Skip to navigation
Developer API

Quickstart

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.

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

1

Open the API keys

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

2

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.

3

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:

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.

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:

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:

{
  "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.

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.

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.