Codique

DevelopersSend messages with the API

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.

Terminal
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"}}'
Response (201 created, or 200 if it existed)
{ "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

Terminal
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.

Text
{ "type": "text", "text": "Your order is out for delivery 🚚" }
Image or document
{ "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", … } }.
  • 400 with TEMPLATE_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.