Send WhatsApp Message

Send text messages to WhatsApp users. Free-form text is only permitted inside the 24-hour customer service window (after the user has messaged you). To start a conversation, send a template first.

📡 Endpoint

POST /v1/whatsapp/messages

📥 Parameters

Field	Type	Required	Description
to	string	Yes	Recipient phone number in E.164 format
type	string	Yes	Message type — text for this endpoint
text.body	string	Yes	Message content (max 4096 characters)
text.preview_url	boolean	No	Render a link preview for URLs in the body
context.message_id	string	No	Reply to a specific inbound message (quoted reply)

🚀 Quick Start

curl -X POST https://api.afriroute.ai/api/v1/whatsapp/messages \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+251911234567",
    "type": "text",
    "text": {
      "body": "Thanks for your order! Your tracking number is #12345.",
      "preview_url": true
    }
  }'

💻 Code Samples

const response = await fetch('https://api.afriroute.ai/api/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+251911234567',
    type: 'text',
    text: {
      body: 'Hello from AfriRoute!',
      preview_url: false
    }
  })
});

const data = await response.json();
console.log(data.message_id); // wamid.HBgM...

import requests

response = requests.post(
    'https://api.afriroute.ai/api/v1/whatsapp/messages',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'to': '+251911234567',
        'type': 'text',
        'text': {'body': 'Hello from AfriRoute!'}
    }
)
print(response.json()['message_id'])

📊 Response

{
  "messaging_product": "whatsapp",
  "message_id": "wamid.HBgMMjUxOTExMjM0NTY3",
  "to": "+251911234567",
  "status": "accepted",
  "timestamp": "2026-05-28T10:30:00Z"
}

🔁 Quoted Replies

Reply to a specific inbound message by passing its wamid in context:

{
  "to": "+251911234567",
  "type": "text",
  "context": { "message_id": "wamid.HBgM_inbound_id" },
  "text": { "body": "Replying to your earlier question." }
}

🔎 Check Message Status

GET /v1/whatsapp/messages/:message_id

{
  "message_id": "wamid.HBgMMjUxOTExMjM0NTY3",
  "status": "delivered",
  "to": "+251911234567",
  "sent_at": "2026-05-28T10:30:00Z",
  "delivered_at": "2026-05-28T10:30:03Z"
}

Delivery and read receipts are also pushed in real time via webhooks.

💡 Best Practices

• Send a template first if the user has not messaged you in the last 24 hours.
• Keep the body under 4096 characters — longer text is rejected.
• Set preview_url: true only when the link preview adds value.
• Use quoted replies in busy threads so the user has context.
• Handle status webhooks rather than polling for accurate tracking.

⚠️ Error Handling

try {
  await sendTextMessage(data);
} catch (error) {
  if (error.code === 131047) {
    console.error('Re-engagement message — 24h window expired, send a template');
  } else if (error.code === 130472) {
    console.error('Recipient is not a WhatsApp user');
  }
}

Code	Description	Solution
131047	24-hour window expired	Send an approved template
130472	Not a WhatsApp user	Verify the number
133004	Undeliverable	Check E.164 format

📚 Related Resources

• Templates — start conversations outside the window
• Media Messages
• Interactive Messages
• Webhooks

---

Need help? Contact Support → | Last Updated: May 2026