Developer API

Quickstart

In three steps you will send a WhatsApp template to a phone number and get back the conversation your agents see in the dashboard.

1. Create an API key

Go to Settings > Developer, create a key, and copy its token. Name it after the system that will use it: the name is what your agents see on every message the key sends, so they can tell an automated send from an agent reply. An account can hold five keys, and deleting one revokes its token immediately.

A personal user token, from Profile Settings > Access Token, works the same way and is useful while you experiment.

Put the token in your shell:

$export HAMS_TOKEN=your_token_here

A key reaches one account and every inbox, conversation and contact in it. Read Errors for the full scope.

2. Find your account and inbox ids

Open the inbox in the dashboard and read both ids from the URL. In /app/accounts/1/settings/inboxes/5, the account id is 1 and the inbox id is 5.

3. Send a message

Run this with your own host, ids, and phone number:

$curl -X POST https://your-installation.example.com/api/v1/accounts/1/developer/messages \
>  -H "api_access_token: $HAMS_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "inbox_id": 5,
>    "phone_number": "+971500000000",
>    "content": "Hi, your order 121212 is confirmed",
>    "template_params": {
>      "name": "order_confirmation",
>      "language": "en",
>      "category": "UTILITY",
>      "processed_params": { "body": { "1": "121212" } }
>    }
>  }'

You get back 201 and this body:

1{
2  "id": 88,
3  "conversation_id": 1234,
4  "contact_id": 42,
5  "inbox_id": 5,
6  "status": "sent",
7  "content": "Hi, your order 121212 is confirmed",
8  "created_at": 1755500000
9}

The API created the contact and the conversation. Keep the conversation_id. Your agents see the same id, and you use it later to reply, label, assign, or resolve the thread. See Managing conversations.

The first message to a number you have never spoken to must be a template. See Sending templates for why.

What happens next

201 means the API created the message row and handed it to the delivery queue. The channel confirms delivery a moment later, and the message appears in the dashboard either way. This version of the API has no delivery callback. To confirm delivery, open the conversation in the dashboard.