Skip to main content

​
Send Your First WhatsApp Message

Get started with WhatsApp Business messaging via Telnyx in minutes. This guide covers account setup, template creation, and sending your first message with delivery confirmation.

​
Prerequisites

Before sending WhatsApp messages, ensure you have:
  • Telnyx Account — Sign up and verify your account
  • Meta Business Manager Account — Required for WhatsApp Business Platform access
  • WhatsApp Business Account (WABA) — Connected via Telnyx’s Embedded Signup
  • Verified phone number — Added to your WABA and verified with Meta
WhatsApp Business Platform requires business verification through Meta’s process. Personal WhatsApp accounts cannot send template messages via the API.
1

Set up your Telnyx account

  1. Create a Telnyx account and verify your email
  2. Navigate to the Portal and complete account verification
  3. Add billing information to enable message sending
  4. Generate an API key from Developer Center → API Keys → Create API Key
Store your API key securely — you’ll need it for all API requests.
2

Connect WhatsApp Business Account

Complete the WhatsApp Embedded Signup to connect your Meta Business Manager:
  1. Navigate to Messaging → WhatsApp in the Telnyx Portal
  2. Click Connect WhatsApp Business Account
  3. Sign in with your Facebook Business Manager credentials
  4. Select the Business Manager account to connect
  5. Follow Meta’s prompts to create or select a WhatsApp Business Account
  6. Verify your business phone number when prompted
Use a Telnyx number with an active messaging profile that you haven’t used with personal WhatsApp. The embedded signup flow currently requires Telnyx-owned numbers — bring-your-own-number is not yet supported through the portal.
If you’re registering a landline number, choose phone call verification instead of SMS when prompted. SMS delivery to landline numbers can be unreliable — call verification is more consistent.
3

Create your first message template

WhatsApp requires pre-approved templates for outbound marketing and notifications:
Set a display name for the phone number before submitting templates. Templates submitted from numbers without an approved display name are rejected by Meta.
When a template contains parameters (e.g., \{\{1\}\}), provide sample values in the example field. Meta reviewers use these to evaluate the template. Without sample values, templates are typically rejected.
Complete the business profile (website, description, industry category) before submitting templates. Incomplete profiles increase rejection rates, especially for new WhatsApp Business Accounts.
Create a message template using the API:
curl -X POST "https://api.telnyx.com/v2/whatsapp/message_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "category": "MARKETING",
    "language": "en_US",
    "waba_id": "YOUR_WABA_ID",
    "components": [
      {
        "type": "BODY",
        "text": "Hello {{1}}! Welcome to our WhatsApp updates.",
        "example": {
          "body_text": [["John"]]
        }
      }
    ]
  }'

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const template = await client.whatsapp.templates.create({
  name: 'welcome_message',
  category: 'MARKETING', 
  language: 'en_US',
  waba_id: 'YOUR_WABA_ID',
  components: [
    {
      type: 'BODY',
      text: 'Hello {{1}}! Welcome to our WhatsApp updates.',
      example: {
        body_text: [['John']]
      }
    }
  ]
});

from telnyx import Telnyx
client = Telnyx(api_key='YOUR_API_KEY')

template = client.whatsapp.templates.create(
    name='welcome_message',
    category='MARKETING',
    language='en_US', 
    waba_id='YOUR_WABA_ID',
    components=[
        {
            'type': 'BODY',
            'text': 'Hello {{1}}! Welcome to our WhatsApp updates.',
            'example': {
                'body_text': [['John']]
            }
        }
    ]
)

require 'telnyx'

telnyx.whatsapp.templates.create(
  name: 'welcome_message',
  category: 'MARKETING',
  language: 'en_US',
  waba_id: 'YOUR_WABA_ID', 
  components: [
    {
      type: 'BODY',
      text: 'Hello {{1}}! Welcome to our WhatsApp updates.',
      example: {
        body_text: [['John']]
      }
    }
  ]
)
Meta typically reviews templates within 24-48 hours. You’ll receive an email when approved.
Start with simple templates for faster approval. Avoid promotional language or special characters in your first template.
4

Send your first WhatsApp message

Once your template is approved, send your first message:
curl -X POST "https://api.telnyx.com/v2/messages/whatsapp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15557654321",
    "whatsapp_message": {
      "type": "template",
      "template": {
        "name": "welcome_message",
        "language": {
          "policy": "deterministic",
          "code": "en_US"
        },
        "components": [
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "John"
              }
            ]
          }
        ]
      }
    }
  }'

from telnyx import Telnyx
client = Telnyx(api_key='YOUR_API_KEY')

response = client.messages.send_whatsapp(
    from_="+15551234567",
    to="+15557654321",
    whatsapp_message={
        "type": "template",
        "template": {
            "name": "welcome_message",
            "language": {
                "policy": "deterministic",
                "code": "en_US"
            },
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text", 
                            "text": "John"
                        }
                    ]
                }
            ]
        }
    }
)

