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 AccountSign 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 phone number you control and haven’t used with personal WhatsApp. Business numbers cannot be used with personal WhatsApp accounts.
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.
  1. In the Telnyx Portal, navigate to Messaging → WhatsApp → Send Messages
  2. Click Create Template
  3. Configure your template:
    • Name: welcome_message (lowercase, underscores only)
    • Category: Marketing
    • Language: English (US)
    • Body: Hello {{1}}! Welcome to our WhatsApp updates.
    • Example Values: Provide sample data for the {{1}} parameter
  4. Click Submit for Review
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"
              }
            ]
          }
        ]
      }
    }
  }'
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):
    import telnyx
    telnyx.api_key = "YOUR_API_KEY"
    
    # Send free-form message (no template required in 24hr window)
    telnyx.WhatsApp.create(
        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)

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
  • 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 41000 error (WhatsApp 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 41000 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 41000 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