👋 Welcome to the Chatbots Africa WhatsApp API
With this API you can:
Reach more than 1.5 billion WhatsApp users directly from your own systems.
- Send text, media, interactive lists, quick replies, WhatsApp Flows, and Meta-approved message templates
- Track delivery status, campaign performance, and wallet balance programmatically
- Integrate with your CRM, ERP, or any backend capable of making an HTTP request
Getting Started
Create a chatbot from your dashboard and submit it for approval (usually within 24 hours).
Once approved, grab the apikey from your chatbot's settings page.
Use that key to authenticate every request below — there's no separate bearer token.
Base URL
Try it — mock playground
Every endpoint in the sidebar includes a Send Mock Request button. It does not call the live API — no wallet credit is spent and no real WhatsApp message is sent. It simply shows the exact shape of a real request and response so you can integrate with confidence before going live.
Validation Errors
Any endpoint returns 422 with this shape when required fields are missing or invalid:
{
"errors": [
"The apikey field is required.",
"The destination field is required.",
"The message field is required."
]
}Send Text Message
Sends a plain text message to a WhatsApp number.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Text content of the message.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"message": "Hello! Thanks for reaching out to us 👋"
}'// Click "Send Mock Request" to preview a sample response.Send Image Message
Sends an image from a public URL, with an optional caption.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Publicly reachable URL of the image (jpg/png).
Optional caption shown below the image.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/image" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"image_url": "https://picsum.photos/id/237/800/600.jpg",
"caption": "Here is a snapshot of your order"
}'// Click "Send Mock Request" to preview a sample response.Send Document Message
Sends a document (PDF, DOCX, etc.) from a public URL.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Publicly reachable URL of the file.
Filename shown to the recipient.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/document" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"file_url": "https://example.com/files/invoice-4821.pdf",
"caption": "Invoice-4821.pdf"
}'// Click "Send Mock Request" to preview a sample response.Send Audio Message
Sends an audio clip from a public URL.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Publicly reachable URL of the audio file (mp3/ogg).
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/audio" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"audio_url": "https://example.com/audio/voice-note.mp3"
}'// Click "Send Mock Request" to preview a sample response.Send Video Message
Sends a video from a public URL, with an optional caption.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Publicly reachable URL of the video (mp4).
Optional caption shown below the video.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/video" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"video_url": "https://example.com/video/product-demo.mp4",
"caption": "Quick demo of the new feature"
}'// Click "Send Mock Request" to preview a sample response.Send Sticker Message
Sends a WebP sticker from a public URL.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Publicly reachable URL of the sticker (webp).
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/sticker" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"sticker_url": "https://example.com/stickers/thumbs-up.webp"
}'// Click "Send Mock Request" to preview a sample response.Send Location Message
Sends a pinned location.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Latitude coordinate.
Longitude coordinate.
Label shown for the pin.
Address text shown under the label.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/location" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"latitude": "5.614818",
"longitude": "-0.208811",
"name": "Mega HQ",
"address": "12 Independence Ave, Accra"
}'// Click "Send Mock Request" to preview a sample response.Send Contact Message
Shares one or more contact cards, in WhatsApp's native contacts format.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
Array of contact objects (WhatsApp contacts schema).
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/contact" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"contacts": [
{
"name": {
"formatted_name": "Kwame Mensah",
"first_name": "Kwame",
"last_name": "Mensah"
},
"phones": [
{
"phone": "+233241234567",
"type": "CELL"
}
]
}
]
}'// Click "Send Mock Request" to preview a sample response.Send List Message
Sends an interactive list of selectable options. The `interactive` field must be a JSON-encoded string (not a nested object).
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
JSON string: {type, title, body, footer?, globalButtons[0].title, items[].title, items[].options[].{postbackText,title,description}}.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/list/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"interactive": "{\"type\":\"list\",\"title\":\"Our Menu\",\"body\":\"Choose an option below\",\"footer\":\"Powered by Mega\",\"globalButtons\":[{\"title\":\"View Options\"}],\"items\":[{\"title\":\"Popular\",\"options\":[{\"postbackText\":\"opt_pizza\",\"title\":\"Pizza\",\"description\":\"Large pepperoni pizza\"},{\"postbackText\":\"opt_burger\",\"title\":\"Burger\",\"description\":\"Beef burger with fries\"}]}]}"
}'// Click "Send Mock Request" to preview a sample response.Send Flow Message
Launches a WhatsApp Flow. The `interactive` field must be a JSON-encoded string (not a nested object).
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
JSON string: {title, body, footer?, flow_token, flow_id, flow_cta, screen}.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/flow/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"interactive": "{\"type\":\"flow\",\"title\":\"Book an appointment\",\"body\":\"Tap below to pick a time that works for you.\",\"footer\":\"Mega Clinic\",\"flow_token\":\"flow_tok_8f21ac\",\"flow_id\":\"1234567890123456\",\"flow_cta\":\"Book Now\",\"screen\":\"APPOINTMENT_SCREEN\"}"
}'// Click "Send Mock Request" to preview a sample response.Send Quick Reply Message
Sends a message with up to a few tappable reply buttons. The `interactive` field must be a JSON-encoded string (not a nested object).
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
JSON string: {content.text, content.caption, options[].title}.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/quick/reply" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"interactive": "{\"content\":{\"text\":\"Would you like to proceed with your order?\",\"caption\":\"Reply below\"},\"options\":[{\"title\":\"Yes, proceed\"},{\"title\":\"No, cancel\"}]}"
}'// Click "Send Mock Request" to preview a sample response.Send Direct Reply Message
Sends a text message as a threaded reply to a previous inbound message.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
The wamid of the message you're replying to.
Text content of the reply.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/reply/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"message_id": "wamid.HBgLMjMzMjQxMjM0NTYVAgASGBI5QjhFQTlFRjdFRjdFRjdFRjcA",
"message": "Thanks for confirming, we'll get that sorted right away."
}'// Click "Send Mock Request" to preview a sample response.Send Message Template
Sends a Meta-approved message template. `template_id` comes from the "List Message Templates" endpoint below.
application/json
Your chatbot API key.
Recipient number, international format without a leading +.
ID of an approved template belonging to your chatbot.
One of: text, image, video, audio, document — matches the template's header type.
Values that fill the template's {{1}}, {{2}}, ... variables, in order. Accepts either a JSON array (recommended) or a comma-separated string. Use an array whenever a value itself contains a comma (an address, a price like "2,450.00", an item list) — splitting a comma-string can shift every value after it. A mismatch between the number of values sent and the number of variables in the template returns a 422 before the message is sent to WhatsApp.
Public media URL — required when type is image/video/audio/document.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/message/template" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"template_id": 42,
"type": "text",
"placeholder": [
"Kwame",
"ORD-4821"
]
}'// Click "Send Mock Request" to preview a sample response.List Message Templates
Returns every approved template owned by your chatbot, with its content, CTA buttons and quick replies.
application/json
Your chatbot API key.
curl -G "https://api.chatbotsafrica.com/api/v1.0/send/template/list" \
--data-urlencode "apikey=wa_live_9f2c7a1e4b6d8f3a"// Click "Send Mock Request" to preview a sample response.Retrieve Media URL
Looks up a media object by the ID Meta sent in an inbound message webhook (e.g. an image a customer sent you), and proxies the file back.
application/json
Your chatbot API key.
The media ID from an inbound webhook payload.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/get/media/url" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"media_id": "1284759385621047"
}'// Click "Send Mock Request" to preview a sample response.Download Media
Downloads the file a customer sent to your bot (image, document, audio, video or sticker). Pass the media ID from the inbound webhook (messages[0].image.id), or the lookaside url from the webhook. The response body is the raw file with its Content-Type and a Content-Disposition filename. Also accepts POST. Lookaside URLs expire after about 5 minutes, so prefer media_id.
application/json
Your chatbot API key.
The media ID from the inbound webhook. Required if url is not sent.
The https://lookaside.fbsbx.com URL from the inbound webhook. Required if media_id is not sent.
curl -G "https://api.chatbotsafrica.com/api/v1.0/media/download" \
--data-urlencode "apikey=wa_live_9f2c7a1e4b6d8f3a" \
--data-urlencode "media_id=1284759385621047"// Click "Send Mock Request" to preview a sample response.Get Wallet Balance
Returns the current credit balance for your account.
application/json
Your chatbot API key.
curl -G "https://api.chatbotsafrica.com/api/v1.0/wallet/balance" \
--data-urlencode "apikey=wa_live_9f2c7a1e4b6d8f3a"// Click "Send Mock Request" to preview a sample response.Get Delivery Report
Returns the delivery status and billing details for a single message.
application/json
Your chatbot API key.
The wamid returned when the message was sent.
curl -G "https://api.chatbotsafrica.com/api/v1.0/delivery/report" \
--data-urlencode "apikey=wa_live_9f2c7a1e4b6d8f3a" \
--data-urlencode "message_id=wamid.HBgLMjMzMjQxMjM0NTYVAgARGBI1RjhFQTlFRjdFRjdFRjdFRjcA"// Click "Send Mock Request" to preview a sample response.Opt Contact In/Out
Records a contact's opt-in/opt-out status for business-initiated messaging.
application/json
Your chatbot API key.
Contact number, international format without a leading +.
true to opt in, false to opt out.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/send/opt/contact" \
-H "Content-Type: application/json" \
-d '{
"apikey": "wa_live_9f2c7a1e4b6d8f3a",
"destination": "233241234567",
"status": true
}'// Click "Send Mock Request" to preview a sample response.Send Messenger Text Message
Sends a plain text message to a Messenger user. Requires a chatbot on the `facebook` channel with a connected Page — an apikey belonging to a WhatsApp-channel chatbot is rejected with a 422, and a chatbot with no Page connected yet returns a 409. Messenger only allows free-form sends within 24 hours of the person's last message to your Page.
application/json
Your chatbot API key (must be a facebook-channel chatbot).
Recipient's Page-Scoped ID (PSID) — not a phone number. Obtained from an inbound message webhook.
Text content of the message.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/messenger/send/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "fb_live_2a8e6c1d9f4b7a3e",
"destination": "7042183512345678",
"message": "Hello! Thanks for reaching out to us 👋"
}'// Click "Send Mock Request" to preview a sample response.Send Messenger Image Message
Sends an image from a public URL to a Messenger user.
application/json
Your chatbot API key (must be a facebook-channel chatbot).
Recipient's Page-Scoped ID (PSID).
Publicly reachable URL of the image (jpg/png).
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/messenger/send/image" \
-H "Content-Type: application/json" \
-d '{
"apikey": "fb_live_2a8e6c1d9f4b7a3e",
"destination": "7042183512345678",
"image_url": "https://picsum.photos/id/237/800/600.jpg"
}'// Click "Send Mock Request" to preview a sample response.Send Messenger Button Template
Sends text with up to three tappable buttons (web link or postback) — Messenger's "button template".
application/json
Your chatbot API key (must be a facebook-channel chatbot).
Recipient's Page-Scoped ID (PSID).
Text shown above the buttons.
Array of up to 3 button objects: {type: web_url|postback, title, url|payload} — matches Messenger's button template schema.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/messenger/send/button-template" \
-H "Content-Type: application/json" \
-d '{
"apikey": "fb_live_2a8e6c1d9f4b7a3e",
"destination": "7042183512345678",
"message": "Your order ORD-4821 has shipped!",
"buttons": [
{
"type": "web_url",
"url": "https://example.com/track/ORD-4821",
"title": "Track Order"
},
{
"type": "postback",
"payload": "CANCEL_ORDER",
"title": "Cancel Order"
}
]
}'// Click "Send Mock Request" to preview a sample response.Send Messenger Quick Reply
Sends text with tappable quick-reply chips that disappear after one is tapped.
application/json
Your chatbot API key (must be a facebook-channel chatbot).
Recipient's Page-Scoped ID (PSID).
Text shown above the quick replies.
Array of {content_type: "text", title, payload} objects — matches Messenger's quick_replies schema.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/messenger/send/quick-reply" \
-H "Content-Type: application/json" \
-d '{
"apikey": "fb_live_2a8e6c1d9f4b7a3e",
"destination": "7042183512345678",
"message": "Would you like to proceed with your order?",
"quick_replies": [
{
"content_type": "text",
"title": "Yes, proceed",
"payload": "QR_YES"
},
{
"content_type": "text",
"title": "No, cancel",
"payload": "QR_NO"
}
]
}'// Click "Send Mock Request" to preview a sample response.Send Instagram Text Message
Sends a plain text message to an Instagram user. Requires a chatbot on the `instagram` channel with a connected account — an apikey belonging to a different channel's chatbot is rejected with a 422, and a chatbot with no Instagram account connected yet returns a 409. Instagram only allows free-form sends within 24 hours of the person's last message to your account.
application/json
Your chatbot API key (must be an instagram-channel chatbot).
Recipient's Instagram-Scoped ID (IGSID) — not a username or phone number. Obtained from an inbound message webhook.
Text content of the message.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/instagram/send/message" \
-H "Content-Type: application/json" \
-d '{
"apikey": "ig_live_5c9d2a7e1f4b8c36",
"destination": "17856349021456789",
"message": "Hello! Thanks for reaching out to us 👋"
}'// Click "Send Mock Request" to preview a sample response.Send Instagram Image Message
Sends an image from a public URL to an Instagram user.
application/json
Your chatbot API key (must be an instagram-channel chatbot).
Recipient's Instagram-Scoped ID (IGSID).
Publicly reachable, directly-resolving URL of the image (jpg/png) — a redirecting URL (e.g. most link shorteners) may fail to fetch.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/instagram/send/image" \
-H "Content-Type: application/json" \
-d '{
"apikey": "ig_live_5c9d2a7e1f4b8c36",
"destination": "17856349021456789",
"image_url": "https://fastly.picsum.photos/id/237/800/600.jpg"
}'// Click "Send Mock Request" to preview a sample response.Send Instagram Quick Reply
Sends text with tappable quick-reply chips that disappear after one is tapped.
application/json
Your chatbot API key (must be an instagram-channel chatbot).
Recipient's Instagram-Scoped ID (IGSID).
Text shown above the quick replies.
Array of {content_type: "text", title, payload} objects.
curl -X POST "https://api.chatbotsafrica.com/api/v1.0/instagram/send/quick-reply" \
-H "Content-Type: application/json" \
-d '{
"apikey": "ig_live_5c9d2a7e1f4b8c36",
"destination": "17856349021456789",
"message": "Would you like to proceed with your order?",
"quick_replies": [
{
"content_type": "text",
"title": "Yes, proceed",
"payload": "QR_YES"
},
{
"content_type": "text",
"title": "No, cancel",
"payload": "QR_NO"
}
]
}'// Click "Send Mock Request" to preview a sample response.