print(f"Message ID: {response.data.id}")
print(f"Status: {response.data.to[0].status}")

import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const message = await client.messages.sendWhatsapp({
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'template',
    template: {
      name: 'welcome_message',
      language: {
        policy: 'deterministic',
        code: 'en_US'
      },
      components: [
        {
          type: 'body',
          parameters: [
            {
              type: 'text',
              text: 'John'
            }
          ]
        }
      ]
    }
  }
});

console.log(`Message ID: ${message.data.id}`);
console.log(`Status: ${message.data.to[0].status}`);

require 'telnyx'

response = telnyx.messages.send_whatsapp(
  from: '+15551234567',
  to: '+15557654321',
  whatsapp_message: {
    type: 'template',
    template: {
      name: 'welcome_message',
      language: {
        policy: 'deterministic',
        code: 'en_US'
      },
      components: [
        {
          type: 'body',
          parameters: [
            {
              type: 'text',
              text: 'John'
            }
          ]
        }
      ]
    }
  }
)

puts "Message ID: #{response.data.id}"
puts "Status: #{response.data.to[0].status}"

package main

import (
    "context"
    "fmt"
    "github.com/team-telnyx/telnyx-go/v2"
)

func main() {
    client := telnyx.NewAPIClient(telnyx.NewConfiguration())
    client.GetConfig().AddDefaultHeader("Authorization", "Bearer YOUR_API_KEY")
    
    parameters := []telnyx.TemplateParameter{
        {
            Type: telnyx.PtrString("text"),
            Text: telnyx.PtrString("John"),
        },
    }
    
    components := []telnyx.TemplateComponent{
        {
            Type:       telnyx.PtrString("body"),
            Parameters: parameters,
        },
    }
    
    template := telnyx.WhatsAppTemplate{
        Name: telnyx.PtrString("welcome_message"),
        Language: &telnyx.TemplateLanguage{
            Policy: telnyx.PtrString("deterministic"),
            Code:   telnyx.PtrString("en_US"),
        },
        Components: components,
    }
    
    whatsappMessage := telnyx.WhatsAppMessageContent{
        Type:     telnyx.PtrString("template"),
        Template: &template,
    }
    
    params := telnyx.MessageSendWhatsappParams{
        From:            "+15551234567",
        To:              "+15557654321",
        WhatsappMessage: whatsappMessage,
    }
    
    response, err := client.Messages.SendWhatsapp(context.TODO(), params)
    
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Message ID: %s\n", response.Data.Id)
    fmt.Printf("Status: %s\n", response.Data.To[0].Status)
}

import com.telnyx.sdk.ApiClient;
import com.telnyx.sdk.ApiException;
import com.telnyx.sdk.Configuration;
import com.telnyx.sdk.auth.HttpBearerAuth;
import com.telnyx.sdk.api.MessagesApi;
import com.telnyx.sdk.model.*;
import java.util.Arrays;

public class WhatsAppQuickstart {
    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        HttpBearerAuth bearerAuth = (HttpBearerAuth) defaultClient.getAuthentication("bearerAuth");
        bearerAuth.setBearerToken("YOUR_API_KEY");
        
        MessagesApi apiInstance = new MessagesApi(defaultClient);
        
        TemplateParameter parameter = new TemplateParameter()
            .type("text")
            .text("John");
            
        TemplateComponent component = new TemplateComponent()
            .type("body")
            .parameters(Arrays.asList(parameter));
            
        TemplateLanguage language = new TemplateLanguage()
            .policy("deterministic")
            .code("en_US");
            
        WhatsAppTemplate template = new WhatsAppTemplate()
            .name("welcome_message")
            .language(language)
            .components(Arrays.asList(component));
            
        WhatsAppMessageContent whatsappMessage = new WhatsAppMessageContent()
            .type("template")
            .template(template);
        
        MessageSendWhatsappRequest request = new MessageSendWhatsappRequest()
            .from("+15551234567")
            .to("+15557654321")
            .whatsappMessage(whatsappMessage);
        
        try {
            var result = apiInstance.sendWhatsapp(request);
            System.out.println("Message ID: " + result.getData().getId());
            System.out.println("Status: " + result.getData().getTo().get(0).getStatus());
        } catch (ApiException e) {
            System.err.println("Exception: " + e.getResponseBody());
        }
    }
}
The messaging profile is automatically resolved from your WhatsApp-enabled phone number specified in the from field.
5

Set up webhook notifications

