Quickstart

Connect to your Inbox, start a conversation from your phone, and reply through the API.

This takes about two minutes and only needs a browser and a terminal. By the end you will have read a real WhatsApp conversation through the API, replied to it, and had the next message pushed to an endpoint of your own.

You need:

The Inbox enabled on your channel — see the Hosted Inbox quickstart if you have not done that yet
A phone with WhatsApp that is not your business number — your personal phone is fine
A URL that can receive a webhook. For testing, any request-inspection service works

Find your Inbox URL

Open the Inbox from the 360dialog Hub. The address in your browser looks like this:

https://your-stack.inbox.getchat.360dialog.io/

That is your Inbox. The API lives under /api/v1/ on the same address. Save it for the next steps:

export INBOX=https://your-stack.inbox.getchat.360dialog.io

Each number has its own Inbox with its own URL. If you have several numbers, you connect to each one separately.

Create a user for the API

Open the admin panel: in the Inbox, open the menu (⋮) in the top right and select Admin panel, or go to $INBOX/hub. Go to Users, select Add user, and fill in:

Username — letters and digits only, such as quickstart
Password — any strong password
Groups — App integration

Save the user.

Get its token

curl -X POST $INBOX/api/v1/auth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=quickstart" \
  --data-urlencode "password=your-password"

The response contains your token. Save it — every call below sends it in the Authorization header:

export SERVICE_TOKEN=your-token

Reference: Create auth token

Check the connection

Ask the Inbox who you are:

curl -H "Authorization: Token $SERVICE_TOKEN" $INBOX/api/v1/users/current/

You get back the user you just created. If you get 403, check that you copied the whole token and kept the Token prefix.

Reference: Retrieve current user

Start a conversation from your phone

If you list your chats now, the list is empty. The API only returns conversations that already exist, and nobody has written to this number yet.

There is a second reason to start from your phone: WhatsApp only lets a business send a free-form message once the customer has written first. That first message opens a conversation window, and inside it you can reply with anything.

So write first yourself. In the Inbox, select Open in WhatsApp and scan the QR code with your phone, or simply send a WhatsApp message to your business number. Say Hi.

List your chats

curl -H "Authorization: Token $SERVICE_TOKEN" $INBOX/api/v1/chats/

Your conversation is there, with one new message. Trimmed down, it looks like this:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "contact": {
        "wa_id": "4915112345678",
        "bsuid": "DE.13491208655302741918",
        "phone_number": "4915112345678",
        "messaging_window_expires_at": 1759237200
      },
      "new_messages": 1
    }
  ]
}

The contact carries up to three identifiers:

wa_id is the ID you pass to every other call. It is either the person's phone number (international format, no +) or, when WhatsApp does not share their number with you — for example because they use a WhatsApp username — their Business-Scoped User ID (BSUID), such as US.13491208655302741918. Treat it as an opaque string: store it and pass it back exactly as you received it, and never parse it as a phone number.
bsuid is the Business-Scoped User ID. It is stable for this person and your business, so it is the most reliable ID to store long-term.
phone_number is filled in only when WhatsApp shares the number. It can be empty.

See Contacts for which one to store, and Usernames & BSUID for when WhatsApp hides a phone number.

messaging_window_expires_at tells you until when you can send free-form replies. Save the wa_id from your own response:

export WA_ID="<wa_id from your response>"

Reference: List chats

Read the conversation

curl -H "Authorization: Token $SERVICE_TOKEN" "$INBOX/api/v1/messages/?wa_id=$WA_ID&limit=20"

Messages come back newest first. Each one carries the original WhatsApp message in waba_payload, and from_us tells you who sent it — false for your Hi.

Reference: List messages

Reply

curl -X POST $INBOX/api/v1/messages/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wa_id": "'"$WA_ID"'", "type": "text", "text": {"body": "Hello from the Inbox API"}}'

The API answers 202 Accepted: the message is queued, not yet delivered.

Check your phone. The reply is there, sent from your business number. Now open the hosted Inbox: the same reply is in the chat, because the API and the hosted Inbox share one backend.

Reference: Create message

Get the next message pushed to you

Polling works, but you want to be told. Register a webhook for incoming messages:

curl -X POST $INBOX/api/v1/webhooks/waba/ \
  -H "Authorization: Token $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-endpoint.example.com/whatsapp", "on_incoming_message": true}'

Send another message from your phone. Within a second, your endpoint receives it in the standard WhatsApp webhook format, with a few Inbox fields added.

Reference: Create webhook

If a reply fails with 453, the conversation window has closed and only a template can go through. See The customer service window.

What to do next

Authentication — why each of your services should have its own user and token
Receiving messages — get new messages delivered to your endpoint
Sending messages — replies when the window is open, templates when it is closed
Playbooks — complete setups for the most common integrations

PreviousInbox API

NextAuthentication

Last updated 5 days ago

Was this helpful?