Developers · REST API
Send messages with the API
Find or create a contact, then send templates, text and media.
On this page
Use this when your system needs to work with conversations: reply in a thread, send media, or message a contact your team also talks to. For one-off notifications such as OTPs, connected apps are simpler.
Scopes: contact:create, inbox:send and template:read.
1. Find or create the contact
Creating a contact that already exists updates it instead. Either way, the response includes the conversation_id you send to.
curl -X POST https://api.example.com/api/v1/contacts \ -H "Authorization: Bearer $CODIQUE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone": "919876543210", "name": "Aarav Shah", "attributes": {"customer_id": "C-1042"}}'{ "id": "…", "wa_id": "919876543210", "name": "Aarav Shah", …, "conversation_id": "<conversation-id>" }Optional phone_number_id picks which of your business numbers the thread uses; otherwise the default.
2. Find out what a template needs
curl "https://api.example.com/api/v1/templates/resolve?name=order_shipped&language=en_US" \ -H "Authorization: Bearer $CODIQUE_API_KEY"The response has the template, a variables list with an id for each value to fill (such as body:1 or button:0:1) and a preview rendered with sample values.
3. Send a template
Pass values by their variable id. Outside the 24-hour window, a template is the only thing you can send.
curl -X POST https://api.example.com/api/v1/conversations/<conversation-id>/messages \ -H "Authorization: Bearer $CODIQUE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "template", "client_message_id": "order-4421-shipped", "template": { "name": "order_shipped", "languageCode": "en_US", "variables": { "body:1": "Aarav", "body:2": "#4421", "button:0:1": "4421" } } }'4. Reply with text or media
Inside the 24-hour window you can send anything.
{ "type": "text", "text": "Your order is out for delivery 🚚" }{ "type": "image", "media": { "link": "https://files.example.com/receipt.png", "caption": "Your receipt" } }{ "type": "document", "media": { "link": "https://files.example.com/INV-1042.pdf", "filename": "INV-1042.pdf" } }Other types: video, audio, sticker, location, contacts and interactive (buttons and lists).
Safe retries
Add a client_message_id (8–64 letters, digits, _ or -) that is unique per message, such as your own event ID. If you send the same one again to the same conversation, you get the original result back and nothing is sent twice.
Responses
200:{ "message": { "id", "status": "sent", … } }.400withTEMPLATE_VALUES_MISSING: a variable is missing; the error lists which.502: WhatsApp refused the message. The error explains why, and the message is saved as failed in the thread.
Delivery and read updates arrive through outbound webhooks, or by reading the conversation’s messages.
Still stuck? Contact us with what you were doing and the exact message you saw.