Configure webhooks to receive real-time delivery status updates:
  1. In the Telnyx Portal, navigate to Messaging → Messaging Profiles
  2. Select your messaging profile
  3. Set Webhook URL to your endpoint (e.g., https://yourapp.com/webhooks/telnyx)
  4. Enable Failover URL for redundancy (optional)
  5. Save the configuration
Your webhook endpoint will receive delivery reports and inbound message notifications.
6

Handle webhook events

Implement webhook handling to track message status and respond to inbound messages:
from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhooks/telnyx', methods=['POST'])
def handle_webhook():
    webhook_data = request.json
    event_type = webhook_data['data']['event_type']
    payload = webhook_data['data']['payload']
    
    if event_type == 'message.sent':
        print(f"WhatsApp message sent: {payload['id']}")
        print(f"Status: {payload.get('to', [{}])[0].get('status', 'unknown')}")
        
    elif event_type == 'message.received':
        print(f"WhatsApp message received: {payload['text']}")
        print(f"From: {payload['from']}")
        
        # Auto-reply during 24-hour window
        reply_to_customer(payload['from'], payload['to'])
    
    return '', 200

def reply_to_customer(customer_number, business_number):
    from telnyx import Telnyx
    client = Telnyx(api_key="YOUR_API_KEY")
    
    # Send free-form message (no template required in 24hr window)
    client.messages.send_whatsapp(
        from_=business_number,
        to=customer_number,
        whatsapp_message={
            "type": "text",
            "text": {
                "body": "Thanks for your message! We'll get back to you soon.",
                "preview_url": False
            }
        }
    )

if __name__ == '__main__':
    app.run(debug=True)

const express = require('express');
import Telnyx from 'telnyx';
const client = new Telnyx({apiKey: 'YOUR_API_KEY'});

const app = express();
app.use(express.json());

app.post('/webhooks/telnyx', async (req, res) => {
  const { data } = req.body;
  const { event_type, payload } = data;
  
  if (event_type === 'message.sent') {
    console.log(`WhatsApp message sent: ${payload.id}`);
    console.log(`Status: ${payload.to[0]?.status || 'unknown'}`);
    
  } else if (event_type === 'message.received') {
    console.log(`WhatsApp message received: ${payload.text}`);
    console.log(`From: ${payload.from}`);
    
    // Auto-reply during 24-hour window
    await replyToCustomer(payload.from, payload.to);
  }
  
  res.status(200).send();
});

async function replyToCustomer(customerNumber, businessNumber) {
  try {
    await client.messages.sendWhatsapp({
      from: businessNumber,
      to: customerNumber,
      whatsapp_message: {
        type: 'text',
        text: {
          body: "Thanks for your message! We'll get back to you soon.",
          preview_url: false
        }
      }
    });
  } catch (error) {
    console.error('Error sending reply:', error);
  }
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

​
Verify Message Delivery

Check message delivery through multiple channels:

​
Portal Dashboard

  1. Navigate to Messaging → Message Logs in the Telnyx Portal
  2. Filter by Channel: WhatsApp and Date Range
  3. View delivery status, timestamps, and any error codes
  4. Click individual messages for detailed delivery information

​
Webhook Events

Monitor these key webhook events:
  • message.sent — Message successfully submitted to WhatsApp
  • message.delivered — Message delivered to recipient’s device
  • message.read — Recipient opened and read the message (when enabled by recipient)
  • message.failed — Message delivery failed (with error details)

​
API Response

The initial API response includes: 
{
  "data": {
    "id": "msg_123abc",
    "to": [
      {
        "phone_number": "+15557654321",
        "status": "queued",
        "carrier": "WhatsApp"
      }
    ]
  }
}

​
Common Issues

Symptoms: API returns a 40008 error indicating the template was not found or not approvedSolutions:
  • Verify template status in Portal under Messaging → WhatsApp → Send Messages
  • Ensure template name matches exactly (case-sensitive)
  • Wait for Meta’s approval (typically 24-48 hours for first templates)
  • Review Meta’s template guidelines for approval requirements
Symptoms: API returns a 40008 error indicating the sender phone number is not registered with WhatsAppSolutions:
  • Complete phone number verification in the Telnyx Portal
  • Ensure number is added to your WhatsApp Business Account
  • Verify the number through Meta’s verification process
  • Check that the number hasn’t been used with personal WhatsApp
Symptoms: Free-form (session) message fails with a 40008 error. WhatsApp requires a template to initiate conversations outside the 24-hour windowSolutions:
  • Use approved message templates for outbound messaging
  • Only send free-form messages within 24 hours of customer’s last message
  • Check conversation window status via webhook events
  • Consider switching to template-based messaging for customer re-engagement
Symptoms: Message status webhook returns undeliverable with Meta API error details in the responseSolutions:
  • Verify recipient has WhatsApp installed and active
  • Ensure phone number format includes country code (+1…)
  • Check that recipient hasn’t blocked your business number
  • Confirm recipient’s WhatsApp account is not banned or restricted

​
Next Steps

Send Messages

Send templates, text, media, and interactive messages

Embedded Signup

Set up your WhatsApp Business Account and verify your number

Receiving Webhooks

Handle inbound messages and delivery status callbacks