> This page is for Omni Channel.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Quickstart

> Create an API key and send your first WhatsApp template from your own system in 3 steps.

The developer API lets your own systems send messages and templates, and read and change the conversations and contacts of your account. Every endpoint is under `https://omni-channel.hams.ai/api/v1/accounts/{account_id}/developer`. The API accepts 1 credential only: an API key that an administrator creates for the account.

> **Note**
>
> Only administrators can see **Settings** > **Developer** and create or delete API keys. The developer API has no feature flag. It is available on every account.

## 1. Create an API key

#### Open the API keys

Open **Settings** > **Developer**. The page is at `/app/accounts/{account_id}/settings?tab=developer`. The **API keys** list opens.

#### Create the key

Click **Create API key**. In **Name**, type the name of the system that uses the key, for example `Billing service`. Click **Create key**.

#### Copy the token

The dialog **Your API key is ready** shows the **Token**. Copy the token. Click **Done**.

The name of the key is the sender name of every message that the key sends. Your agents see this name in the conversation. It tells them that a system sent the message, not an agent.

An account can have 5 API keys. To see the token of a key again, click **View token** on the row of the key. To revoke a key, click **Delete** on its row. The token stops immediately, and every integration that uses it stops.

Put the token in your shell:

```bash
export HAMS_TOKEN=your_token_here
```

Send the token in the `api_access_token` header of every request. A personal access token of a user does not work on the developer API. The API rejects it with `401`.

> **Warning**
>
> Create 1 key for each integration. A key reaches every inbox, conversation, and contact in the account. If each integration has its own key, you can revoke 1 key and the other integrations continue to work.

## 2. Find your account id and inbox id

Open the inbox settings in the dashboard. Read the 2 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 template

A first message to a new WhatsApp number must be an approved WhatsApp template. Run this request with your own ids, phone number, and template:

```bash
curl -X POST https://omni-channel.hams.ai/api/v1/accounts/1/developer/messages \
  -H "api_access_token: $HAMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": 5,
    "phone_number": "+971500000000",
    "template_params": {
      "name": "order_confirmation",
      "language": "en",
      "category": "UTILITY",
      "processed_params": { "body": { "1": "121212" } }
    }
  }'
```

The API answers `201` with this body:

```json
{
  "id": 88,
  "conversation_id": 1234,
  "contact_id": 42,
  "inbox_id": 5,
  "status": "sent",
  "content": "Hi, your order 121212 is confirmed",
  "created_at": 1755500000
}
```

The API created the contact and the conversation. It made `content` from the body of the approved template. See [Templates](/omni-channel/api/templates).

Keep the `conversation_id`. It is the conversation number that your agents see in the dashboard URL. All the conversation endpoints take this number. See [Conversations](/omni-channel/api/conversations).

## What happens next

`201` means that the API saved the message and put it in the delivery queue. It does not mean that the channel delivered it. The message shows in the conversation in the dashboard, with its delivery status. The developer API has no delivery callback. To see the delivery status, open the conversation in the dashboard.

## Rate limit

By default, each key can send 300 requests each minute. Each key has its own limit. If a key sends more, the API answers `429`. See [Errors](/omni-channel/api/errors).

## Related

* [Messages](/omni-channel/api/messages)
* [Templates](/omni-channel/api/templates)
* [Conversations](/omni-channel/api/conversations)
* [Errors](/omni-channel/api/errors)