> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/inbox/inbox-api/quickstart.md).

# 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](/docs/inbox/hosted-inbox/quickstart.md) 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

{% stepper %}
{% step %}
**Find your Inbox URL**

Open the Inbox from the [360dialog Hub](https://app.360dialog.com/inbox). 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:

```bash
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.
{% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**Get its token**

```bash
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:

```bash
export SERVICE_TOKEN=your-token
```

Reference: [Create auth token](/docs/inbox/inbox-api/api-ref/authorization.md#post-api-v1-auth-token)
{% endstep %}

{% step %}
**Check the connection**

Ask the Inbox who you are:

```bash
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](/docs/inbox/inbox-api/api-ref/users.md#get-api-v1-users-current)
{% endstep %}

{% step %}
**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](/docs/inbox/the-customer-service-window.md), 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*.
{% endstep %}

{% step %}
**List your chats**

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

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

```json
{
  "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](/docs/inbox/inbox-api/contacts.md) for which one to store, and [Usernames & BSUID](https://docs.360dialog.com/docs/resources/phone-numbers/usernames-and-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:

```bash
export WA_ID="<wa_id from your response>"
```

Reference: [List chats](/docs/inbox/inbox-api/api-ref/chats.md#get-api-v1-chats)
{% endstep %}

{% step %}
**Read the conversation**

```bash
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](/docs/inbox/inbox-api/api-ref/messages.md#get-api-v1-messages)
{% endstep %}

{% step %}
**Reply**

```bash
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](/docs/inbox/inbox-api/api-ref/messages.md#post-api-v1-messages)
{% endstep %}

{% step %}
**Get the next message pushed to you**

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

```bash
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](/docs/inbox/inbox-api/api-ref/webhooks.md#post-api-v1-webhooks-waba)
{% endstep %}
{% endstepper %}

{% hint style="info" %}
If a reply fails with `453`, the conversation window has closed and only a template can go through. See [The customer service window](/docs/inbox/the-customer-service-window.md).
{% endhint %}

## What to do next

* [Authentication](/docs/inbox/inbox-api/authentication.md) — why each of your services should have its own user and token
* [Receiving messages](/docs/inbox/inbox-api/receiving-messages.md) — get new messages delivered to your endpoint
* [Sending messages](/docs/inbox/inbox-api/sending-messages.md) — replies when the window is open, templates when it is closed
* [Playbooks](/docs/inbox/inbox-api/playbooks.md) — complete setups for the most common integrations


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.360dialog.com/docs/inbox/inbox-api/quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.