# Amomic-AI — complete documentation

> Generated from https://docs.amomic.in · 2026-08-01
> This file contains every documentation page in full, in reading order.



============================================================================
# SECTION: Get started
============================================================================



----------------------------------------------------------------------------
## Quickstart
URL: https://docs.amomic.in/start/quickstart
----------------------------------------------------------------------------

This walks you from an empty workspace to an agent answering real questions on your website. It takes about five minutes and needs nothing installed.

If you'd rather start from your own backend, go to [Your first API call](/start/first-api-call) instead — but do this first anyway. The API sends messages *from* an agent, so you need an agent before the API is useful.

::: steps

::: step Create an agent

In the console, open **Agents** and choose **New agent**. Two fields matter:

- **Agent name** — what your team calls it. `Support Agent` is fine.
- **Purpose** — what outcome this agent owns. Describe the job, not the channel:

  > Resolve common support questions using approved company information.

The purpose is not decoration. It becomes the spine of the agent's instructions, and a vague purpose produces a vague agent. "Help customers" is vague. "Answer delivery, refund, and order-status questions from our published policy, and hand off anything about billing" is not.

Leave **Business knowledge** on *Require a ready knowledge base before publishing*. That setting is what stops an agent going live with nothing to stand on.

```mock
{"component": "AgentsScreen", "props": {"caption": "Agents you have built, with where each one is running."}}
```
:::

::: step Give it something to know

An agent with no knowledge can only be polite. Open **Knowledge**, create a knowledge base, and add your first source.

The fastest useful source is your own website:

- Choose **Website**, paste your help or FAQ URL, and let it crawl.
- Crawling reads the pages, splits them into passages, and indexes each passage by meaning rather than by keyword.

You can also upload a PDF or paste text directly. Most workspaces end up with all three.

::: tip Start narrower than feels right
Point it at your help centre, not your entire marketing site. Retrieval quality falls when the index is full of pages that answer nothing — press releases and careers pages compete with the passage that actually holds the refund window.
:::

Back on the agent, open the **Knowledge** tab and bind the knowledge base to it. An agent only sees knowledge you have explicitly attached.
:::

::: step Test it before anyone else does

Open the **Test** tab and ask it the five questions your customers actually ask. Not the easy ones — the ones your team gets wrong.

Watch for two failures specifically:

- **It answers from nowhere.** If it states a policy that isn't in your sources, your knowledge base is thin and the agent is filling the gap. Add the missing source.
- **It refuses something it should know.** The passage exists but isn't being retrieved — usually because the page buries the answer in a table or an image.

Fix these now. Every one of them is a real customer conversation later.
:::

::: step Publish a version

Testing edits a draft. Publishing freezes it.

Choose **Publish** and the current state of the agent becomes an immutable **version** — persona, instructions, knowledge bindings, and tool policy, captured together. Your next edit starts a new draft and does not touch what is running.

This is the mechanism that makes the rest of the system safe: nothing you type in the studio can change an agent that is currently talking to customers.
:::

::: step Deploy it to your website

From the agent, choose **Deploy** → **Web widget**. The console gives you one line:

```html title="Paste before </body>"
<script async src="https://services.amomic.in/widget.js" data-bot="wgt_01JQRS4T8XZ0AB1CD2EF3GH4"></script>
```

Paste it before the closing `</body>` tag of your site. That's the whole installation — no npm package, no build step, no framework plugin.

```mock
{"component": "WidgetMock", "props": {"caption": "The widget on a customer's screen. Colours, greeting, and position all follow your configuration."}}
```

Add your domain to the widget's allowed list while you're there. Until you do, a draft bot answers on any origin — convenient for testing, wrong for production.
:::

:::

## You now have

- An agent with a defined job, grounded in your own content
- A published version you can point to and roll back to
- A live deployment on one channel, with every conversation landing in your inbox

## Where to go next

::: cards

::: card Put it on WhatsApp
The same agent, same knowledge, answering on [WhatsApp](/channels/whatsapp). Connect your own WhatsApp Business number through Meta.
:::

::: card Give it a phone number
Let it [answer the phone](/channels/voice) in English, Hindi, or whichever Indian language the caller uses.
:::

::: card Drive it from your backend
[Send messages and place calls](/start/first-api-call) from your own systems over the REST API.
:::

::: card Understand the model
[How it fits together](/concepts/architecture) — the ten minutes that make everything else obvious.
:::

:::


----------------------------------------------------------------------------
## Your first API call
URL: https://docs.amomic.in/start/first-api-call
----------------------------------------------------------------------------

The API lets your own systems do what your team does in the console: send a message, place a call, read a conversation, open a ticket. This page takes you from nothing to a real message delivered.

::: note Server-side only
`/api/v1` sends no CORS headers, by design. An API key in front-end JavaScript is a leaked API key — anyone can read it out of your bundle. Call this API from your backend. For in-page use there is the [web chat widget](/channels/web-chat), which has its own origin-scoped auth.
:::

## 1. Create a key

In the console, open **Developers → API keys** and choose **Create key**.

Name it after the system that will hold it — `Order service`, not `Test key 2`. When a key starts behaving strangely at 3 a.m., the name is what tells you which deployment to look at.

New keys are read-only by default (`conversations:read` and `agents:read`). Widen them deliberately: a key is easy to grant more scope later and impossible to un-leak. See [Scopes](/api/scopes).

```mock
{"component": "ApiKeysScreen", "props": {"caption": "Keys are shown masked after creation. The one full copy is the only one."}}
```

::: warning The secret is shown exactly once
We store a SHA-256 hash, not the key. Nobody at Amomic-AI can recover it for you — not support, not an engineer with database access. Put it in your secret manager before you close the dialog. If you lose it, roll the key; rolling gives you a new secret and keeps the old one working for 24 hours so you can deploy without downtime.
:::

## 2. Verify it

`GET /ping` costs nothing, changes nothing, and tells you everything about how the API sees your key. It should be the first call every integration makes.

::: codegroup

```bash cURL
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```javascript Node.js
const response = await fetch("https://services.amomic.in/api/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` },
});

console.log(await response.json());
```

```python Python
import os, httpx

response = httpx.get(
    "https://services.amomic.in/api/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"},
)
print(response.json())
```

:::

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order service",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

Read `scopes` carefully. Most "why is this 403" questions are answered right here, before any real request is made.

## 3. Find out what your workspace can do

Ids don't exist in a vacuum — you need a sender to send *from*. `GET /channels` exists precisely because a backend integrator has no console open to copy one out of.

```bash
curl https://services.amomic.in/api/v1/channels \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{
  "message_channels": ["whatsapp"],
  "call_channels": ["voice"],
  "senders": [
    {
      "channel": "whatsapp",
      "sender_id": "was_9f2c41ab77de1063c8a4b512",
      "display_number": "+919461093306",
      "verified_name": "Acme Retail",
      "is_default": true,
      "status": "connected"
    }
  ]
}
```

## 4. Send a real message

Now the interesting one. This sends an actual WhatsApp message to an actual phone.

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-shipped" \
  -d '{
    "to": "+919876543210",
    "template": {
      "name": "order_shipped",
      "language": "en_US",
      "variables": ["Asha", "AM-4821"]
    }
  }'
```

```javascript Node.js
const response = await fetch("https://services.amomic.in/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-shipped`,
  },
  body: JSON.stringify({
    to: order.customerPhone,
    template: {
      name: "order_shipped",
      language: "en_US",
      variables: [order.customerName, order.reference],
    },
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}
```

```python Python
import os, httpx

response = httpx.post(
    "https://services.amomic.in/api/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
        "Idempotency-Key": f"order-{order.id}-shipped",
    },
    json={
        "to": order.customer_phone,
        "template": {
            "name": "order_shipped",
            "language": "en_US",
            "variables": [order.customer_name, order.reference],
        },
    },
)
response.raise_for_status()
```

:::

```json title="201 Created"
{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "sent"
}
```

```mock
{"component": "WhatsAppMock", "props": {"caption": "What lands on your customer's phone. The variables you passed are substituted into the approved template."}}
```

Three things in that request are doing real work:

- **`template` rather than `text`.** You can only send free-form text inside the 24-hour window that opens when a customer messages you. An order update almost never falls inside it. [The 24-hour window](/channels/whatsapp-window) explains when each applies.
- **`Idempotency-Key`.** Your retry after a network timeout replays the stored response instead of messaging the customer twice. See [Idempotency](/api/idempotency).
- **`variables` positionally.** `["Asha", "AM-4821"]` fills `{{1}}` and `{{2}}`. An object like `{"1": "Asha", "2": "AM-4821"}` works too.

## 5. Handle the failures properly

Every error uses the same envelope, so one handler covers the whole API:

```json title="412 Precondition Failed"
{
  "error": {
    "code": "failed_precondition",
    "message": "This workspace has no WhatsApp sender connected.",
    "details": { "reason": "channel_not_connected" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Branch on `error.code` for the class of problem and on `error.details.reason` for the specific cause. Log `request_id` — quoting it to support turns a support thread into a lookup.

The ones you will actually hit first:

```responses
[
  {"status": 401, "code": "unauthenticated", "reason": "wrong_environment", "description": "A test key was used against production, or the reverse. Not a bad secret."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key is valid but lacks the scope. `details.required_scope` names it."},
  {"status": 404, "code": "not_found", "reason": "template_not_found", "description": "No approved template by that name. Check spelling and approval status."},
  {"status": 409, "code": "conflict", "reason": "session_window_closed", "description": "Free-form text outside the 24-hour window. Send a template."},
  {"status": 412, "code": "failed_precondition", "reason": "channel_not_connected", "description": "No WhatsApp sender is connected to this workspace yet."}
]
```

[Errors](/api/errors) has the complete list.

## Test keys and live keys

There is one production API. Keys carry an environment and are checked against the host they are used on:

```params
[
  {"name": "amk_live_…", "type": "live key", "required": false, "description": "Works against <code>services.amomic.in</code>. Real messages, real calls, real money."},
  {"name": "amk_test_…", "type": "test key", "required": false, "description": "Issued in non-production environments. Sending one at the production host returns <code>401</code> with <code>wrong_environment</code>."}
]
```

A mismatch is always a 401 with `details.reason` of `wrong_environment` — never a silent failure and never a bad-secret error. If you see it, you have the right key pointed at the wrong host.

## Next

::: cards

::: card Place an AI call
[POST /calls](/api/calls) has your agent phone someone and talk to them.
:::

::: card Receive events
[Webhooks](/webhooks/overview) push replies, call outcomes, and new tickets to you instead of you polling.
:::

::: card A complete flow
[Order-shipped update](/recipes/order-updates) — the whole thing end to end, including retries and the webhook that closes the loop.
:::

::: card Hand it to a coding agent
[Use with agents](/agents-setup) connects these docs to Claude Code or Codex so it writes the integration with the real contract in front of it.
:::

:::


----------------------------------------------------------------------------
## What you can build
URL: https://docs.amomic.in/start/what-you-can-build
----------------------------------------------------------------------------

This page is for deciding whether this fits. Every scenario below is built from things that ship today — no roadmap, no "with a bit of custom work". Each one names the pages that build it, so you can skim the shape and then go deep on whichever is yours.

Underneath all six is one model: you build **one agent**, publish it as a **version**, and deploy that version onto each **channel** where customers reach you. Read [How it fits together](/concepts/architecture) once and every scenario here becomes obvious.

## A support agent on WhatsApp and the web

The most common first build, and the one that pays for itself fastest.

You point a knowledge base at your help centre, upload the two PDFs that were never turned into pages, and paste in the handful of exceptions your team knows by heart. You write a purpose that names what the agent owns and what it hands off. Then you deploy that one agent twice — once as a widget on your site, once on your WhatsApp Business number. Same knowledge, same answers, two touchpoints. When your refund window changes from 7 days to 14, you update one source and both channels are correct within a re-sync.

The work is mostly in the knowledge, not the configuration. Expect to spend an hour on sources and testing, and about ten minutes on everything else.

→ [Quickstart](/start/quickstart) · [Knowledge bases](/build/knowledge) · [Install the widget](/channels/web-chat) · [Set up WhatsApp](/channels/whatsapp)

## An AI receptionist on your main line

Your published number rings; the agent answers, in Hindi or English, and follows the caller if they switch mid-sentence.

You get a phone number, deploy an agent to it, and write the opening line callers hear the moment the call connects. The **call language** setting decides what a caller may speak — English only for the cleanest transcription, Hindi and English for the usual Indian mix, or all ten supported Indian languages — and the **opening language** decides only which one the first sentence is in. On a call the agent answers common questions instantly from a compressed fact sheet built from your knowledge base, and reaches for a full search only when a caller asks for something specific. When it is done, it says goodbye and hangs up properly rather than leaving a caller listening to an open line.

Every call produces a transcript, an outcome, response-latency figures, and optionally a recording.

→ [How voice works](/channels/voice) · [Numbers and KYC](/channels/phone-numbers) · [Languages](/channels/voice-languages)

## Order and delivery notifications from your backend

This one is not conversational at all. Your systems already know when an order ships; the customer's phone is where they want to hear about it.

Your backend calls [`POST /messages`](/api/messages) with an approved WhatsApp template and the values to fill in. Because a shipment notification almost always fires outside the 24-hour window, a template is not optional — a free-form send there is refused with a `409` and `session_window_closed`, which is a rule of WhatsApp's, not ours. Send an `Idempotency-Key` derived from your own order id and a retry after a network timeout returns the original response instead of messaging the customer twice.

If the customer replies, the window opens, your agent picks up the conversation, and it lands in the same inbox as everything else.

→ [Order-shipped update](/recipes/order-updates) · [Sending messages](/api/messages) · [Templates](/channels/whatsapp-templates) · [The 24-hour window](/channels/whatsapp-window) · [Idempotency](/api/idempotency)

## An outbound renewal reminder, triggered by your CRM

A policy is expiring in seven days. Your CRM knows; a human calling three hundred customers does not scale.

Your system calls [`POST /calls`](/api/calls) with the destination, the caller-ID number to dial from, and a short `purpose` that tells the agent why it is calling. The agent opens with a fixed template that identifies your business, discloses that it is a virtual assistant, and asks whether now is a good time — in that order, deliberately. From there it is a real conversation: it can answer questions from your knowledge base and open a ticket if the customer wants a person.

A `201` means the call is ringing, not connected. The outcome arrives later, on the `call.ended` webhook or by fetching the call.

::: warning Outbound calling is your compliance decision
The platform enforces the operational guards: the destination cannot be one of your own numbers, the caller ID must be a number your workspace owns with an agent deployed on it, and concurrent calls are capped per workspace. It does **not** check a do-not-call registry, enforce calling hours, apply a per-day cap, or maintain a consent register — none of those exist. Whether a given number should be called, and when, is entirely on your side of the line.
:::

→ [Trigger a call from your CRM](/recipes/crm-call) · [Placing calls](/api/calls) · [Outbound calls](/channels/outbound-calls)

## Escalation into tickets when a human is needed

The agent's most useful skill is knowing when to stop.

When a customer asks for a person, asks for follow-up, or has a problem the knowledge base cannot resolve, the agent calls `create_support_ticket`. That one action resolves the customer against your contact directory — by email, phone, or WhatsApp ID, depending on what the channel already knows — opens the ticket with the issue summary and the conversation reference attached, and reads the reference back to the customer: `AM-4F91C2E0`. Retries inside the same conversation return the same ticket rather than a duplicate. Your team works it in the console; your backend hears about it on the `ticket.created` webhook.

This is the hand-off path, and it is worth being explicit about why: the inbox is read-only. There is no takeover control and no way to join a live conversation as a human. When a person needs to get involved, a ticket is how they do it.

→ [Escalate to a ticket](/recipes/support-escalation) · [Tools and actions](/build/tools) · [Tickets](/api/tickets)

## Conversations synced into your warehouse

Every channel converges into one conversation store, which makes it a genuinely useful analytics source — but only if it is in your warehouse next to everything else.

A scheduled job walks [`GET /conversations`](/api/conversations) newest-first with a cursor, fetches the transcript for anything new, and writes both. The transcripts you get back contain only customer and agent messages; the internal trail of what the agent looked up is not included, so you are not accidentally exporting operational noise or tool payloads into a table someone will later query. A read-only key carrying only `conversations:read` is all this needs — build the job against a key that cannot send anything.

→ [Sync conversations](/recipes/sync-conversations) · [Conversations API](/api/conversations) · [Pagination](/api/pagination) · [Scopes](/api/scopes)

## What this is not for

Worth saying plainly, because discovering it in week three is expensive.

**This is not a bulk marketing blaster.** There is no campaign builder, no broadcast tool, no contact-list send, no batch endpoint, and no scheduling parameter anywhere in the API. Sending to a thousand people means a thousand individual calls, each subject to a per-key rate limit — the shape of the product is one customer at a time. WhatsApp's own opt-out keywords are honoured automatically and a suppressed recipient is refused, which is correct behaviour for a support and transactional tool and an obstacle if what you wanted was reach. If your use case is promotional volume, this is the wrong tool and it will be a frustrating one.

**This is not a replacement for your CRM.** Contacts here are a directory for *reaching* people — name, phone, email, WhatsApp ID, per-channel consent, tags. There are no deals, no pipelines, no custom fields, no automatic activity timeline, and no merge for duplicates. It is deliberately the minimum needed to know who you are talking to and whether you are allowed to contact them. Your CRM stays the system of record; this stays the system that talks to customers, and [`POST /contacts`](/api/contacts) is the seam between them.

**And two smaller ones.** There is no human takeover in the inbox — escalation is a ticket. And there is no per-channel agent behaviour: one agent behaves the same on WhatsApp, the web, and the phone, so genuinely different jobs need genuinely different agents.

## Where to start

::: cards

::: card Build the first one
[Quickstart](/start/quickstart) — an agent answering on your website in about five minutes.
:::

::: card Wire up your backend
[Your first API call](/start/first-api-call) — a working authenticated request in about a minute.
:::

::: card Understand the model first
[How it fits together](/concepts/architecture) — five nouns that make everything else obvious.
:::

::: card Look up a word
[Glossary](/concepts/glossary) — every term in these docs, defined with a link.
:::

:::


============================================================================
# SECTION: Concepts
============================================================================



----------------------------------------------------------------------------
## How it fits together
URL: https://docs.amomic.in/concepts/architecture
----------------------------------------------------------------------------

Everything in this documentation is an elaboration of five nouns: a **workspace** holds **agents**; an agent is published as a **version**; a version is put on a **channel** by a **deployment**. Read this page once and the rest of the docs stop being a list of features and start being obvious.

## The whole model in one sentence

You build one agent, you freeze it as a version, and you deploy that version onto each channel where customers can reach you. Every one of those channels feeds back into the same inbox, the same customer directory, and the same analytics.

```mock
{"component": "PlatformDiagram", "props": {"caption": "One agent, published as versions, deployed onto channels. Customers arrive on the left; your systems talk to the API on the right."}}
```

## A workspace

A workspace is your organisation. It owns the agents, the knowledge, the channel connections, the conversations, the contacts, the API keys, and the bill.

It is also the isolation boundary. Every query the platform runs is filtered by workspace before anything else happens, and there is no mechanism — no sharing setting, no cross-workspace agent, no shared knowledge base — for data to cross it. A WhatsApp number connected to one workspace cannot be connected to another. Two workspaces are two products as far as the data is concerned.

Everything else on this page happens *inside* one workspace. [Workspaces and roles](/concepts/workspace) covers who can do what within it.

## An agent is a persona, knowledge, and tools

An agent is not a chatbot script and not a flow chart. It is three things bundled together:

| Part | What it is | Where you set it |
|---|---|---|
| **Persona** | Its name, its purpose, its instructions, the language it works in, and how strictly it must stick to your content. | The agent's **Persona** tab |
| **Knowledge** | The knowledge bases you have explicitly attached. An agent can only answer from knowledge you attached to it. | The agent's **Knowledge** tab |
| **Tools** | The things it can *do* rather than know — open a ticket, send a WhatsApp message, call your API, end a call. | The agent's **Tools** tab |

Those three things are channel-neutral. You do not write a WhatsApp agent and a phone agent; you write one agent, and each channel renders it appropriately — the same answer arrives as light markdown in the web widget, as WhatsApp's own bold and italic syntax on WhatsApp, and as plain spoken prose on a call.

That is the first reason the model is shaped this way: **you describe the job once**. When your refund window changes from 7 days to 14, you update one knowledge source and every channel is correct.

See [Agents and versions](/build/agents), [Knowledge bases](/build/knowledge), and [Tools and actions](/build/tools).

## Publishing freezes a version

While you are editing, you are editing a draft. Nothing you type is live.

When you choose **Publish**, the current state of the agent is captured as a **version**: the persona, the knowledge bindings, and the tool policy, all snapshotted together and stamped with a sequence number and a configuration hash. That version is immutable. There is no edit path for a published version — not in the console, not in the API, not for support. The only way to change anything is to publish a new one.

Your next edit starts a fresh draft. The agent's badge changes from `Published` to `Changes to publish`, and the version that is actually running does not move.

This is the second reason the model is shaped this way: **you can fix an agent without touching what is live**. You can rewrite the instructions, re-crawl the website, attach a new knowledge base, and test all of it at midday on a Tuesday while the version deployed on your phone number keeps answering exactly as it did this morning. Nothing you do in the studio can reach a customer until you publish and deploy on purpose.

::: note Immutability is what makes rollback meaningful
If versions could be edited, "roll back to version 3" would mean "roll back to whatever version 3 has become". Because they cannot, version 3 is still exactly the agent that worked, including which knowledge it was allowed to see.
:::

## Deploying puts a version on a channel

A **channel** is a kind of touchpoint: web chat, WhatsApp, or voice. A **channel connection** is a specific one you own and have verified — this website's domain, that WhatsApp Business number, this phone number.

A **deployment** is the join between them: *this agent version, on that connection, with this channel-specific configuration.*

```
agent version  +  channel connection  +  channel config   =   deployment
(what it says)    (where customers        (greeting, call
                   reach you)              language, domains)
```

The channel config is the part that genuinely differs per channel and has nowhere else to live: the opening line a caller hears, which language the call opens in, whether calls are recorded, which domains the widget may load on, which WhatsApp sender number it answers from.

One agent can have many deployments — a widget on your main site, a second widget on your help centre, a WhatsApp number, and a phone number, all serving the same published version. Each is independent. Pausing the phone deployment does not touch the widget.

A deployment moves through `draft` → `ready` → `active`, and when a newer deployment takes over the same connection, the old one becomes `superseded`. Activation is a single transaction that swaps the connection over and supersedes whatever was there, so two people activating at once cannot both win.

The rule worth learning early: **editing a live deployment clones it rather than changing it.** An active deployment is frozen; a change produces a replacement that must validate before it can replace the original. A bad edit can therefore never take down a working number — the worst case is a clone that refuses to activate, while the old deployment carries on. [Deployments](/build/deployments) covers the whole lifecycle.

## Everything converges

Whatever channel a customer arrives on, the same three things happen.

**One inbox.** Every conversation — a widget chat at 2 a.m., a WhatsApp thread, a phone call transcript — lands in the same inbox with its full transcript, tagged with the channel it came from. You do not check three places.

**One customer directory.** When an agent needs to identify someone — to open a ticket, say — it resolves them against your contacts by email, phone, and WhatsApp ID before creating anything new. A returning customer enriches the record that already exists rather than spawning a duplicate.

**One set of analytics.** Conversation volume, messages per visitor, channel mix, and voice performance are computed across every deployment of every agent, and can be filtered down to a single touchpoint.

[Conversations and contacts](/concepts/conversations) explains the transcript and identity model in detail, including where the identity story is still incomplete.

## The two ways in

There are exactly two interfaces, and they are split along a deliberate line.

### The console, for humans

`console.amomic.in` is where the things you change once a quarter live: creating agents, writing personas, adding knowledge, configuring tools, publishing versions, connecting channels, deploying, reading the inbox, working tickets, managing the team and the bill.

These are decisions that want review, permissions, and a visible history — which is exactly what a UI provides and an API does not.

### The API, for your systems

`https://services.amomic.in/api/v1` is where the things you call ten thousand times a day live: sending a message, placing a call, reading a conversation, opening a ticket, upserting a contact.

It is a small, flat REST surface, server-side only, authenticated with a workspace-scoped key. Start at [Your first API call](/start/first-api-call) or the [API overview](/api/overview).

### Which one does what

| Task | Console | API |
|---|---|---|
| Create or edit an agent | Yes | — |
| Add or refresh knowledge | Yes | — |
| Configure tools and the tool policy | Yes | — |
| Publish a version | Yes | — |
| Deploy, pause, or replace a deployment | Yes | — |
| Connect a WhatsApp number, request a phone number | Yes | — |
| Create or revoke an API key | Yes (admins) | — |
| Send a WhatsApp message | The agent does it in conversation | [`POST /messages`](/api/messages) |
| Place an outbound AI call | From a ticket | [`POST /calls`](/api/calls) |
| Read a conversation transcript | Inbox | [`GET /conversations`](/api/conversations) |
| Open a support ticket | Tickets | [`POST /tickets`](/api/tickets) |
| Create or match a contact | Contacts | [`POST /contacts`](/api/contacts) |
| Be told when something happens | Notifications | [Webhooks](/webhooks/overview) |

The API has no agent-building routes and will not grow them. Configuration that changes behaviour for every future customer belongs where a person can review it; traffic belongs on the API.

::: warning The API is not callable from a browser
`/api/v1` sends no CORS headers at all. API keys are workspace-scoped, so a key in front-end JavaScript is a leaked workspace. For anything in the page, use the [web chat widget](/channels/web-chat), which has its own origin-scoped auth and no key.
:::

## Following one customer through

Priya opens your site at 11 p.m. and asks about a delayed order.

1. The **widget** loads on an allowed domain and finds the **deployment** attached to it. That deployment names an **agent version**.
2. The version's **knowledge bindings** decide what the agent may search. Her question is matched against passages by meaning, and the closest ones are put in front of the model.
3. The agent answers from those passages. Because it cannot resolve the delay itself, it reaches for a **tool** — `create_support_ticket` — which first resolves Priya against your **contacts** by email, then opens a ticket and returns its public reference, `AM-4F91C2E0`.
4. The whole exchange is a **conversation** in your **inbox**, with the ticket linked to it.
5. Your backend hears about it on the `ticket.created` **webhook**, and your ops tool calls [`POST /messages`](/api/messages) the next morning to send her the resolution on WhatsApp — the same person, matched on the same phone number.

Five nouns, one customer, no duplicated configuration anywhere.

## What is deliberately not in the model

Naming the gaps is faster than discovering them.

- **There is no per-channel agent.** You cannot give WhatsApp different instructions from voice. If two channels genuinely need different behaviour, build two agents and deploy one to each.
- **There is no per-deployment knowledge override.** Knowledge is bound to the agent and frozen into the version; every deployment of that version sees the same knowledge.
- **There is no cross-workspace sharing.** Agents and knowledge bases do not travel between workspaces.
- **Versions are never edited.** Not by you, not by support. Publish a new one.
- **Channel connections are not created by the API.** Numbers and domains are provisioned and verified in the console.

## Where to go next

::: cards

::: card Workspaces and roles
[Who can do what](/concepts/workspace), how invitations work, and why API keys are workspace-wide.
:::

::: card Build an agent
[Agents and versions](/build/agents) — the fields that matter, and how to write a purpose that produces a good agent.
:::

::: card Teach it something
[Knowledge bases](/build/knowledge) — the five source types, how retrieval works, and how to get good answers out of it.
:::

::: card Put it somewhere
[Deployments](/build/deployments) — the lifecycle, activation, and why editing a live deployment clones it.
:::

::: card Look up a word
[Glossary](/concepts/glossary) — every term in these docs, defined in two sentences with a link.
:::

::: card Drive it from code
[Your first API call](/start/first-api-call) — a working request in about a minute.
:::

:::


----------------------------------------------------------------------------
## Workspaces & roles
URL: https://docs.amomic.in/concepts/workspace
----------------------------------------------------------------------------

A workspace is your organisation inside Amomic-AI. It owns your agents, knowledge bases, channel connections, conversations, tickets, contacts, API keys, and the subscription that pays for all of it. Everything you build lives in exactly one workspace, and a person can belong to more than one — the topbar switcher moves between them.

Two things make the workspace worth understanding on its own: it is the **billing boundary**, and it is the **isolation boundary**.

## The isolation boundary

Every read and write the platform performs is filtered by workspace before anything else is evaluated. There is no sharing setting, no "make this knowledge base public", and no cross-workspace agent. Concretely:

- An agent, a knowledge base, or a published version belongs to one workspace and cannot be copied to another from the product.
- A WhatsApp Business number connected to one workspace cannot be connected to a second — the attempt is refused with *"This WhatsApp number is already connected to another workspace."*
- A phone number provisioned for a workspace answers only that workspace's deployments.
- An API key reads and writes only its own workspace's data. There is no key that spans two.

If your company needs a hard separation — production versus a partner brand, or two subsidiaries that must not see each other's customers — two workspaces is the mechanism. There is no lighter-weight partition inside one.

## The billing boundary

The plan, the seat count, and the usage meters are all properties of the workspace, not of a person. Your plan sets hard caps on how many agents, knowledge bases, deployments, and team seats you can create; creating past a cap is refused with a message naming the limit. [Limits and plans](/operate/limits) has the numbers.

Two consequences worth knowing before they surprise you:

- **Pending invites consume seats.** The Members tab counts active members plus outstanding invitations against the seat limit, so an invite that was never accepted still blocks the next one. Revoke it.
- **A suspended workspace stops working, for everyone.** If payment goes unpaid for long enough the console collapses to the billing page for every member, and voice calls are answered with an out-of-service line rather than by your agent. Only an owner can clear it.

## The three roles

There are exactly three: `owner`, `admin`, and `member`. They are ranked, and every permission check is "this rank or above" — so an owner passes every admin check without needing a second role.

There is exactly one owner per workspace, created when the workspace is created. Ownership moves by transfer, not by promotion.

| | Member | Admin | Owner |
|---|---|---|---|
| Read the inbox, tickets, calls, analytics | Yes | Yes | Yes |
| Work tickets they have claimed | Yes | Yes | Yes |
| Read agents, knowledge, and the retrieval tester | Yes | Yes | Yes |
| Test an agent | Yes | Yes | Yes |
| Add, edit, or delete knowledge sources | — | Yes | Yes |
| Create, publish, or archive an agent | — | Yes | Yes |
| Deploy, pause, or remove a deployment | — | Yes | Yes |
| Connect channels, request phone numbers, submit compliance | — | Yes | Yes |
| Create, roll, and revoke API keys and webhooks | — | Yes | Yes |
| Add, edit, import, or delete contacts | — | Yes | Yes |
| Assign tickets to other people, acknowledge escalations, set routing | — | Yes | Yes |
| Edit organisation details | — | Yes | Yes |
| Invite, remove, and re-role teammates | — | Yes | Yes |
| Change the plan, pay, or cancel the subscription | — | — | Yes |
| Transfer ownership | — | — | Yes |

### What a member actually experiences

Member is a genuine working role, not a read-only spectator seat. A member can handle the whole support day: read every conversation in the inbox, claim an unassigned ticket, reply on it, add internal notes, escalate something they cannot resolve, and use the AI copilot on tickets they have claimed.

What they cannot do is change how the product behaves. The write controls on Knowledge are removed from their view rather than shown as disabled buttons, and Channels and Developers are not in their sidebar at all.

Three member-specific rules in ticketing are worth stating because they surprise people:

- A member must **claim** a ticket before working it. The composer says `Claim this ticket before working on it.` until they do.
- A member cannot assign a ticket to someone else, only to themselves.
- A member sees active tickets. Resolved and closed queues are an admin view.

### What admin adds

Admin is the "configures the product" role. Everything that changes what customers experience — the agent's instructions, what it knows, what it can do, which number it answers on — is admin and above, as is everything that hands out credentials.

Two admin powers deserve deliberate thought before you grant them:

- **API keys.** An admin can mint a key that sends WhatsApp messages and places calls on behalf of the whole workspace. The console says so on the page: *"API keys can send messages and place calls on behalf of this whole workspace, so only owners and admins can manage them."*
- **Deployments.** An admin can point a live phone number at a different agent. The change is auditable and reversible, but it takes effect on the next call.

### What owner adds

Owner adds money and succession: changing plan, paying, cancelling, and transferring ownership. That is the entire delta. An owner is not a "super admin" with extra product powers — an admin can already configure everything.

Transferring ownership is a swap, not a copy: `Transfer ownership to {name}? You'll become an admin.` The workspace never has two owners and never has none.

## Inviting teammates

Invitations live in **Settings → Members**.

::: steps

::: step Send the invite

Enter the teammate's email and pick a role. The role select offers **Member** and **Admin** only — you cannot invite someone as an owner, because ownership transfers rather than being granted.

The invite becomes a link. Share it however you normally share links; the invitation is also recorded under **Pending invites** with its role and expiry.
:::

::: step Watch the seat count

The card reads `{used} of {limit} plan seats used (pending invites count)`. If you are at the cap the invite is refused with `seat_limit_reached` and a message naming your plan's seat allowance.

Revoking a stale pending invite frees its seat immediately.
:::

::: step Change or remove later

Each member row carries a role select (`Member` / `Admin`), a transfer-ownership control, and a remove control. Changing someone from admin to member takes effect on their next request; it does not revoke API keys they created, because keys belong to the workspace rather than to them.
:::

:::

::: warning Removing a person does not revoke their keys
An API key is a workspace credential. If the person who created it leaves, the key keeps working until an admin revokes or rolls it. Off-boarding should include a pass over **Developers → API keys**.
:::

## API keys are workspace credentials

This is the single most important thing to understand about programmatic access, and it is a deliberate design choice rather than a missing feature.

An API key authenticates **the workspace**, not a user and not an agent. There is no per-user key, no per-agent key, and no per-origin key. A key does not inherit the role of whoever created it, and actions taken with it are not attributed to a person.

```mock
{"component": "ApiKeysScreen", "props": {"caption": "Keys are named for where they run, not for who made them. The scope column is the only thing narrowing what each one can do."}}
```

**Scopes are the only partition.** A key carries a set of the six scopes, granted at creation, and that set is the whole of its authority:

| Scope | Lets the key |
|---|---|
| `messages:send` | Send WhatsApp messages and templates |
| `calls:write` | Place a call, read its outcome, hang it up |
| `conversations:read` | List conversations and read transcripts |
| `contacts:write` | Create or match a contact |
| `tickets:write` | Open a ticket, and read one back |
| `agents:read` | List the agents in the workspace |

A newly created key defaults to `conversations:read` and `agents:read` — read-only, on the principle that a key is easier to widen later than to un-leak. [Scopes](/api/scopes) has the full endpoint matrix, including the fact that reading a ticket requires `tickets:write` because there is no read-only ticket scope.

Practical consequences of workspace-scoping:

- **Give each system its own key.** Not because the keys differ in power by default, but because separate keys are separately revocable and separately visible in the request log. Your order service and your CRM sync should not share one.
- **Grant the narrowest scope set that works.** A key that only needs to send order updates gets `messages:send` and nothing else. It then cannot read a single conversation even if it is stolen.
- **Never put a key in front-end code.** `/api/v1` sends no CORS headers precisely so that this fails loudly rather than working until someone reads your bundle.
- **Rotate with Roll, not Revoke.** Rolling issues a replacement and keeps the old key working for 24 hours, which is enough to redeploy. Revoking kills it within seconds.

The full mechanics — the one-time reveal, the `amk_live_` / `amk_test_` split, and the six distinct causes of a 401 — are in [Authentication](/api/authentication).

## Who should be what

Some opinionated defaults that hold up in most teams.

**Owner: one person, usually whoever owns the budget.** Not the most technical person, and not a shared account. The owner is who your renewal fails on and who has to act at 9 a.m. on a Monday when a payment bounces. Transfer it when that person changes jobs rather than sharing their login.

**Admin: the two or three people who build the product.** Whoever writes the agent's instructions, curates the knowledge, and owns the integration. Keep this list short — an admin can repoint a live phone number and mint a key that sends messages to your entire customer list.

**Member: everyone else, including most of the support team.** A member can do all the day-to-day work and cannot accidentally change what an agent says to twenty thousand customers. Support agents, analysts, and anyone who mainly reads should be members.

Two failure modes to avoid:

- **Making everyone an admin so nobody is blocked.** The most common reason a live agent changed unexpectedly is that seven people could change it.
- **Making the only technical person a member.** They will be blocked on every knowledge fix and you will end up sharing an admin login, which is worse than the grant you were avoiding.

## Also on the Settings page

Beyond Members, the settings tabs cover a few workspace-level things worth knowing where to find:

- **Organization** — the workspace name, website, and the **Organization ID** you should quote when you contact support.
- **Compliance** — the one-time identity verification required before phone numbers can be issued to the workspace. See [Numbers and KYC](/channels/phone-numbers).
- **Profile** — your own display name, and phone verification so the platform can ring you when you call a customer from a ticket.
- **Notifications** — which events reach you in-app and by email. Security and billing emails are always sent and cannot be turned off.

## Next

::: cards

::: card How it fits together
[The model in one page](/concepts/architecture) — agents, versions, deployments, and channels.
:::

::: card Authentication
[How keys work](/api/authentication) — format, one-time reveal, rolling, and every cause of a 401.
:::

::: card Scopes
[What a key can do](/api/scopes) — six scopes and the endpoint matrix.
:::

::: card Security and data
[Where your data lives](/operate/security) and how it is protected.
:::

:::


----------------------------------------------------------------------------
## Conversations & contacts
URL: https://docs.amomic.in/concepts/conversations
----------------------------------------------------------------------------

Every channel converges here. A widget chat at 11 p.m., a WhatsApp thread, a phone call — all three become a **conversation** with a full transcript, and all three resolve to a **contact** in the same customer directory. This page explains both, including where the identity story is still incomplete.

## What a conversation is

A conversation is one continuous exchange between a customer and an agent on one channel. It carries:

| Field | What it is |
|---|---|
| `conversation_id` | The stable identifier. Use it to fetch the transcript. |
| `channel` | Where it happened — `web`, `whatsapp`, or `voice`. |
| `agent_id` | Which agent handled it. |
| `status` | Where it stands; open conversations report `open`. |
| `customer` | What is known about the person — name, email, and the channel-specific identifier. |
| `message_count` | How many messages it contains. |
| `preview` | The first 140 characters of the last real message, for list views. |
| `created_at` / `updated_at` | When it started and when it last moved. |

Conversations are per channel by design. A customer who chats on your website in the morning and messages your WhatsApp number in the afternoon has two conversations — because they are two different threads, with different histories and different constraints. They resolve to **one contact**, which is where the two halves come back together.

A voice call produces a conversation like any other. The transcript is the turns of the call, speaker by speaker; the audio recording, the call outcome, and the response-latency figures live alongside it on the call record. See [How voice works](/channels/voice).

## Message roles

The public transcript has exactly two roles.

| Role | Who |
|---|---|
| `user` | The customer. What they typed, or what they said on the call. |
| `model` | The agent. |

That is the whole vocabulary. There is no `system` role in a transcript, no `assistant` alias, and no tool-call messages.

### The operational trail

Alongside those messages, the platform records an internal trail of what the agent *did* between turns: which knowledge base it searched, which live API it called, which MCP tool it used, which action it took, and — on voice — why it played a filler line while it was waiting.

**That trail is deliberately excluded from the public transcript.** [`GET /conversations/{id}/messages`](/api/conversations) returns only `user` and `model` messages, so a transcript you sync into your warehouse or show to a customer contains the conversation and nothing else.

In the console inbox the trail *is* shown, rendered as thin rows rather than message bubbles, labelled by what happened: `Knowledge base`, `Live API`, `MCP tool`, `Action`. On calls you will also see why the agent spoke while thinking — `while looking something up`, `covering a slow reply`, `the wait ran long`, `checking the caller was still there`, `ending the call after silence`, `call time limit reached`.

::: tip Read the trail first when an answer was wrong
It separates three bugs that look identical from the outside. No lookup at all means the agent answered from its own head — a knowledge gap. A lookup that returned the wrong passages means a retrieval problem. The right passages plus a wrong answer means a persona problem. See [Testing and publishing](/build/testing).
:::

## The inbox

Every conversation from every channel lands in one inbox with its full transcript, tagged with the channel it came from. You do not check three places.

```mock
{"component": "InboxScreen", "props": {"caption": "Every conversation from every channel, with the full transcript and the operational trail."}}
```

The list is searchable and filterable by agent. Each row shows the agent, the customer's channel identifier, a relative timestamp, and either the last message or a message count; a `Preview` badge marks conversations from the console's own widget preview rather than a real visitor. The transcript pane shows the channel badge, when the conversation started, how many messages it holds, and the messages themselves. Images sent by a customer render inline.

::: warning The inbox is read-only
There is no takeover control and no reply box. You cannot join a live conversation, send a message as the agent, or intervene mid-chat from the inbox. It is a complete record of what happened, not a shared console.

When a customer needs a person, the route is a **ticket** — the agent opens one with `create_support_ticket`, your team works it in [Tickets](/api/tickets), and the ticket carries the conversation reference so whoever picks it up has the history. That is the supported hand-off path.
:::

## Reading conversations from your systems

Two endpoints, both requiring the `conversations:read` scope:

- [`GET /conversations`](/api/conversations) — the list, newest activity first, 25 per page by default and up to 100. Filter by `agent_id`. Walk pages with `next_cursor` until it comes back `null`.
- [`GET /conversations/{id}/messages`](/api/conversations) — the transcript, **oldest first**, 100 per page by default and up to 200.

An unknown or foreign conversation id returns 404 rather than an empty page, so a bad id can never look like a quiet conversation.

Internal fields are not projected — you will not see workspace ids, deployment ids, connection ids, or per-message metadata. What comes back is the conversation and its transcript.

For a scheduled sync into a warehouse, see [Sync conversations](/recipes/sync-conversations) and [Pagination](/api/pagination).

## Contacts

A contact is a person in your customer directory. It holds:

- `contact_id`, and the workspace it belongs to
- `name`, `phone`, `email`, and `wa_id` (their WhatsApp identifier)
- `tags`
- `consent` — separate permissions for `voice`, `whatsapp`, and `email`
- `last_seen_channel`
- `created_at`

Phone numbers are normalised on the way in. A bare ten-digit Indian number becomes `+91…` automatically; anything that does not land between 8 and 15 digits is rejected with `Phone number must contain 8 to 15 digits.` Email addresses are trimmed and lower-cased, so `Priya@Example.com` and `priya@example.com` are the same person. WhatsApp identifiers are reduced to digits.

## How a person is identified

There are exactly three match keys: **email**, **phone**, and **WhatsApp ID**. Every lookup is scoped to your workspace before anything else happens.

The resolution logic, in order:

::: steps

::: step Look up each identity separately

Whatever identities are known — an email, a phone number, a WhatsApp ID — each is queried against the directory on its own.
:::

::: step If exactly one contact matches, enrich it

The existing contact is updated with **only the fields that were empty**, plus `last_seen_channel`. A supplied value never overwrites a value that is already there.
:::

::: step If a supplied identity conflicts, stop

If the matched contact already has a different email — or a different phone — the operation fails with `The contact already has a different {field}; manual review is required.` rather than silently choosing one.
:::

::: step If the identities match two different contacts, stop

`The supplied identities belong to different contacts; manual review is required.` A phone number belonging to Rohit and an email belonging to Priya, arriving in the same request, is a data problem a human should look at — not something to resolve by guessing.
:::

::: step Otherwise, create

A new contact is created, tagged `ai-captured` when the agent captured it.
:::

:::

::: note There is no merge
Nothing in the platform merges two contacts into one. That is a deliberate refusal, not a missing feature — an automatic merge of two records that a conflict check already flagged as suspicious is how one customer's phone number ends up on another customer's file. Conflicts surface for a human to resolve.
:::

Over the public API, [`POST /contacts`](/api/contacts) upserts a contact and matches **by email first, then phone**. It requires at least one of the two — a name-only request is rejected with `Provide an email or a phone number.` If the details belong to two different existing contacts you get a 409 with `Those details belong to two different contacts.`

## How a contact accumulates across channels

This is the payoff, and it is worth being precise about how it happens.

Priya messages your WhatsApp number about a delayed order. The agent resolves her by her WhatsApp identifier, finds nothing, and creates a contact carrying her `wa_id` and the phone number derived from it. Later in the chat she gives an email so she can be updated — that email lands on the same contact, because it was empty.

Three weeks later she opens your website and fills in the widget's lead form with that same email. The resolver matches the email to the existing contact and enriches it rather than creating a second one. Her name from the web form fills a field the WhatsApp conversation never captured.

She then calls your support number. The agent resolves her by caller ID, which matches the phone number already on the record.

One contact. Three channels. No manual reconciliation — and, importantly, no guessing: each step matched on an identifier the channel itself supplied, not on a name that happened to look similar.

### Where contacts come from

| Source | Behaviour |
|---|---|
| Web widget lead form | Creates or enriches on submit. If it fails, the visitor never sees an error — the chat continues. |
| Agent opening a ticket on web chat | Asks first name, then email; asks for a phone number only when creating a new contact. |
| Agent opening a ticket on WhatsApp | Uses the chat's own number; asks for an email only if the contact has none. |
| Agent opening a ticket on a call | Uses the caller's number only. Email is never captured on a call — speech recognition is not reliable enough to spell an address. |
| [`POST /contacts`](/api/contacts) | Upsert from your own systems. Matches by email, then phone. |
| Console, and CSV import | Manual entry, or a CSV with `name`, `phone`, and `email` columns. |

::: warning Two honest gaps
**A conversation alone does not create a contact.** Somebody has to give an identity — through the lead form, through a ticket, or through the API. A customer who chats anonymously and never identifies themselves leaves a conversation and no directory entry. The console says so plainly on the contacts page.

**CSV import does not deduplicate.** Rows are created directly, without the resolution logic above. Importing a list that overlaps your existing directory produces duplicates, and there is no merge to clean them up afterwards. Import into a fresh directory, or check for overlap first.
:::

A contact's **activity timeline is currently empty**. It shows an honest empty state rather than fabricated history: automatic linking of calls and conversations onto a contact record is not enabled yet. To see a customer's history today, search the inbox or their tickets.

## What converges, and what does not

**Converges:** every conversation from every channel into one inbox; every identified customer into one contact record; every channel's volume into one set of analytics.

**Does not converge:** conversations themselves. A WhatsApp thread and a web chat with the same person remain two conversations, linked only by the contact. There is no unified per-customer thread view.

## Where to go next

::: cards

::: card Read transcripts from code
[Conversations API](/api/conversations) — list, fetch, and page through messages.
:::

::: card Upsert a customer
[Contacts API](/api/contacts) — matching rules, conflicts, and what comes back.
:::

::: card Hand off to a human
[Escalate to a ticket](/recipes/support-escalation) — the supported path when the agent cannot finish the job.
:::

::: card Get told instead of polling
[Webhooks](/webhooks/overview) — `conversation.started`, `conversation.ended`, and the rest.
:::

:::


----------------------------------------------------------------------------
## Glossary
URL: https://docs.amomic.in/concepts/glossary
----------------------------------------------------------------------------

Every term you will hit in this documentation, alphabetised, with a link to the page that covers it in full. If a word here is doing more work than you expected, follow the link — most of these are small ideas with a sharp edge somewhere.

### 24-hour window

WhatsApp's rule, not ours: you may send free-form messages to a customer only within 24 hours of their last message to you. Outside that window, only pre-approved templates go out, and a free-form attempt is refused with a `409` and `session_window_closed`. The clock resets every time the customer messages you again. No template is sent automatically when a window closes — if something needed to go out, it does not go out later. → [The 24-hour window](/channels/whatsapp-window)

### Agent

The thing your customer talks to: a persona, the knowledge bases attached to it, and the tools it may call, bundled together. An agent is channel-neutral — you write it once and each channel renders it appropriately, so the same answer arrives as light markdown in the web widget, as WhatsApp's own formatting on WhatsApp, and as spoken prose on a call. An agent cannot be reached by customers until it is published as a version and that version is deployed. → [Agents and versions](/build/agents)

### API key

The credential your backend uses to call the public API, formatted `amk_live_…` or `amk_test_…`. It is scoped to a whole workspace and to a specific set of scopes, sent as `Authorization: Bearer …` or `X-Api-Key`, and only ever stored as a hash — the plaintext is shown once, at creation, and never again. Because it is workspace-scoped, a key in front-end JavaScript is a leaked workspace; the API is server-side only and sends no CORS headers. → [Authentication](/api/authentication)

### Call mode

A voice deployment's setting for what a caller may speak, labelled **Call language** in the console. Three values: `en` (English only, highest transcription accuracy), `multi` (Hindi and English, handling callers who switch mid-sentence), and `indic` (ten Indian languages, following the caller as they switch). It also gates which languages the call may open in — you cannot greet in Tamil on a number set to `en`. → [Languages](/channels/voice-languages)

### Channel

A kind of touchpoint where customers reach you: web chat, WhatsApp, or voice. Distinct from a **channel connection**, which is a specific one you own and have verified — this website's domain, that WhatsApp Business number, this phone number. Connections are created and verified in the console; the API does not create them. → [How it fits together](/concepts/architecture)

### Chunk

A passage of your content, indexed on its own. Ingested sources are split into passages of roughly 1,600 characters on paragraph boundaries, each carrying the last 200 characters of the previous one so a fact straddling a boundary is not lost. Retrieval works at this granularity: the agent is given passages, never whole documents. The console reports source sizes in chunks, which is a useful proxy for how much an agent actually knows. → [Knowledge bases](/build/knowledge)

### Contact

A person in your customer directory, holding a name, phone, email, WhatsApp identifier, tags, and per-channel consent. Contacts are matched on email, phone, and WhatsApp ID, and an existing contact is enriched only in its empty fields — a supplied value never overwrites one that is already there. There is no merge: conflicting identities stop the operation for a human to resolve. → [Conversations and contacts](/concepts/conversations)

### Conversation

One continuous exchange between a customer and an agent on one channel, with a full transcript. Conversations are per channel by design, so the same person messaging you on WhatsApp and chatting on your website has two conversations linked by one contact. The public transcript contains only `user` and `model` messages; the internal record of what the agent looked up or called is kept separately and shown only in the console inbox. → [Conversations and contacts](/concepts/conversations)

### Deployment

An agent version, on a channel connection, with channel-specific configuration — the only object that decides what a real phone number, WhatsApp sender, or website widget actually does. It moves through `draft` → `ready` → `active` → `superseded` or `archived`. Editing an active deployment is refused; the supported path clones it, validates the clone, and activates it, so a bad edit can never take down a working number. → [Deployments](/build/deployments)

### DID

Direct Inward Dialling number — the phone number customers actually dial, provisioned to your workspace. A DID is inert on its own: it rejects calls until an agent is explicitly deployed to it, and a workspace-wide voice setting will not substitute for that. It also serves as the caller ID for outbound calls, and the API will only place a call from a DID your workspace owns and has active. → [Numbers and KYC](/channels/phone-numbers)

### Idempotency key

A value you send as the `Idempotency-Key` header on a request that spends money, so a retry cannot double-send. Replaying the same key with the same body returns the original stored response without touching the provider; replaying it with a *different* body is a `409` with `idempotency_key_reuse`. Keys are scoped to your workspace, the specific API key, and the endpoint, and they expire after 24 hours. → [Idempotency](/api/idempotency)

### Knowledge base

A container of sources that an agent can be taught from. Creating one does not make any agent smarter — an agent only sees knowledge explicitly attached to it, and the same knowledge base can teach several agents at once. Deleting a knowledge base stops its content serving every connected agent immediately, without a republish. → [Knowledge bases](/build/knowledge)

### Opening language

The language a phone call opens in, set per voice deployment as **Greet callers in**. It is not the same as the call mode: the mode decides what the caller may speak, the opening language decides only the first line. The agent follows the caller from their first reply regardless, so an opening language is a starting register, not a constraint on the conversation. → [Languages](/channels/voice-languages)

### Public reference

The customer-safe identifier for a ticket, formatted `AM-` followed by eight uppercase hex characters — `AM-4F91C2E0`. It is what an agent reads back to a customer and what your team quotes in a reply, and it is derived from the ticket rather than being a sequential counter, so it reveals nothing about your volume. Every ticket has one, whether the agent created it or your backend did. → [Tickets](/api/tickets)

### Retrieval

The process of finding the passages most relevant to a customer's question and putting them in front of the model before it answers. It works on meaning rather than keywords, so a question and its answer need not share any words — and, equally, no amount of exact phrasing will find a passage that was never indexed. One search runs per attached knowledge base and the results are merged closest-first. → [Knowledge bases](/build/knowledge)

### Scope

A capability granted to an API key, named the way a customer would describe it out loud rather than after an HTTP route. There are exactly six: `messages:send`, `calls:write`, `conversations:read`, `contacts:write`, `tickets:write`, and `agents:read`. New keys are created read-only by default, on the principle that a key is easier to widen later than to un-leak. → [Scopes](/api/scopes)

### Sender

The WhatsApp Business number that messages go out from, and that customers reply to. A workspace can have more than one, and an agent can be pinned to a specific sender or use the workspace default. The sender is also what the 24-hour window is tracked against, so a customer's window with one of your numbers says nothing about their window with another. → [Set up WhatsApp](/channels/whatsapp)

### Source

One item of content or connectivity inside a knowledge base. There are exactly five types: `website` (crawled), `file` (uploaded documents and images), `text` (pasted), `endpoint` (your HTTP API, either ingested on a schedule or called live), and `mcp` (an MCP server whose tools become abilities). Each source reports its own status and, where applicable, its own refresh schedule. → [Knowledge bases](/build/knowledge)

### Template

A WhatsApp message whose wording Meta has approved in advance, with placeholders for the values you fill in at send time. Templates are the only thing you can send outside the 24-hour window, which makes having at least one approved utility template the difference between reaching a customer and not. Categories that work end to end are `UTILITY` and `MARKETING`; an agent can only send templates you have explicitly added to its allowlist. → [Templates](/channels/whatsapp-templates)

### Ticket

A unit of support work, created by an agent when it cannot finish the job, by your team in the console, or by your backend over the API. It carries a status, a priority, an assignee, an SLA clock set at creation, the originating conversation, and a public reference. Tickets are the supported path from AI to human — the inbox itself is read-only, so escalation is what a hand-off means here. → [Tickets](/api/tickets)

### Tool

Something the agent can *do* rather than know. Four are built in — `create_support_ticket`, `send_whatsapp_message`, `search_knowledge`, and `end_call` — and your own tools are built as `endpoint` or `mcp` sources on a knowledge base, each declaring whether it reads or acts. A disabled tool is not declared to the model at all, so it cannot be attempted and refused; it does not exist. → [Tools and actions](/build/tools)

### Version

An immutable snapshot of an agent: its persona, its knowledge bindings, and its tool policy, frozen together with a sequence number and a configuration hash. There is no edit path for a published version, which is exactly what makes "roll back to version 3" mean something — version 3 is still the agent that worked, including which knowledge it was allowed to see. Publishing creates a version; it does not deploy it. → [Agents and versions](/build/agents)

### Webhook

An HTTPS endpoint of yours that we POST to when something happens, so your systems learn about events without polling. Nine event types exist, covering messages, conversations, calls, tickets, and leads. Every delivery is signed, and you must verify the signature against the raw request body — parsing the JSON and re-serialising it changes the bytes and the signature will not match. → [Webhooks](/webhooks/overview)

### Workspace

Your organisation, and the isolation boundary for everything else. It owns the agents, the knowledge, the channel connections, the conversations, the contacts, the API keys, and the bill. Every query is filtered by workspace before anything else happens, and there is no mechanism — no sharing setting, no cross-workspace agent, no shared knowledge base — for data to cross it. → [Workspaces and roles](/concepts/workspace)


============================================================================
# SECTION: Build an agent
============================================================================



----------------------------------------------------------------------------
## Agents & versions
URL: https://docs.amomic.in/build/agents
----------------------------------------------------------------------------

An agent is the thing your customer talks to. You write it once — a name, a purpose, some instructions, the knowledge it may use, the tools it may call — and every channel renders that same agent appropriately. This page covers the fields, what each one actually does to behaviour, and the publish-and-version mechanism that makes it safe to edit an agent that is currently live.

If you have not read [How it fits together](/concepts/architecture), read it first. It explains why an agent, a version, and a deployment are three different things; this page assumes you know.

```mock
{"component": "AgentsScreen", "props": {"caption": "Agents you have built. Each card shows its publication state, its channels, and how much of its knowledge is ready."}}
```

## Creating an agent

**Agents → New agent.** Four fields, and only two are required.

| Field | Required | Limit | What it does |
|---|---|---|---|
| **Agent name** | Yes | 60 characters | What your team calls it, and what a customer sees on the web widget and hears on a call. |
| **Purpose** | Yes | 500 characters | The outcome this agent owns. This becomes the spine of its behaviour. |
| **Additional instructions** | No | 4,000 characters | Style, tone, and specific rules that are not a policy fact. |
| **Business knowledge** | Yes (defaulted) | — | Whether a ready knowledge base is required before this agent may be published. |

The agent is created as an unpublished draft. Nothing is provisioned, no channel is touched, no customer can reach it. You can create it, forget about it for a week, and come back.

::: note The name is customer-facing on some channels
On a phone call the outbound opening line uses the agent name — "this is Asha, a virtual assistant calling on behalf of…" — so `Support Agent v2 (test)` is a name your callers will hear. Use something you would say out loud.
:::

### Business knowledge: `required` vs `no_business_knowledge`

This is a two-option select, and it is the single setting most likely to prevent an embarrassing launch.

| Option in the console | Stored value | Effect |
|---|---|---|
| Require a ready knowledge base before publishing | `required` | The agent's readiness check fails until at least one attached knowledge base is serving content. You cannot publish an empty agent by accident. |
| No business knowledge — safe general behavior only | `no_business_knowledge` | You are stating on the record that this agent answers with no company-specific content. Readiness stops asking for knowledge. |

Leave it on `required` unless you are deliberately building something that has nothing to look up — a pure call-router, or a bot whose only job is to open a ticket. The moment an agent is expected to answer a question about *your* business, `required` is the setting that stops it going live with nothing to stand on.

## Writing a purpose that produces a good agent

The purpose field is 500 characters and it does more work than anything else you will type. It is not a description for your colleagues. It is the sentence the agent uses to decide, on every single turn, whether a question is its job.

A vague purpose does not produce a vague agent. It produces a *confident* agent with no boundaries — one that answers billing questions it has no information about, because nothing told it that billing was not its job.

### The shape that works

A good purpose answers three questions in order:

1. **What does it resolve?** The concrete outcomes, named.
2. **From what?** The authority it is allowed to draw on.
3. **What does it hand off?** The line it does not cross.

That is it. Three clauses, usually under 300 characters.

### Before and after

**Support agent — before:**

> Help customers.

Two words, and every one of the three questions is unanswered. This agent will attempt anything anyone asks it, including questions about pricing tiers it has never seen and complaints it cannot resolve. It has no reason to hand anything off, so it will not.

**Support agent — after:**

> Answer delivery, refund, and order-status questions from our published policy; hand off anything about billing.

Now the agent knows three topics are in scope, that the published policy is the authority, and that billing is somebody else's. When a customer asks about a failed payment, it opens a ticket instead of improvising a refund rule.

---

**Receptionist — before:**

> Answer the phone for our clinic.

This describes the channel, not the job. "Answer the phone" is what the deployment does. The agent still does not know what a successful call looks like.

**Receptionist — after:**

> Tell callers our timings, location, and which doctors are available on which days, from the clinic information sheet. Take a callback request for anything about test results or fees.

Note what changed: the outcomes are named, the source is named, and there is an explicit escape hatch that produces a concrete action rather than an apology.

---

**Order desk — before:**

> Handle customer queries about orders and be helpful and friendly. Our company was founded in 2019 and we sell home appliances across India with a focus on customer satisfaction.

This is the most common failure and it looks like effort. Half the field is company background — which belongs in a knowledge base, where it can be searched and updated — and the operative half is still "handle queries". Worse, facts written into the purpose are frozen into the published version, so when they change you must republish the agent rather than re-crawl a page.

**Order desk — after:**

> Resolve order-status, delivery-date, and return-eligibility questions using the order lookup tool and our returns policy. Confirm the order number before quoting anything. Escalate damaged-on-arrival cases to a ticket.

### Rules of thumb

- **Name the outcomes, not the audience.** "Support our B2B customers" is not an instruction. "Answer contract, invoice, and onboarding questions" is.
- **Describe the job, not the channel.** The same agent runs on the widget, WhatsApp, and the phone. A purpose that says "reply to WhatsApp messages" is wrong on two of the three.
- **Always include the hand-off clause.** An agent with no stated boundary treats every question as in scope. One sentence — "hand off anything about X" — is what makes it reach for [`create_support_ticket`](/build/tools) instead of guessing.
- **Do not put facts in the purpose.** Prices, timings, and policies belong in a [knowledge base](/build/knowledge). Facts in the purpose can only be changed by publishing a new version; facts in a knowledge source can be re-crawled without touching what is live.
- **Read it back as an instruction to a new hire on day one.** If a competent human could not act on it, neither can the agent.

## Additional instructions

Instructions are for *how*, once the purpose has settled *what*. Four thousand characters is a lot of room, and most of it should stay empty.

Good instructions look like:

```text
Be concise — two or three sentences unless the customer asks for detail.
Ask one clarifying question at a time, never a list.
Quote the refund window exactly as written in the policy; never round it.
If a customer is angry, acknowledge it once and move to the fix.
Never invent an order number, a date, or a policy detail.
```

Bad instructions look like a second purpose, or a knowledge base in disguise ("Our office hours are 9 to 6…"). If a line contains a fact that could change, it is in the wrong place.

::: danger Never put credentials in instructions
The console says this next to the field and it is worth repeating: no API keys, no access tokens, no customer secrets, no internal URLs with a token in the query string. Instructions are copied verbatim into every published version and are visible to anyone in the workspace who can open the agent. Credentials for a tool belong in the source's headers, where they are moved into encrypted storage and never shown again — see [Tools and actions](/build/tools).
:::

## Persona settings

The **Persona** tab is where the agent lives after creation. It holds everything from the create form plus three more controls.

| Field | Options | Notes |
|---|---|---|
| **Agent name** | 60 characters | Same field as on create. |
| **Language** | `English` (`en`), `Hindi` (`hi`), `Multilingual` (`multi`) | The register the agent writes and speaks in. `multi` lets it follow the customer. |
| **Purpose** | 500 characters | |
| **Instructions** | 4,000 characters | |
| **Grounding policy** | `Strictly grounded` (`grounded`), `Balanced` (`balanced`) | How tightly it must stay inside your content. |
| **Knowledge requirement** | `required`, `no_business_knowledge` | Same setting as **Business knowledge** on create. |

Everything on this tab is channel-neutral. There is no per-channel persona — you cannot give WhatsApp one tone and voice another. If two channels genuinely need different behaviour, build two agents.

### Grounding policy

`grounded` is the default and it is the right default.

- **`grounded`** — the agent answers from retrieved passages and says it does not know when the content does not cover the question. It will still be conversational; it will not fill a gap with something plausible.
- **`balanced`** — the agent leans on your content but is permitted more general reasoning around it.

Choose `balanced` only when you have watched a `grounded` agent in the test tab refuse things you were happy for it to answer. Turning it up because answers feel "stiff" usually means the knowledge base is thin, and the fix is a source, not a policy.

### Language versus voice language

The persona **Language** field is not the same thing as a voice deployment's call language.

| Setting | Where it lives | What it controls |
|---|---|---|
| Persona **Language** | The agent, frozen into every version | The register the agent thinks and writes in across all channels |
| **Call language** and **Greet callers in** | The voice deployment, per phone number | What a caller may speak, and which language the call opens in |

A number can open in Hindi while the agent's persona language is `multi`. See [Languages](/channels/voice-languages) for the full matrix.

## What publishing does

While you are editing, you are editing a draft. Nothing you type reaches a customer.

Choosing **Publish** captures the current state of the agent as a **version**, and the console is precise about what "current state" means:

- the **persona** — name, language, purpose, instructions, grounding policy, knowledge requirement
- the **knowledge bindings** — which knowledge bases are attached, and which revision of each
- the **tool policy** — which tools are enabled, which WhatsApp templates are allowed, whether action tools may fire

Those three are snapshotted together, stamped with a sequence number and a configuration hash, and written once. **There is no update path for a published version** — not in the console, not in the API, not for support. The only way to change anything is to publish another one.

Your next keystroke starts a fresh draft. The agent's badge moves to `Changes to publish` and the version that is actually running does not move.

### Why immutability is the point

Three things become true only because versions cannot be edited.

**You can work on a live agent in the middle of the day.** Rewrite the instructions, re-crawl the website, attach a new knowledge base, run twenty test conversations — the version deployed on your phone number keeps answering exactly as it did this morning. Nothing in the studio reaches a customer until you publish *and* deploy, both on purpose.

**"Roll back to version 3" means something.** If versions could be edited, rolling back would mean returning to whatever version 3 has become since. Because they cannot, version 3 is still exactly the agent that worked — including which knowledge it was permitted to see.

**An incident has a fixed subject.** When a customer reports a bad answer from last Tuesday, the version that produced it still exists, unchanged, with its config hash. You can read it instead of reconstructing it.

::: warning Publishing is not deploying
Publishing creates a version. It does not put that version anywhere. Until you deploy it to a channel connection, a freshly published agent shows `Published, not deployed yet` and no customer can reach it. See [Deployments](/build/deployments).
:::

## Publication badges

The agents list shows one of three strings per agent. They are worth learning because they answer "is my change live?" without opening anything.

| Badge | Meaning |
|---|---|
| `Not published` | The agent has never been published. It has no version, so it cannot be deployed. |
| `Published` | Every change you have made is captured in the current version. The draft is clean. |
| `Changes to publish` | There is a published version *and* a newer draft. What is live is the older one. |

Two more strings appear where deployment matters: `Published, not deployed yet` (a version exists but nothing is serving it) and `Not deployed yet`.

Inside the agent studio the same three states read as `Published`, `Unpublished changes`, and `Not published`, and the **Overview** tab shows the underlying draft state directly — `clean` or `unpublished changes`.

::: tip `Changes to publish` is not a warning
It is the normal, healthy state of an agent someone is improving. It becomes a problem only when you believed you had shipped something. If a fix is not visible to customers, this badge is the first place to look.
:::

## Version history and rollback

The **Versions** tab lists every published version, newest first. Each row carries:

- `Version {n}` and, on one of them, a `Current` badge
- the change summary you wrote, or `Published configuration` when you wrote none
- how many knowledge bindings the version froze
- when it was published, and a truncated configuration hash

The configuration hash is the fastest way to answer "did anything actually change?" Two versions with the same hash are the same agent.

::: tip Write the change summary
It costs five seconds and it is the only human-readable record of why a version exists. `Added the 2026 returns policy and stopped it quoting delivery estimates` is worth far more in three months than `Published configuration`.
:::

### Rolling back

Rollback happens at the deployment layer, not the agent layer. A deployment names one specific agent version, so restoring old behaviour means putting the old version back on the connection:

::: steps

::: step Find the deployment that is serving the bad behaviour

Open the agent's **Deployments** tab and identify the channel and connection — the phone number, the WhatsApp sender, or the site.
:::

::: step Roll it back to the previous deployment

The previous deployment on that connection is still there, marked `Replaced`. Rolling back re-activates its configuration and its agent version in a single transaction, superseding the bad one. Your draft is untouched.
:::

::: step Fix the draft, then publish forward

Rollback buys you time; it is not a fix. The draft still contains whatever caused the problem. Correct it, test it, publish a new version, and deploy that.
:::

:::

[Deployments](/build/deployments) covers activation, supersession, and the clone rule in full.

## Archiving an agent

Archiving removes an agent from daily work without deleting anything. Conversations, calls, and published version history are all kept, and you can restore it from the **Archived agents** section at any time.

**Archiving is blocked while anything is live.** If the agent has active deployments, the console tells you how many and refuses until you pause them from the **Deployments** tab. That is deliberate — archiving is a tidying action, and tidying should never silently drop a customer's call.

## How many agents you can have

Agent count is capped by your plan, and there is a hard workspace backstop of 20 agents regardless of plan. Most workspaces need far fewer than they expect: one agent serving four channels is the normal shape, not four agents.

Build a second agent when the *job* differs — a sales qualifier and a support resolver have different purposes, different knowledge, and different hand-off rules. Do not build a second agent because you have a second channel. See [Limits and plans](/operate/limits).

## Where to go next

::: cards

::: card Give it something to know
[Knowledge bases](/build/knowledge) — the five source types, how retrieval actually works, and how to get good answers out of it.
:::

::: card Let it do things
[Tools and actions](/build/tools) — the built-in tools, and how to turn your own API into something the agent can call.
:::

::: card Find the bad answers first
[Testing and publishing](/build/testing) — what to test, the two failure modes worth hunting, and the readiness checks.
:::

::: card Put it in front of customers
[Deployments](/build/deployments) — the lifecycle, what activation does, and why editing a live deployment clones it.
:::

:::


----------------------------------------------------------------------------
## Knowledge bases
URL: https://docs.amomic.in/build/knowledge
----------------------------------------------------------------------------

A knowledge base is a container of sources. You point it at your website, your documents, your pasted text, or your live systems; the platform reads all of it, splits it into passages, and indexes each passage by meaning. When a customer asks something, the closest passages are found and put in front of the model before it answers.

That is the whole mechanism, and understanding it is what separates an agent that answers correctly from one that confidently invents a refund window.

```mock
{"component": "RetrievalDiagram", "props": {"caption": "A question becomes a meaning-based search over your passages. The closest ones are put in front of the model, which answers from them."}}
```

## Indexed by meaning, not by keyword

This is the part that surprises people, so it comes first.

Your content is not stored as searchable text. Each passage is converted into a numeric representation of what it *means*, and a customer's question is converted the same way. Retrieval finds the passages whose meaning sits closest to the question.

The practical consequences:

- **Wording does not have to match.** A page that says "orders are dispatched within 48 hours of confirmation" answers "when will you ship my stuff?" without sharing a single significant word.
- **Adding more content can make answers worse.** Every passage competes. A knowledge base holding your help centre answers well; the same knowledge base with your entire marketing site added answers worse, because press releases and careers pages now sit between the question and the passage that holds the answer.
- **Structure matters more than volume.** A passage that reads as a complete thought retrieves well. A passage that is half of a table, or a heading with no body under it, does not.
- **There is no keyword fallback.** If a passage does not exist, no amount of exact phrasing will conjure it. "It should have found that" almost always means "that page was never crawled" or "that fact is inside an image".

## The five source types

There are exactly five. Choose by asking what kind of thing you are teaching the agent.

| Type | Console tab | Use it for | Refreshable |
|---|---|---|---|
| `website` | **Website** | Anything already published on your site — help centre, FAQ, policies, product pages. | Yes |
| `file` | **Files** | Documents that exist as documents — a price list, a policy PDF, an onboarding deck. | No |
| `text` | **Text** | Facts that live nowhere else. The three-line exception nobody wrote down. | No |
| `endpoint` | **API** | Data from your own systems, either ingested on a schedule or looked up live mid-answer. | Yes, when ingested |
| `mcp` | **MCP** | An MCP server whose tools become abilities the agent can call. | No |

```mock
{"component": "KnowledgeScreen", "props": {"caption": "A knowledge base with its sources, their status, and which agents are connected to it."}}
```

### `website`

Paste one URL. The crawler starts there and reads the same site.

**What it does:**

- Honours `robots.txt`, then looks for a sitemap, then falls back to following links within the site.
- Stays on the same site — the exact host or a subdomain of it, ignoring `www.`. It will not wander onto a different domain.
- Renders JavaScript, so single-page applications and content that loads after the initial HTML are read correctly.
- Skips cart, checkout, and admin paths, and skips binary assets.
- Drops query strings when deciding whether it has already seen a page, so `?utm_source=` variants do not produce duplicates.
- Reads up to about sixty pages per source.

**What it does not do:** there is no crawl-configuration screen. You do not set a page limit, a crawl depth, include or exclude patterns, or a JavaScript toggle — those are not exposed anywhere in the product. The only input is the starting URL.

That constraint is exactly why the starting URL matters so much. See [Scope the crawl narrowly](#scope-the-crawl-narrowly) below.

**When a crawl fails**, the source carries the reason in plain words rather than a code:

| What you see | What it means |
|---|---|
| `That address can't be reached from the crawler.` | The URL does not resolve, or the site is not reachable from the public internet. Staging behind a VPN will fail here. |
| `Couldn't read any pages from that website.` | The crawler reached the host but got nothing usable — often a hard block on automated traffic. |
| `We reached the site but couldn't read any text on it.` | The pages rendered but contain no readable text. Usually a site built entirely from images or an unusual embed. Paste the content as `text` or upload the documents instead. |

### `file`

Upload documents directly. Accepted: `pdf`, `docx`, `doc`, `xlsx`, `xls`, `csv`, `txt`, `md`, `html`, `htm`, plus the image formats `png`, `jpg`, `jpeg`, `webp`, `gif`. **Maximum 15 MB per file.**

Images are read visually and converted into text, which means a screenshot of a price table can become usable knowledge. It also means a 40-page PDF of scanned pages will work but produce messier passages than the same content as real text. If you have the source document, upload that rather than a scan of it.

Files are never re-read on a schedule. When the document changes, upload the new one and delete the old — otherwise both versions are in the index and the agent will sometimes retrieve last year's prices.

### `text`

A title and a body, typed or pasted. Underrated.

Use it for the things that are true but unpublished: the actual escalation path, the exception you make for enterprise customers, the fact that the number on the contact page is no longer monitored. These are usually the highest-value passages in a knowledge base because they exist nowhere the crawler can reach.

Keep each text source to one topic with a descriptive title. `Shipping policy` retrieves better than `Notes`.

### `endpoint`

Your own HTTP API, in one of two modes:

- **Ingest the response** — fetched now and on a schedule, converted to text, and indexed as passages. This is knowledge: a product catalogue, a branch list, a rate card.
- **Call it live** — never ingested. Registered as a function the agent calls mid-answer for data that changes by the minute: stock, availability, a specific order's status.

A live endpoint is where a knowledge base stops being knowledge and starts being a tool. It also carries a capability — `read` for a lookup, `action` for something that changes state in your system. [Tools and actions](/build/tools) covers both modes, the capability rules, and the safety model in full.

::: note There is no "test connection" button
Neither the API tab nor the MCP tab has a verify or test control. You add the source and watch its status: it moves to `Connected` when it worked, or shows `Failed` with the reason. Use the [retrieval tester](#the-retrieval-tester) and the agent's test tab to confirm behaviour.
:::

### `mcp`

Point at an MCP server URL and the tools it lists become abilities your agent can use. Because MCP does not tell us which of a server's tools change data and which only read, you classify the **whole server** once — look-up or action — and every tool on it inherits that classification. You can optionally restrict which tool names are allowed; leaving that empty allows everything the server lists.

Again, see [Tools and actions](/build/tools) — an MCP server is a tool surface, not a body of knowledge.

## What happens to your content

Every ingested source goes through the same pipeline.

::: steps

::: step Read

The crawler fetches pages, the file reader extracts text from documents and images, the endpoint fetcher converts a response into readable lines.
:::

::: step Split into passages

The text is cut into passages of roughly 1,600 characters, split on paragraph and line boundaries rather than mid-sentence. Each passage carries the last 200 characters of the one before it, so a fact that straddles a boundary is not lost. Fragments under 80 characters are discarded. A single source produces at most 1,500 passages.
:::

::: step Index by meaning

Each passage is indexed together with its title, so a passage from a page called *Returns and refunds* is easier to find for a refund question than the same words on an untitled page.
:::

::: step Serve

The passages become searchable for every agent the knowledge base is attached to. Re-syncing is last-good-serving: the old passages keep answering until the new ones are fully indexed, so a re-crawl never leaves an agent briefly knowing nothing.
:::

:::

When a customer asks a question, one nearest-neighbour search runs **per attached knowledge base** and the results are merged, closest first. Roughly the six best passages reach the model. Passages that are not close enough to the question are dropped rather than padded out — which is why a `grounded` agent says it does not know instead of answering from something vaguely related.

On voice calls there is one extra step: the knowledge base is also compressed into a compact fact sheet that the agent holds in mind for the whole call, so ordinary questions are answered without a lookup round-trip. Anything the fact sheet does not cover triggers a real search through the `search_knowledge` tool. This is why voice feels faster than the same question on chat, and why a very large knowledge base still answers common questions instantly.

## Source status

Each source shows where it is in that pipeline.

| Underlying status | What you see in the console | Meaning |
|---|---|---|
| `pending` | `Syncing…` | Queued, not started. |
| `crawling` | `Crawling {done}/{found}` | Website only. Live progress — pages read out of pages discovered. |
| `processing` | `Syncing…` | Text extracted; passages being indexed. MCP tool discovery also happens here. |
| `ready` | `Synced ✓` or `Connected` | Serving. `Synced ✓` for ingested sources with a passage count; `Connected` for live endpoints and MCP servers, which have no passages by design. |
| `error` | `Failed` | Something went wrong. The row shows the reason inline. |

A source that shows `Connected` with zero passages is working correctly — a live tool has nothing to ingest.

## Refresh scheduling

Ingested sources can re-read themselves on a schedule. The **Keep it fresh** control offers exactly four options:

| Console label | Value | Interval |
|---|---|---|
| Only when I re-sync | `manual` | Never automatic. The default. |
| Every day | `daily` | 24 hours |
| Every week | `weekly` | 7 days |
| Every month | `monthly` | 30 days |

::: warning There is no hourly option
The shortest automatic interval is `daily`. If your content changes more often than that, a scheduled re-crawl is the wrong tool — use a **live** `endpoint` source, which fetches at answer time and is always current.
:::

**Only two source types can be scheduled:** `website`, and `endpoint` in ingest mode. Text, files, and MCP servers are always `manual` — there is nothing to re-read for the first two, and a live tool is current by definition.

A few behaviours worth knowing:

- The next-refresh clock is pushed forward *before* a refresh starts, so a source that fails does not hot-loop. It retries at its next scheduled interval.
- A source already syncing is skipped by the scheduler, and a manual re-sync on it is refused with `This source is already syncing.`
- After a successful refresh, every agent attached to that knowledge base picks up the new content — including a rebuilt voice fact sheet. You do not republish the agent for a content refresh.

You can always force a refresh: hover a source row and choose **Re-sync**. Admin or owner only.

## Attaching knowledge to an agent

**An agent can only answer from knowledge you have explicitly attached to it.** Creating a knowledge base does not make any agent smarter. There is no default, no workspace-wide pool, no implicit access.

Attach from either end:

- From the agent's **Knowledge** tab — choose a knowledge base and **Attach**.
- From the knowledge base's **Connected agents** card — **Connect**.

Each attachment row shows the knowledge base's serving state as a raw value:

| State | Meaning |
|---|---|
| `empty` | Attached, but it has no content yet. An agent whose knowledge requirement is `required` will not pass readiness. |
| `ready` | Serving content. |
| `degraded` | Serving, but something is not fully healthy. |
| `unavailable` | Not currently serving. |

The same knowledge base can teach several agents at once, which is the normal shape — one *Company policies* knowledge base attached to your support agent, your receptionist, and your order desk.

**Bindings are versioned with the agent.** Attaching or detaching changes the draft; the change reaches customers when you publish a new version. A content *refresh* is different — a validated refresh advances the knowledge base's active revision without changing the binding, so new content flows to live agents without a republish.

Detaching is a soft archive, not a deletion. The knowledge base and its content are untouched; the agent stops seeing it on the next published version.

::: danger Deleting is immediate and global
Deleting a knowledge base stops its passages serving **every** connected agent at once, including live ones, without a republish. The console tells you how many passages will stop serving. Deleting a single source removes its passages from every agent's memory the same way. There is no undo.
:::

## Credentials for authenticated sources

Endpoint and MCP sources can carry up to ten HTTP headers — an API key, a bearer token, a signed cookie.

- Values go **straight into encrypted secret storage** at the moment you add the source. They are never written into the knowledge base record, never returned by any read, and never shown again in the console.
- The console keeps only the header *names*, plus a `Key secured` indicator on the row.
- To rotate a credential, re-enter it on the source. The pointer does not change, so nothing else needs updating.
- Auth is header-based only. There is no OAuth flow and no client-certificate option.
- If a credential goes missing, the source reports `This source's credentials are missing; re-enter them on the source.` rather than failing silently mid-conversation.

The platform also refuses to store credential-shaped fields anywhere they do not belong — a deployment or channel configuration containing a key called `token`, `password`, `api_key` or similar is rejected outright. Secrets have exactly one place to live.

## Getting good answers

Adding sources takes minutes. Getting a knowledge base that answers your customers' actual questions takes about an hour of deliberate work. This is that hour.

### Scope the crawl narrowly

Since there is no crawl-configuration UI, the starting URL is your only control — and it is a strong one, because the crawler stays on the same site and reads a bounded number of pages.

- Point it at `https://yourcompany.com/help`, not `https://yourcompany.com`.
- If your help centre lives on its own subdomain, that is even better.
- If your policies, your blog, and your careers page all live under one root, add *separate sources* for the specific sections rather than one source for the root.

Two reasons. First, retrieval quality: fewer irrelevant passages means the right one wins more often. Second, the page budget: sixty pages spent on your help centre is a complete help centre, while sixty pages spent from your homepage is your navigation, your blog index, three press releases, and possibly no policy page at all.

::: tip Check what actually got read
After the crawl finishes, look at the passage count on the source row. A twelve-page help centre that produced eight passages did not work — go and look at those pages in a browser with JavaScript disabled, and you will usually find the content arrives from somewhere the crawler could not follow.
:::

### Prefer structured pages

Content that retrieves well shares a shape: a clear heading, a self-contained answer beneath it, in prose.

Content that retrieves badly:

- **Answers buried in tables.** A shipping matrix with regions across the top and weights down the side is perfectly readable to a human and nearly meaningless once flattened into a line of text. Rewrite the ten most-asked rows as sentences in a `text` source: "Delivery to Mumbai for orders under 5 kg takes 2 to 3 working days."
- **Answers inside images.** A price card exported as a PNG, an infographic of the returns process, a screenshot of the timings board. Images uploaded as files are read visually and will work; the same image embedded in a crawled web page will not be read. This is the single most common cause of "it should have known that".
- **Answers in PDFs behind a login.** The crawler is an anonymous visitor. Upload the file instead.
- **Accordion and tab content that loads on click.** JavaScript is rendered, but content that requires a click to fetch may not be there when the page is read. Check with the retrieval tester.
- **One enormous page.** A 20,000-word policy document becomes many passages that all look alike. Split it, or add a short `text` source with the ten facts customers actually ask about.

### Say the exceptions out loud

Your published content describes the policy. Your team knows the exceptions. Customers ask about the exceptions.

Write a `text` source for each one. "Refunds are 14 days, but for orders shipped to the North-East the clock starts on delivery, not dispatch." Nothing on your website says that, so nothing in your index does either, and the agent will confidently quote 14 days from dispatch.

### The retrieval tester

Every knowledge base has a **Retrieval tester** — a search box that shows exactly which passages the agent would look up for a given question, without involving the model at all.

This is the sharpest debugging tool in the product, because it separates two failures that look identical from the outside:

- **The tester returns nothing relevant** — `Nothing relevant found — the agent would say it doesn't know.` The passage does not exist or is not close enough. This is a *content* problem. Add or rewrite a source.
- **The tester returns the right passage but the agent still answered badly** — retrieval worked and the model did not use it. This is a *persona* problem. Look at the purpose, the instructions, and the grounding policy in [Agents and versions](/build/agents).

Every member of the workspace can use the retrieval tester, including those who cannot edit knowledge.

### Then test as a customer

The retrieval tester tells you what was found. The agent's **Test** tab tells you what the customer hears. Use both, in that order, and use the questions your team gets wrong rather than the ones you know are covered. [Testing and publishing](/build/testing) covers what to look for.

## Limits

| Limit | Value |
|---|---|
| Knowledge bases per workspace (hard backstop) | 50 |
| File upload size | 15 MB |
| Passages per source | 1,500 |
| Endpoint or MCP response size | 2 MB |
| Tools listed per MCP server | 20 |
| Headers per source | 10 |

Plan tiers cap how many knowledge bases you can create below that backstop — see [Limits and plans](/operate/limits). Sources, passages, and crawl pages are not capped by plan.

## Who can change knowledge

Creating a knowledge base, adding or deleting sources, renaming, re-syncing, and connecting or disconnecting agents are all **admin or owner** actions. Members see the knowledge bases, their sources, and the retrieval tester, but the write controls are not shown to them at all. See [Workspaces and roles](/concepts/workspace).

## Where to go next

::: cards

::: card Turn a source into an ability
[Tools and actions](/build/tools) — live endpoints, MCP servers, and the difference between reading and doing.
:::

::: card Find the gaps before customers do
[Testing and publishing](/build/testing) — the two failure modes worth hunting, and readiness.
:::

::: card Tune the agent that reads it
[Agents and versions](/build/agents) — purpose, instructions, and the grounding policy.
:::

:::


----------------------------------------------------------------------------
## Tools & actions
URL: https://docs.amomic.in/build/tools
----------------------------------------------------------------------------

Knowledge lets an agent answer. Tools let it *act*. A tool is a named capability the agent can decide to invoke mid-conversation — opening a ticket, sending a message, looking up a live order, cancelling a booking — and the difference between a helpful agent and a merely articulate one is usually a tool.

This page covers the four tools that ship built in, how to build your own on top of a knowledge base, and the policy layer that decides what any of them may do.

## What a tool is

To the model, a tool is a name, a description of when to use it, and a set of typed parameters. On each turn it may either answer or call a tool; if it calls one, the result comes back and it continues from there. The loop runs at most three rounds before the agent is forced to answer with what it has, so a tool that misbehaves cannot trap a customer in silence.

Three properties are worth internalising before you build anything:

- **The description is the control surface.** The agent decides whether to call a tool almost entirely from its description. "Check stock" invites speculative calls; "Use when the customer asks whether a specific product is currently available, after they have named the product" does not.
- **A tool the agent cannot see cannot be called.** Disabling a tool does not add a rule telling the model to avoid it — the tool is never declared, so it does not exist as far as the model is concerned. That is a much stronger guarantee than an instruction.
- **Tool failures never surface as errors.** If a tool throws or times out, the failure is handed back to the model as text and it recovers in conversation. A customer sees "I could not reach our order system right now" rather than a stack trace or an abrupt silence.

## The built-in tools

Four tools ship with the platform. These are their exact registered names — what the model sees, and what you will see in a transcript.

| Tool | Available on | Enabled by default |
|---|---|---|
| `create_support_ticket` | Every channel | Yes |
| `send_whatsapp_message` | Every channel | No |
| `search_knowledge` | Voice calls only | Yes, when the agent has knowledge |
| `end_call` | Voice calls only | Yes |

### `create_support_ticket`

Creates a support ticket and resolves or creates the customer's contact record in one guarded action. It returns a status and the ticket's public reference — `AM-4F91C2E0` — which the agent can read back to the customer.

**When the agent reaches for it:** when the customer asks for a human, asks for follow-up, asks to escalate, or has an unresolved problem that needs staff action. It is the mechanism behind every "let me get someone to look at this".

**How identity is resolved**, per channel — the agent never asks for information the channel already knows:

| Channel | What it uses |
|---|---|
| Web chat | Asks first name, then email; asks for a phone number only when creating a new contact |
| WhatsApp | The chat's own number. Asks for an email only if the contact record has none |
| Voice | The caller's number, automatically. The email and phone parameters are **structurally removed** from the tool on calls |
| Email | The sender's address, automatically |

That voice behaviour is deliberate and worth understanding. Speech recognition is not reliable enough to transcribe an email address or a phone number correctly, so rather than accepting a plausible-looking wrong address, the fields are removed from the tool entirely. The caller ID is the identity.

**Ticketing is idempotent within a conversation.** A retry — the customer asking again, the model calling twice — returns the same ticket rather than opening a duplicate.

The agent is also instructed never to claim a ticket exists until the tool has actually returned success. If ticket creation fails, the customer is told it failed.

See [Tickets](/api/tickets) for what happens next, and [Escalate to a ticket](/recipes/support-escalation) for the end-to-end shape.

### `send_whatsapp_message`

Puts a confirmation, a link, or a reference on the customer's phone — **from any channel**. A caller on the phone can be sent the booking reference by WhatsApp before they hang up. A web visitor can be sent the tracking link.

It is **off by default**, including for agents created before it existed. Turn it on from the agent's **Tools** tab.

**Who it can message.** By default, only the person the agent is already talking to. On WhatsApp itself, the customer's own WhatsApp ID is authoritative — if the model produces a different recipient, that recipient is ignored outright. There is one setting, **Allow messaging a different number**, that permits a model-chosen destination; it exists for cases like an order desk notifying a third party, and it is the one control that lets a customer's wording decide where a message goes. Leave it off unless you specifically need it.

**Which templates it may send.** You choose an explicit allowlist, up to 20 templates. That list becomes the set of values the `template_name` parameter will accept — the model literally cannot name a template you did not approve. If no template is approved yet, the agent can only reply inside an open WhatsApp conversation.

#### The closed-window result

WhatsApp permits free-form messages only within 24 hours of the customer's last inbound message. Outside that window, only pre-approved templates go out. See [The 24-hour window](/channels/whatsapp-window) for the rule itself.

What matters here is how the tool behaves when it hits that wall. It does not fail silently, and it does not quietly substitute different words. It returns a structured status the agent can reason about:

| Status | What happened |
|---|---|
| `sent` | The message went out. |
| `template_required` | The window is closed. Free text is not permitted; a template is needed. |
| `template_not_allowed` | A template was named, but it is not on this agent's allowlist. |
| `template_not_found` | The named template does not exist or is not approved. |
| `needs_information` | A required value is missing — a template variable, a recipient. |
| `opted_out` | The recipient has opted out of messages from you. |
| `needs_setup` | WhatsApp sending is enabled but no sender number is usable. |
| `not_configured` | WhatsApp is not connected for this workspace. |
| `failed` | The send was attempted and did not succeed. |

**The practical consequence:** on `template_required`, the agent knows *why* it could not send and can do something sensible — send an approved template instead, or tell the customer plainly that it cannot message them right now and offer another route. It does not tell the customer the message went out when nothing was sent. If you have approved no templates, this is the moment your agent starts apologising to customers at 2 a.m.; approving one utility template is usually the whole fix.

::: warning No template is sent automatically when a window closes
There is no hold-and-release queue and no automatic re-engagement. If the window closes with a message pending, the message does not go out later. Either the agent sends an approved template in the moment, or nothing is sent.
:::

### `search_knowledge`

**Voice calls only**, and only when the agent has knowledge attached.

On a call, the agent already holds a compressed fact sheet built from its knowledge base, so ordinary questions are answered without any lookup — which is what keeps a call feeling like a conversation rather than a query. `search_knowledge` is the long tail: when the caller asks for a specific detail the fact sheet does not carry, the agent searches the full knowledge base for it.

You do not configure this tool. It appears when the agent has content and disappears when it does not.

On chat channels there is no equivalent tool because retrieval is not a decision there — the relevant passages are put in front of the model before it answers. See [Knowledge bases](/build/knowledge).

### `end_call`

**Voice calls only.** Hangs up, after the agent's goodbye has finished playing.

This exists because a phone call needs an ending. Without it, an agent that has said goodbye sits on an open line waiting for a caller who has stopped talking, and the call ends on an idle timeout instead of a clean farewell. The tool waits for the spoken goodbye to complete before disconnecting, so the caller never hears themselves cut off mid-word.

## Building your own tools

Your own tools are **knowledge sources**. There is no separate integrations screen, no plugin directory, and no third-party connector marketplace — a tool is an `endpoint` or `mcp` source on a knowledge base, and it reaches an agent through the same attachment that gives it knowledge.

That is a deliberate design: the thing that decides what an agent knows also decides what it can do, so there is exactly one place to audit.

### Read tools versus action tools

Every custom tool declares a capability.

| Capability | Meaning | Example |
|---|---|---|
| `read` | Looks something up. Nothing in your system changes. | Order status, stock level, appointment availability, invoice balance |
| `action` | Changes something in your system. | Accept a return, cancel a booking, reschedule a delivery, apply a credit |

In the console these read as **Look up data** and **Take an action**, and a source configured as an action carries an `Action` badge wherever it appears.

The distinction is enforced, not advisory:

- A `read` tool may only use `GET` or `POST`. Choose `PUT`, `PATCH`, or `DELETE` and you are told `{method} changes data — set capability to 'action' to use it.`
- An `action` must be a live tool. It cannot be a scheduled ingest, because ingesting a `DELETE` on a timer is not a thing anyone wants.
- A live tool must have a name the agent can call.

### A live read tool

Mode **Call it live**, capability **Look up data**. It is never ingested into the knowledge base; it is registered as a function the agent invokes mid-answer.

You provide:

- **The URL**, optionally with `{braces}` for values the agent fills in — `https://api.yourcompany.com/orders/{order_id}`. Each substituted value fills exactly one path segment; it cannot escape into the rest of the path.
- **A tool name** — a short verb, like `check_stock`. This is what appears in transcripts.
- **When should the agent use it?** — plain words. This is the field that stops the agent calling too eagerly, and it deserves more thought than the URL.
- **Headers**, if the endpoint needs auth. Values go into encrypted storage immediately and are never shown again.

The response is capped at 2 MB, and what reaches the model is truncated at 24,000 characters. Return the fields the agent needs, not your full object graph — a lean response is both faster and easier for the agent to use correctly.

::: tip Write the description as a rule, not a label
`check_stock` with the description "Checks stock" will be called for "do you have anything nice?". The same tool with "Use only after the customer has named a specific product, to report whether that product is currently in stock" will not. Every eager tool call in production traces back to a description that described the endpoint instead of the situation.
:::

### An action tool

Mode **Call it live**, capability **Take an action**. Same fields, plus a method that may be `POST`, `PUT`, `PATCH`, `DELETE`, or `GET`.

When any action tool is bound to an agent, extra rules are injected into its behaviour automatically:

- Confirm the customer actually asked for this before doing it.
- Gather missing details one at a time, not as a form.
- Never claim it is done before the tool returns success.
- Never call speculatively.

**Every action call is audited** — success or failure — with the workspace, agent, conversation, channel, deployment, source, tool name, capability, outcome, and latency. **Arguments and response bodies are deliberately not recorded**, because they carry customer data and, occasionally, credentials. You get a complete record of what happened without a second copy of the payload. Read-capability calls are not audited; nothing changed.

### MCP servers

An MCP server is added once and its tools become available to any agent the knowledge base is attached to. Up to 20 tools per server, and you can restrict which of them are allowed by name.

Because MCP does not declare which of a server's tools mutate state, **you classify the server, not the tool** — look-up or action — and every tool on it inherits that classification. If any tool on the server changes data, the whole server is an action server. That is a conservative default and it is the correct one.

Errors are reported in plain words: `The MCP server rejected our credentials (401).`, `The MCP server answered with HTTP {code}.`, `Couldn't reach the MCP server. Check the URL and try again.`, and `The MCP server lists no tools.`

### Safety at call time

Every custom tool call, read or action, runs through the same guards:

- The destination must resolve to a public address. Internal addresses, loopback, and cloud metadata endpoints are refused.
- Redirects are not followed, and the connection is pinned to the address that was checked — so a host cannot pass a check and then point somewhere else.
- Responses are capped at 2 MB, and what reaches the model at 24,000 characters.
- Credentials are read from encrypted storage at call time and are never present in any record you can read.

## The tool policy

The agent's **Tools** tab holds a small policy that is **frozen into every published version**. That is the point: what an agent was allowed to do on a given day is recoverable, not inferred.

| Setting | Default | Effect |
|---|---|---|
| Create support tickets | **On** | Enables `create_support_ticket`. |
| Send WhatsApp messages | **Off** | Enables `send_whatsapp_message`, plus its sender, template allowlist, and recipient rule. |
| Let this agent take actions | **On** | Master switch for action-capability tools on attached knowledge bases. |
| Write actions | `Approved actions only` | Not configurable. The model cannot choose the workspace, the channel identity, or the contact id. |

**The actions master switch is absolute.** Turned off, action tools on an attached knowledge base are not declared to the model at all — it cannot try and be refused, because it never learns they exist. Read tools continue to work normally, so an agent with actions blocked can still look up an order but cannot cancel one. Turn it off when you want an agent that answers questions about a system it must not touch.

Tools are also only offered when their source is actually serving. A source that is still syncing or has failed contributes nothing, so a broken integration degrades the agent rather than breaking the conversation.

::: note What is deliberately not here
There is no per-deployment tool override — a version's tool policy applies to every channel it runs on. There is no approval workflow for individual tool calls, and there is no per-agent-version allowlist beyond the WhatsApp template list. If two channels need different powers, build two agents.
:::

## What happens automatically

Three behaviours are not settings and cannot be turned off, because turning them off would only produce bad data:

- **Contact resolution.** Before creating anything, the agent resolves the customer against your directory by email, phone, and WhatsApp ID. A returning customer enriches the record that already exists. See [Conversations and contacts](/concepts/conversations).
- **Idempotent ticketing.** Retries within the same conversation return the same ticket rather than duplicates.
- **Hand-off context.** When a ticket is opened, the issue summary, the channel, the requester, and the conversation reference go with it, so the person who picks it up is not starting from nothing.

## Reading what a tool did

Every conversation in the [inbox](/concepts/conversations) shows an operational trail alongside the messages, and tool use appears there by kind: `Knowledge base`, `Live API`, `MCP tool`, and `Action`. That trail is staff-facing only — it is not part of the transcript a customer sees, and it is not returned by [`GET /conversations/{id}/messages`](/api/conversations).

When an agent gives a wrong answer, that trail is the first thing to read. It tells you immediately whether the agent looked anything up, called your API, or answered from memory — three very different bugs with three very different fixes.

## Where to go next

::: cards

::: card Add the sources tools live on
[Knowledge bases](/build/knowledge) — endpoint and MCP sources, credentials, and refresh.
:::

::: card Get the WhatsApp side right
[The 24-hour window](/channels/whatsapp-window) and [Templates](/channels/whatsapp-templates) — what the send tool is allowed to do and when.
:::

::: card Watch the tools fire
[Testing and publishing](/build/testing) — the test tab shows what the agent looked up on every turn.
:::

::: card Handle the escalation end
[Escalate to a ticket](/recipes/support-escalation) — from the agent's tool call to your team's queue.
:::

:::


----------------------------------------------------------------------------
## Deployments
URL: https://docs.amomic.in/build/deployments
----------------------------------------------------------------------------

Publishing freezes an agent into a version. Deploying puts that version somewhere a customer can reach it. A **deployment** is the join between the two — this agent version, on that channel connection, with this channel-specific configuration — and it is the only object in the platform that decides what a real phone number, WhatsApp sender, or website widget actually does.

```mock
{"component": "DeploymentDiagram", "props": {"caption": "An agent version plus a channel connection plus channel configuration equals a deployment. Activating one supersedes whatever was serving that connection."}}
```

## The three ingredients

```text
agent version  +  channel connection  +  channel config   =   deployment
(what it says)    (where customers        (greeting, call
                   reach you)              language, domains)
```

**The agent version** is immutable. A deployment names one specific version, and that version cannot change underneath it. See [Agents and versions](/build/agents).

**The channel connection** is a specific touchpoint you own and have verified: a website, a WhatsApp Business number, a phone number. Connections are created and verified in the console, not through the API.

**The channel config** is the part that genuinely differs per channel and has nowhere else to live:

| Channel | Configuration that lives on the deployment |
|---|---|
| Web | The domains the widget may load on, the widget's appearance and greeting, lead capture |
| WhatsApp | Which sender number this agent answers from |
| Voice | The phone number, the call language, the language the call opens in, the opening line, whether calls are recorded |

One agent can have many deployments — a widget on your main site, a second on your help centre, a WhatsApp number, a phone number — all serving the same published version. Each is independent. Pausing the phone deployment does not touch the widget.

## The lifecycle

```text
draft  →  ready  →  active  →  superseded
                          └→  archived
```

| State | What it means |
|---|---|
| `draft` | Created and editable. Nothing is serving. This is the only state in which a deployment can be changed. |
| `ready` | It has passed validation and may be activated. **Already frozen** — see [the clone rule](#editing-a-live-deployment-clones-it). |
| `active` | It is the deployment its connection points at. Customers reach it. |
| `superseded` | A newer deployment took over the same connection. It is history, and it is the thing rollback restores. |
| `archived` | Removed from the working set. The connection and past conversations are untouched. |

Two further dimensions sit alongside the lifecycle. **Desired state** is `active` or `paused` — this is what pausing changes, and it moves independently of the lifecycle. **Health** is `unknown`, `healthy`, `degraded`, or `error`, reported by the channel rather than set by you. A freshly activated deployment starts at `unknown` and stays there until the channel says otherwise; that is not a problem.

## Validation, and what blocks activation

A deployment is validated before it can be activated, and again at the moment of activation. If anything is missing you get a specific list rather than a generic failure.

The checks are:

- **The agent version exists.** You cannot deploy an agent that has never been published.
- **The connection is enabled** and **verified**. A number that has not completed verification cannot serve customers.
- **The provider authorisation is healthy** — the underlying account connection has not expired or been revoked.
- **The channel configuration is complete** for that channel:
  - **Web** — allowed domains are set, and the widget install is verified.
  - **WhatsApp** — a sender number is chosen, and its webhook is verified.
  - **Voice** — a phone number is chosen, and an opening line is written.

In the deployment dialogs the same conditions appear as plain-language reasons on each option: `Connection disabled`, `Verification required`, `Connection has an error`, `Connection is degraded`. If the agent itself is not published yet, the dialog says so directly — `Publish the agent before deploying it to a channel.`

## What activation does

Activation is one transaction, and everything in it either happens together or not at all.

::: steps

::: step Re-validate

The checks above run again. Anything unresolved and activation is refused with the list of blockers. Nothing has moved.
:::

::: step Claim the connection

The connection is claimed with a compare-and-swap on its own version. If someone else changed that connection between the moment you loaded the page and the moment you pressed the button, activation fails with `Connection changed since it was loaded.` rather than overwriting their change.

This is what makes two people activating different agents on one phone number at the same time impossible. One wins; the other is told why.
:::

::: step Swap and supersede

The new deployment becomes `active`. The connection is repointed to it. **The deployment that was serving that connection becomes `superseded` and `paused`** in the same transaction.

Nothing on any other connection moves. Activating a WhatsApp deployment does not touch your phone number.
:::

::: step Project onto the channel

The live configuration is pushed to the channel runtime: the widget starts serving the new agent on the allowed domains, the phone number starts routing calls to it with its voice settings, the WhatsApp sender starts answering from it.
:::

:::

There is no partial state. A customer either reaches the old deployment or the new one, never a half-configured hybrid.

::: note Activation is idempotent
Activating a deployment that is already active on that connection returns success and changes nothing. A double-click, or two operators pressing the button at the same time, is safe.
:::

## Editing a live deployment clones it

This is the rule worth learning before anything else.

**An active deployment is immutable.** So is a `ready` one — validation freezes it, not activation. Attempting to edit either is refused: `Active or validated deployments are immutable; clone to make changes.`

The supported path is:

```text
clone  →  validate  →  activate
```

The clone copies the channel, the connection, the agent, and the agent version, takes your replacement configuration, and lands as a fresh `draft`. It must pass validation before it can be activated, and activating it transactionally supersedes the original.

The console does this for you. When you change a voice deployment's settings, it tells you plainly: *Saving rolls a new deployment onto this number so the change is auditable. Calls already in progress finish on the old settings.* You are not editing the running configuration; you are building its replacement and swapping it in.

### Why this matters

**A bad edit can never take down a working number.** Consider the alternative. If deployments were mutable, saving a voice deployment with an empty opening line would break the number immediately, and every caller for the next ten minutes would hear silence.

With cloning, the worst case is a clone that refuses to validate. The clone sits in `draft` telling you what is wrong. The original deployment carries on answering calls exactly as it did before, because nothing touched it. You fix the clone, or you abandon it.

**The second reason is auditability.** Every configuration a number has ever served is a real object with a timestamp, not a diff you have to reconstruct. "What was this number doing on 14 June?" has an answer you can open.

**The third is rollback.** Because the previous deployment still exists as `superseded` — complete with its configuration and its agent version — going back is re-activating a thing that demonstrably worked, not rebuilding it from memory.

::: warning A live agent update is two steps, not one
Editing the agent and publishing a new version does **not** change what any deployment serves. A deployment names one specific version. After publishing, you must deploy the new version to each connection you want it on. Until you do, the agents list will show `Changes to publish` cleared and your customers still hearing the old behaviour — which is exactly the confusion this design trades for safety.
:::

## Pausing

Pausing is the fast, reversible way to take an agent off a channel.

**What it does:** sets the deployment's desired state to `paused` and **un-points the channel from it**. The phone number stops routing calls to the agent, the WhatsApp sender stops answering, the widget stops serving. New traffic is not handled.

**What it does not do:**

- It does not change the lifecycle state. The deployment is still `active`; it is not desired to be serving. That is why resuming is instant and requires no re-validation.
- It does not delete or alter the configuration.
- It does not touch conversation history, transcripts, tickets, or contacts.
- It does not affect any other deployment, including other deployments of the same agent.

Resume puts it straight back. Pause is the right tool for "stop it now, decide later" — an agent giving bad answers at 11 p.m. should be paused, not edited.

You must pause before archiving. Archiving a serving deployment is refused with `Pause this deployment before removing it.` — the platform will not let a tidying action drop a customer's call.

## Rolling back

The previous deployment on a connection is still there, marked `Replaced`. Rolling back to it clones it, validates, and activates in one step, superseding the deployment that is currently live and restoring both its configuration *and* its agent version.

Rollback is a mitigation, not a fix. Your draft still contains whatever caused the problem. Correct it, test it, publish a new version, and deploy forward.

## Run-state badges

The **Deployments** tab shows one of five strings per row. These are the exact strings.

| Badge | Meaning | What to do |
|---|---|---|
| `Live` | Active and serving. Customers reach it. | Nothing. |
| `Disabled` | Paused. Configuration intact, not serving. | Resume it when you are ready. |
| `Error` | The channel reports it as unhealthy. | Check the connection — verification, provider authorisation, credentials. |
| `Replaced` | Superseded by a newer deployment on the same connection. | Nothing. It is history, and it is what rollback restores. |
| `Not live` | Not currently serving — typically a draft, or one that never activated. | Validate and activate it, or delete it. |

::: tip `Replaced` on every row but one is correct
A connection that has been reconfigured five times has five `Replaced` deployments and one `Live`. That is the audit trail working, not a leak. Superseded and archived deployments do not count toward your plan's deployment limit.
:::

## Removing a deployment

Removing takes the deployment out of the working set. The console is explicit about what survives: *This removes the {channel} deployment. The channel connection itself stays and past conversation history is kept — you can deploy an agent here again later.*

So removing a WhatsApp deployment does not disconnect your WhatsApp number, and removing a voice deployment does not release your phone number. The connection is yours until you release it deliberately from the channel page.

## Deployment limits

Your plan caps how many deployments can exist in the working set — `draft`, `ready`, and `active` all count. Superseded and archived history is free, so a well-used connection does not consume your allowance.

When you hit the cap: `Your plan includes {limit} deployment(s). Upgrade to add more.` See [Limits and plans](/operate/limits).

## Where to go next

::: cards

::: card Publish something to deploy
[Agents and versions](/build/agents) — what publishing freezes and why versions are immutable.
:::

::: card Check it before you activate
[Testing and publishing](/build/testing) — readiness checks and the publish-then-deploy sequence.
:::

::: card Put it on a phone number
[How voice works](/channels/voice) and [Numbers and KYC](/channels/phone-numbers) — the voice connection and its per-deployment settings.
:::

::: card Put it on WhatsApp
[Set up WhatsApp](/channels/whatsapp) — connecting a number and verifying it before you deploy.
:::

:::


----------------------------------------------------------------------------
## Testing & publishing
URL: https://docs.amomic.in/build/testing
----------------------------------------------------------------------------

Every agent is good at the questions you thought of while building it. Testing is the half hour in which you find out what happens to the other ones — and it is the cheapest half hour in this entire product, because every failure you find here is a real customer conversation you do not have.

## The test tab

Open the agent and choose **Test**. It is a real conversation with the current draft: the agent remembers the thread, so you can ask a question and then follow up on the answer, which is where most agents actually break.

Three pieces of the interface do the work.

**The source expander.** Every answer shows how long it took and either `{n} source(s)` — expandable to see exactly which passages it used — or the badge **`No knowledge used`**. That badge is the most informative thing on the screen. An answer full of specific facts about your business with `No knowledge used` next to it is an agent inventing your policy, and it will do the same thing to a customer tonight.

**The verdicts.** Mark each answer `Pass` or `Needs work`. This is not bookkeeping — a passing run against the current configuration is what the readiness check looks for. Marking answers is how you tell the platform you actually looked.

**New thread.** Because the agent remembers the conversation, a fresh question after five turns is not the same test as a fresh question at the start. Start a new thread when you change topic.

Messages are capped at 1,000 characters, which is longer than any real customer message.

## What to actually test

Do not test the questions you know are covered. You wrote the knowledge base; of course it answers those. Test the ones your own team gets wrong.

::: steps

::: step The five questions your support inbox is full of

Open your inbox — the real one, with humans in it — and take the five most repeated questions from last month. Ask those, in the customer's own words, typos included. If the agent cannot handle your top five, nothing else matters.
:::

::: step The exceptions

"What if I bought it on sale?" "What if I'm in Guwahati?" "What if the box was opened?" Published policies describe the rule; customers ask about the edges. An agent that answers the rule confidently when the customer is describing an exception is worse than one that says it does not know.
:::

::: step The follow-up

Ask a question, then ask a second one that only makes sense given the first answer. "How long do refunds take?" then "And if I paid by UPI?" This is where thin knowledge shows: the first answer is fine, the second is invented.
:::

::: step The out-of-scope question

Ask it something you sell nothing of. `Do you sell refrigerators?` A well-scoped agent declines cleanly. A vague one improvises. If it improvises, the fix is in the [purpose](/build/agents), not the knowledge base.
:::

::: step The hand-off

Say `I want to talk to a human.` The agent should reach for a ticket, gather what it needs without interrogating you, and read back a reference. If it merely apologises, check that ticketing is enabled on the [Tools](/build/tools) tab.
:::

::: step The angry customer

Type the message an actually annoyed person sends — short, capitalised, no punctuation. Tone handling is the difference between a complaint that resolves and a complaint that goes on social media.
:::

:::

The console offers four starters if you want somewhere to begin: `How much does it cost?`, `Do you sell refrigerators?`, `I want to talk to a human.`, and `What are your support hours and how do I reach you?` They are a warm-up, not a test plan.

## The two failure modes

Almost everything you find will be one of these two, and they need opposite fixes. Telling them apart is the whole skill.

### 1. It answers from nowhere

The agent states a policy, a price, a timing, or a rule that is not in any of your sources. Usually fluent, usually plausible, occasionally exactly right by luck.

**How to spot it:** the `No knowledge used` badge, or a source expander whose passages have nothing to do with the claim.

**What it means:** your knowledge base is thin here and the model is filling the gap.

**The fix is content.** Add the source. If the fact exists on your website but was not crawled, check whether that page is inside the section you pointed the crawler at. If it exists nowhere — the exception your team knows by heart — write a `text` source for it. See [Knowledge bases](/build/knowledge).

Do not fix this by adding a rule to the instructions. "Never say the refund window is 30 days" patches one sentence and leaves the underlying gap intact.

### 2. It refuses something it should know

The agent says it does not know, and you can see the answer on your own website.

**How to spot it:** open the knowledge base's **Retrieval tester** and ask the same question. It shows exactly which passages would have been retrieved, with the model taken out of the picture.

- **The tester finds nothing relevant** — the passage does not exist. Almost always one of: the answer is inside an image, the answer is inside a table that flattened into meaningless text, the page needed a click to load its content, or the page was outside the crawl.
- **The tester finds the right passage but the agent still refused** — retrieval worked and the model did not use it. That is a persona problem: check the purpose for a boundary that excludes this topic, and consider whether `grounded` is too tight for the way that passage is written.

Tables and images are the usual culprit, and worth stating plainly: a shipping matrix or a price card that a human reads at a glance frequently becomes unusable once flattened into text. Rewrite the ten rows customers actually ask about as sentences in a `text` source. It takes ten minutes and fixes more failures than anything else you can do.

## Readiness checks

The agent's **Overview** tab shows a readiness verdict — `Ready to publish` or `Needs attention` — computed from four areas:

| Check | What it looks at |
|---|---|
| **Agent** | The persona is complete enough to publish — it has a name and a purpose. |
| **Knowledge** | If the knowledge requirement is `required`, at least one attached knowledge base is actually serving content. |
| **Test** | A passing test run exists against the current configuration. |
| **Tools** | The tool policy is coherent — for example, WhatsApp sending enabled with a usable sender. |

Each issue labels itself `Required before publishing` or `Recommended`, with a link that takes you to the tab that fixes it. When everything passes you get one line: `Every current check passes.`

::: note The test check is fingerprinted to the configuration
A passing run counts against the configuration it was run on. Change the persona, attach a knowledge base, or alter the tool policy and the test check goes stale — because a passing run on a different agent is not evidence about this one. Re-test after material changes. This is mildly annoying by design.
:::

Recommended issues do not block publishing. They are there because someone will otherwise publish an agent with knowledge attached but no tools enabled and wonder why it never escalates.

## Publishing, then deploying

These are two separate actions and the order matters.

::: steps

::: step Publish the version

**Overview → Publish**, or the **Versions** tab. The current persona, knowledge bindings, and tool policy are frozen together into an immutable version.

Write a change summary. `Added the 2026 returns policy and stopped it quoting delivery estimates` costs five seconds and is the only human-readable record of why this version exists.
:::

::: step Deploy it to each channel

Publishing does not move anything. Until you deploy, the agent shows `Published, not deployed yet` and every live channel keeps serving the version it was already serving.

From the agent's **Deployments** tab, deploy the new version to each connection you want it on. Each activation supersedes what was there in a single transaction. See [Deployments](/build/deployments).
:::

::: step Try it on the real channel

The test tab tests the agent. It does not test the channel. Send yourself a WhatsApp message, load the page with the widget on it, or ring your own number.

Channel-level problems are invisible in the studio: a domain missing from the widget's allowed list, a WhatsApp template that was never approved, an opening line that reads fine and sounds strange out loud. Five minutes on the real channel catches all three.
:::

:::

::: warning Roll out one channel at a time
If you have four deployments, activate the new version on one, watch it for a few conversations, then do the rest. All four at once means a problem you did not catch in testing reaches every customer simultaneously — and while [rollback](/build/deployments) is fast, not needing it is faster.
:::

## When something is wrong in production

In order, quickest first:

1. **Pause the deployment.** It stops serving immediately and nothing is lost. This is always the right first move at 2 a.m.
2. **Roll back.** The previous deployment is still there as `Replaced`, with its configuration and its agent version intact. Re-activating it restores exactly what worked.
3. **Then diagnose.** Read the conversation in the [inbox](/concepts/conversations) — the operational trail shows whether the agent looked anything up, called a tool, or answered from memory. Three different bugs, three different fixes.
4. **Fix the draft, test, publish, deploy.** Your draft still contains whatever caused it. Rollback bought time; it did not change anything you wrote.

## Where to go next

::: cards

::: card Fix a content problem
[Knowledge bases](/build/knowledge) — the retrieval tester, source types, and getting good answers.
:::

::: card Fix a behaviour problem
[Agents and versions](/build/agents) — writing a purpose, instructions, and the grounding policy.
:::

::: card Ship it safely
[Deployments](/build/deployments) — activation, pausing, and rollback.
:::

::: card Check the whole picture
[Going live](/operate/going-live) — everything worth confirming before real traffic arrives.
:::

:::


============================================================================
# SECTION: Channels
============================================================================



----------------------------------------------------------------------------
## Set up WhatsApp
URL: https://docs.amomic.in/channels/whatsapp
----------------------------------------------------------------------------

Connecting WhatsApp puts one of your agents on a WhatsApp Business number you own. Customers message the number the way they message anyone else; the agent reads the message, answers from its knowledge base, and every exchange lands in your inbox alongside web and voice conversations.

Nothing about the agent changes. The same published version, the same knowledge, the same tools — rendered in WhatsApp's own formatting instead of a web bubble.

## What you get once it is connected

- **Inbound conversations answered automatically.** Every message to the connected number reaches the agent deployed to it.
- **Outbound sends from your backend.** [`POST /messages`](/api/messages) sends free-form text or an approved template from any connected sender.
- **The agent can start a WhatsApp conversation itself.** An agent talking to someone on your website can follow up on WhatsApp, if it has a phone number for them — see [Capture leads](/channels/web-chat-leads).
- **Opt-out handling across the workspace.** A customer who sends `STOP` to one of your numbers is suppressed on all of them.

## Vocabulary: WABA, sender, agent

Three things get confused constantly, and the difference matters when something breaks.

| Term | What it is |
|---|---|
| **WhatsApp Business Account (WABA)** | Meta's container for your business messaging. It holds your message templates, your quality rating, and one or more phone numbers. You own it; Amomic-AI is authorized to act on it. |
| **Sender** | One phone number inside that WABA, connected to your workspace. Each sender carries its own credential, its own assigned agent, and its own reply settings. |
| **Agent** | The published [agent version](/build/agents) that answers on that sender. Bound by activating a [deployment](/build/deployments), not by editing the sender directly. |

A workspace can hold several senders. A sender belongs to exactly one workspace — if the number is already connected somewhere else you get *"This WhatsApp number is already connected to another workspace."* rather than a silent takeover.

## Before you begin

You need all four. Missing any one of them stops the flow partway through, usually inside Meta's window where the error is least helpful.

- Admin access to your Meta Business portfolio
- A business phone number you control
- Access to receive Meta's SMS or voice verification on that number
- An Amomic-AI agent, published, ready to handle conversations

::: warning Publish the agent first
The connection flow asks which agent will answer before it opens Meta. If you have no agent yet the console says *"Create an agent before connecting WhatsApp."* and stops. Build and publish one first — [Quickstart](/start/quickstart) gets you there in a few minutes.
:::

## Connect a number

Setup runs through Meta's Embedded Signup. You authorize inside Meta's own window; the credential comes back to us server-side. You are never asked to paste a token into your browser on the recommended path.

::: steps

::: step Choose the agent that will answer

Open **Channels → WhatsApp**. On the first-sender card, pick the agent from **Choose the agent that will answer**. This is changeable later, per sender, from the **Automation** tab.

:::

::: step Authorize your business with Meta

Choose **Continue with Meta**. Meta opens in a secure window where you sign in, select an existing WABA and phone number, or create them on the spot.

The window is Meta's, not ours. Two things go wrong there often enough to name:

- **Browser privacy settings block it.** Strict tracking protection stops Meta's SDK from loading and you get *"Meta login could not be loaded. Check browser privacy settings."* Try a normal window in a mainstream browser.
- **You close it early.** Cancelling before Meta finishes returns *"WhatsApp setup was cancelled before completion."* Nothing is saved; start again.

When it completes, we verify with Meta that the WABA and number you picked are actually the ones you were authorized for, check the number is not already connected elsewhere, subscribe the number to inbound webhooks, and store the credential in a secrets vault. The credential is never returned to the browser.

:::

::: step Verify a real conversation

The **Overview** tab has a **Verify a conversation** card. It exercises the real inbound session and the real outbound reply path, which is the only proof that matters.

1. From your phone, send any message to the connected number.
2. Enter that same phone number in the field.
3. Choose **Send verification reply**.

If step 1 is skipped you get *"Couldn't send the reply. Message the business number first to open the 24-hour window."* That is not a bug — it is [the 24-hour window](/channels/whatsapp-window) doing its job, and it is worth understanding before you build anything on top of this channel.

:::

:::

## Sender health

Each sender shows a health state. These are the exact labels, and each one names its own fix.

| State | What it means |
|---|---|
| `Ready` | Messages can be received and answered by the assigned agent. |
| `Connected` | Verified live with Meta — this number is receiving and answering messages. |
| `Finishing setup` | The connection is saved, but Meta setup is not fully active yet. Usually the number's own verification with Meta is still pending. |
| `Agent required` | Choose which agent should answer messages for this number. Inbound messages arrive and go nowhere until you do. |
| `Reconnect required` | Meta authorization is missing or no longer valid. Use **Reconnect Meta** on the Connection tab. |
| `Paused` | This sender is disabled and will not handle messages. |

The **Readiness** card breaks the same judgement into its four parts — phone number registered with Meta, authorization available, webhook subscription active, agent assigned — so you can see which one is failing rather than guessing.

There is also a live check that calls Meta while you watch: **Verify with Meta** on the Connection tab. It resolves the stored credential with no fallback and makes one real request, so a `Reconnect required` result here is definitive.

::: note Quality rating
Meta scores each number's quality as `Green`, `Yellow` or `Red` based on how recipients react to your messages. A red rating surfaces a warning in the console: pause non-essential sends, review recent blocks and reports, and confirm every recipient opted in. Meta may reduce your messaging limits if quality stays low.
:::

## Multiple senders and the default

Add more numbers with **Add sender**. Each one authorizes separately through Meta and gets its own isolated credential — a problem with one sender's token never touches another.

Per sender, independently:

- The agent that answers
- Whether incoming messages are marked as read
- Whether a typing indicator shows while the agent composes
- The business profile customers see

One sender in the workspace is the **workspace default**, marked with a `Default` pill and set from **Make workspace default** on the Connection tab. The default matters in exactly one place: when [`POST /messages`](/api/messages) is called without a `sender_id`, the message goes out from the default sender.

```json title="Choosing a sender explicitly"
{
  "to": "+919876543210",
  "sender_id": "was_9f2c41ab77de1063c8a4b512",
  "text": "Your technician is on the way."
}
```

Call [`GET /channels`](/api/discovery) from your backend to list the senders your key can send from, with their ids — there is no other way to get a `sender_id` into code without copying it out of the console by hand.

::: warning Opt-outs are workspace-wide, senders are not
A customer opt-out blocks sends from every number in the workspace. Everything else — agent, profile, templates, credential — is per sender. Do not assume a second number gives you a second chance with someone who unsubscribed.
:::

## The display name is Meta's decision

The name customers see above your number is set in WhatsApp Manager and reviewed by Meta. It is read-only in the Amomic-AI console, with a padlock, because we genuinely cannot change it on your behalf — Meta reviews every display-name change.

The console reflects what Meta reports:

- *"A change to this name is awaiting Meta's review."*
- *"Meta declined this name. Submit a different one in WhatsApp Manager."*
- *"No display name yet. Set one in WhatsApp Manager — customers see it above your number."*

Everything else on the business profile *is* editable here, and changes go straight to Meta and are live immediately: the About line (up to 139 characters), the description (up to 512), contact email, category, up to two websites, address, and the profile photo (square JPEG or PNG, at least 192×192, under 5 MB).

## Putting an agent on a sender

Two routes reach the same place.

**From the channel.** Open the sender's **Automation** tab, pick the agent under **Assigned agent**, and save. The agent's instructions and knowledge base power replies from that number.

**From the agent.** Deploy the agent to the WhatsApp connection. Activating the deployment writes the binding onto the sender.

Either way, the binding is owned by the deployment. That has two consequences worth knowing:

- **Pausing a deployment unassigns the sender.** Inbound messages then arrive and are dropped, because no agent is bound. The sender shows `Agent required`.
- **You cannot edit a live deployment.** Change something and you clone it, validate the clone, and activate — which transactionally replaces the old one. See [Deployments](/build/deployments).

## How an inbound message reaches your agent

```
Customer sends a message
  → Meta delivers a signed webhook to Amomic-AI
  → the number it was sent to identifies the sender
  → the sender identifies the workspace and the bound agent
  → the agent answers, grounded in its knowledge base
  → the reply goes back out on the same number
```

Three details in that chain surprise people:

- **Routing is by the receiving number, not by the customer.** The same customer messaging two of your numbers gets two independent conversations with two independently assigned agents.
- **An unrecognised number is dropped.** We acknowledge the delivery to Meta and log it, rather than leaving Meta retrying into a routing void.
- **A sender with no agent is silent.** Not an error to the customer, not a fallback message — nothing. Check the `Agent required` state if messages seem to vanish.

Every inbound message also restarts [the 24-hour window](/channels/whatsapp-window) for that customer on that sender. Read that page before you design any notification flow.

### What the agent can read

| Customer sends | What happens |
|---|---|
| Text | Answered normally. |
| Image (JPEG, PNG, WEBP, GIF) | Read by the agent. A caption is treated as the question; an image with no caption is answered on its own. |
| Button tap or list selection | Treated as the customer's reply. |
| Location | Passed through as the shared coordinates. |
| Voice note, video, document, sticker | Not processed. The agent replies: *"I can read text and images right now — voice notes and other files aren't supported yet. Please type your question or send a photo and I'll help!"* |

### What the agent can send

Text and interactive replies. The agent writes in WhatsApp's own formatting — `*bold*`, `_italic_`, `~strike~` — never markdown, and long replies split at sentence and paragraph boundaries rather than being truncated.

It can also produce native WhatsApp UI:

- **Up to 3 options** render as tap buttons, labels trimmed to 20 characters.
- **4 to 10 options** render as a tap-to-open list, row titles trimmed to 24 characters.
- **A single link** renders as a call-to-action button.

Outbound images, documents, audio and video are not supported on this channel. If a customer needs a file, send them a link.

## Opt-outs

WhatsApp opt-out is handled for you, before the message reaches the agent. A customer whose message matches an opt-out keyword exactly — after trimming whitespace and ignoring case — is suppressed immediately.

**Opt-out keywords:** `stop`, `unsubscribe`, `opt out`, `optout`, `cancel`, `band karo`, `बंद करो`, `रोको`, `बंद`

They get one reply and nothing else:

> You won't receive any more messages from us. Send START to resubscribe.

**Opt-in keywords:** `start`, `subscribe`, `unstop`, `shuru karo`, `शुरू करो`

> Welcome back! How can I help you today?

::: danger Suppression is permanent until they send START
There is no expiry, no cool-off, no per-campaign scope, and no console override. A suppressed recipient stays suppressed across every sender in the workspace until they message one of your numbers with an opt-in keyword themselves.

Any send to a suppressed recipient — free text or template, from the API or from an agent — fails with `403 permission_denied`, message *"Recipient has opted out."*, and `details.reason` of `"suppressed"`. Handle that code in your integration and stop retrying; a retry cannot succeed.
:::

Match is exact, not fuzzy. "please stop messaging me" does not trigger suppression — it goes to the agent as an ordinary message. If you want stricter handling than Meta's keyword convention, keep your own suppression list and check it before you call the API.

## Sending from your backend

Once a sender is connected and healthy, [`POST /messages`](/api/messages) is the whole surface:

```bash
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-shipped" \
  -d '{
    "to": "+919876543210",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "variables": ["Asha", "AM-4821"]
    }
  }'
```

Two constraints decide the shape of every integration built on this channel:

- **Free-form `text` only works inside the 24-hour window.** Outside it you get `409` with `session_window_closed`. See [The 24-hour window](/channels/whatsapp-window).
- **Templates must already be approved by Meta.** The API sends them; it does not create them. See [Templates](/channels/whatsapp-templates).

## Troubleshooting

::: details Messages arrive but the agent never replies
Check the sender's health. `Agent required` means nothing is bound — assign an agent on the Automation tab, or resume the paused deployment that used to hold the binding. Inbound is working fine in this state, which is exactly why it looks like the agent is ignoring people.
:::

::: details Sends fail with 412 channel_not_connected
No WhatsApp sender is connected to the workspace at all, or the one you named in `sender_id` does not exist. Call [`GET /channels`](/api/discovery) to see what your key can actually send from.
:::

::: details The sender flipped to Reconnect required
The stored credential no longer works — Meta revoked it, the authorizing admin lost access to the business portfolio, or the number was moved. Use **Reconnect Meta** on the Connection tab and re-authorize. Inbound stops until you do.
:::

::: details A number connected fine but shows Finishing setup
Meta has not finished verifying the number itself. Complete verification in WhatsApp Manager; the state resolves on the next live check.
:::

## Next

::: cards

::: card The 24-hour window
[The single WhatsApp rule](/channels/whatsapp-window) that decides whether your message sends or returns a 409.
:::

::: card Templates
[Write, submit and send](/channels/whatsapp-templates) the approved messages that reach customers outside the window.
:::

::: card Send from code
[POST /messages](/api/messages) — the full request contract, every error, and the idempotency rules.
:::

::: card Receive replies
[Webhooks](/webhooks/overview) push `message.received` and `message.status` to your backend instead of you polling.
:::

:::


----------------------------------------------------------------------------
## The 24-hour window
URL: https://docs.amomic.in/channels/whatsapp-window
----------------------------------------------------------------------------

Everything that goes wrong on WhatsApp goes wrong here. If you read one page about this channel, read this one.

WhatsApp does not let a business message whoever it wants whenever it wants. You may write freely to a customer only in the 24 hours after *they* last wrote to you. Outside that window you may send only messages Meta has already reviewed and approved — templates. There is no third option.

Amomic-AI enforces this centrally, on the send path, so no caller can route around it: not the API, not an agent, not the console.

## The window in one picture

```mock
{"component": "WindowDiagram", "props": {"caption": "The window opens on the customer's message and closes 24 hours later. Your replies do not extend it — only theirs do."}}
```

## What opens it

**A message from the customer. Only that.**

Every inbound message from that customer to that sender restarts the 24-hour clock from the moment it arrives. A customer who writes to you every day keeps the window permanently open. A customer who wrote once last Tuesday is long outside it.

Things that do **not** open or extend the window:

- Your agent replying. Outbound never extends the clock.
- Sending an approved template. It reaches them, but it does not open a free-form window on its own.
- A delivery or read receipt.
- The customer opening the chat, or the message being marked read.

The window is scoped **per customer, per sender**. If a customer messages one of your numbers, you have an open window on that number and no window on the others.

## What you can send, when

| Window | Free-form `text` | Approved `template` |
|---|---|---|
| **Open** — they messaged within 24 hours | Yes | Yes |
| **Closed** — they have not, or never did | No — `409` | Yes |

Templates deliberately bypass the window check. That is the entire reason they exist: they are the sanctioned way to start a conversation with someone who is not currently talking to you.

::: warning What templates do not bypass
Opt-outs. A suppressed recipient rejects templates exactly as hard as free text — `403 permission_denied` with `details.reason` of `"suppressed"`. See [opt-outs](/channels/whatsapp#opt-outs).
:::

## The error, exactly

Send free-form text to a closed window and you get this, every time:

```responses
[
  {"status": 409, "code": "conflict", "reason": "session_window_closed", "description": "The 24-hour session window is closed; only approved template messages can be sent."}
]
```

```json title="409 Conflict"
{
  "error": {
    "code": "conflict",
    "message": "The 24-hour session window is closed; only approved template messages can be sent.",
    "details": { "reason": "session_window_closed" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Branch on `error.details.reason`, not on the message string. `conflict` covers more than one situation across the API; `session_window_closed` is unambiguous.

```javascript title="Handling it properly"
const response = await fetch("https://services.amomic.in/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-shipped`,
  },
  body: JSON.stringify({ to: order.customerPhone, text: message }),
});

if (response.status === 409) {
  const { error } = await response.json();
  if (error.details?.reason === "session_window_closed") {
    // Not retryable as free text. Fall back to the approved template.
    return sendTemplate(order);
  }
}
```

::: danger A 409 here is not transient
Retrying the same free-form send will fail identically until the customer writes to you again — which may be never. Backoff does not help. Queueing does not help. The only correct handling is to send a template instead, or to not send at all.
:::

## Nothing is sent automatically when the window closes

There is no hold-and-release. There is no automatic re-engagement template. There is no queue that drains when the customer next writes in.

When the window closes, the closed window is simply the state of the world. If you have something to say, you send a template. If you had a message pending in your own system, it is your system's job to notice the 409 and decide what happens next.

We are explicit about this because the alternative — quietly substituting a template you did not choose, on a Meta conversation category you did not budget for, to a recipient who may not want it — is worse than an error.

## The consequence for your design

Work through the timing of a real notification and the conclusion is unavoidable.

A customer orders at 11 a.m. and asks a question in chat; the window opens. The order ships at 9 p.m. the next day — 34 hours later. The window closed 10 hours ago. Your "your order has shipped" message is a template, or it does not go out.

Now generalise. **Anything triggered by your system rather than by the customer is almost always outside the window**, because your systems run on your schedule and customers write on theirs:

| Flow | Triggered by | Realistically |
|---|---|---|
| Answering a support question | The customer, just now | Inside the window |
| Agent follow-up during a live chat | The customer, minutes ago | Inside the window |
| Order shipped / out for delivery | Your warehouse | Outside |
| Appointment reminder for tomorrow | A scheduler | Outside |
| Payment receipt, renewal notice | Your billing job | Outside |
| Feedback request a day later | A cron | Outside, by definition |
| Re-engaging a lapsed customer | A report | Far outside |

So: **build every notification flow on templates from the start.** Not as a fallback bolted on after the first 409 in production — as the primary path.

The pattern that survives contact with reality:

::: steps

::: step Get the template approved before you write the code

Template review takes minutes to a day. Doing it after your integration is built means your launch waits on Meta. See [Templates](/channels/whatsapp-templates).
:::

::: step Send the template unconditionally for anything system-triggered

Do not probe the window first. There is no endpoint that reports window state, and a template send works whether the window is open or closed. Checking would only add a failure mode.
:::

::: step Use free-form text only inside a conversation you are already in

An agent replying to a live conversation is inside the window by construction — the customer's message is what woke it up. That is where free text belongs.
:::

::: step Treat 409 / `session_window_closed` as "switch to a template", not as "retry later"

One code path, one decision, no queue.
:::

:::

## What the agent does when it hits a closed window

An agent can be given the ability to send a WhatsApp message — following up a web chat, for example. When it tries and the window is closed, it does not silently invent a substitute or apologise vaguely. The tool returns a structured result the model can act on, using these exact values:

`sent` · `template_required` · `needs_setup` · `opted_out` · `template_not_allowed` · `template_not_found` · `needs_information` · `not_configured` · `failed`

`template_required` means the window is closed and the agent should reach for one of the templates it is permitted to send. Which templates those are is set on the agent's tool policy — the model cannot name a template you have not allowed. See [Tools & actions](/build/tools).

## Verifying the window is doing what you think

The console's **Verify a conversation** card on the WhatsApp Overview tab is a window test in disguise:

1. Message your business number from your phone. The window opens.
2. Enter that number in the card and choose **Send verification reply**.
3. A reply arrives on your phone.

Skip step 1 and the reply fails with *"Couldn't send the reply. Message the business number first to open the 24-hour window."* That is the window rejecting a free-form send, end to end, in ten seconds — a cheaper way to see the behaviour than discovering it in production.

## Common misreadings

::: details "My template send opened the window, so now I can send text"
It did not. A template reaches the customer; only a message *from* the customer opens the window. If they reply to your template, that reply opens it.
:::

::: details "The customer read my message, so the window is open"
Read receipts are not inbound messages. Nothing about the customer's behaviour inside WhatsApp opens the window except sending you something.
:::

::: details "It worked in testing and fails in production"
In testing you were messaging the number yourself minutes earlier, so every window was open. Production traffic is triggered hours later by your own systems. This is the single most common way this rule is discovered.
:::

::: details "We have a second number, so we can message from that one"
The window is per sender, so the second number's window is also closed — you have gained nothing except a second closed window. Opt-outs, meanwhile, *are* shared across senders, so the second number does not help there either.
:::

::: details "Can I query whether the window is open?"
No. There is no endpoint that reports window state. Send the template.
:::

## Next

::: cards

::: card Templates
[How to write and submit one](/channels/whatsapp-templates), what Meta approves, and how to fill its variables at send time.
:::

::: card POST /messages
[The send contract](/api/messages) — text, templates, sender selection, and every error code.
:::

::: card Order-shipped update
[A complete flow](/recipes/order-updates) built the right way round, template first.
:::

::: card Errors
[The full error model](/api/errors), including how `code` and `details.reason` divide up.
:::

:::


----------------------------------------------------------------------------
## Templates
URL: https://docs.amomic.in/channels/whatsapp-templates
----------------------------------------------------------------------------

A template is a message you write in advance, Meta reviews, and you then send with the changeable parts filled in. It is the only way to reach a customer outside [the 24-hour window](/channels/whatsapp-window) — which, for anything your own systems trigger, is nearly always.

Meta requires approval because templates are how a business can message someone who is not currently talking to it. Review is the control on that. It is not a formality: a template that reads like unsolicited promotion in a category that claims otherwise gets rejected, and templates that provoke blocks pull down the number's quality rating.

```mock
{"component": "TemplatesScreen", "props": {"caption": "Templates in the console, with the raw status each one carries at Meta."}}
```

## Anatomy

A template has one required part and three optional ones.

| Component | Required | Limit | Notes |
|---|---|---|---|
| **Header** | No | 60 characters | A short bold line above the message. Text only. |
| **Body** | **Yes** | 1024 characters | The message. Where variables normally live. |
| **Footer** | No | 60 characters | Small print. **No variables allowed here.** |
| **Buttons** | No | 10 | Quick replies, links, or a call button. |

Plus two identifiers that are not shown to customers: a **name** (lowercase letters, numbers and underscores, up to 128 characters) and a **language** code.

```mock
{"component": "WhatsAppMock", "props": {"header": "Your order is on the way", "body": "Hi Asha, your order AM-4821 has shipped and arrives by 6 PM today. Track it any time with the button below.", "footer": "Reply STOP to opt out", "buttons": ["Track order", "Talk to support"], "time": "18:04", "caption": "The template order_shipped with {{1}} filled in as \"Asha\" and {{2}} as \"AM-4821\"."}}
```

## Categories

There are exactly three. Pick the one that describes what the message actually does — misclassifying is a common rejection reason, and marketing costs more than utility.

| Value | Label | Use it for |
|---|---|---|
| `UTILITY` | Utility | Follows up on something the customer did — an order, a booking, an account change. |
| `MARKETING` | Marketing | Promotions and announcements. Costs more and needs clearer opt-in. |
| `AUTHENTICATION` | Authentication | One-time passcodes only. |

::: warning Create AUTHENTICATION templates in WhatsApp Manager
The authentication category has rules of its own at Meta — fixed body structure, code-expiry handling, autofill behaviour — and the console composer does not implement them. If you need one-time-passcode templates, create them in WhatsApp Manager, then press **Sync** to pull them into the console so they can be sent. Everything on this page about sending applies to them normally; only authoring is elsewhere.
:::

## Status

Templates carry Meta's verdict as a raw lowercase string. Three values matter:

| Status | Meaning |
|---|---|
| `pending` | With Meta for review — usually minutes, sometimes a day. The status updates itself; you do not need to poll. |
| `approved` | Ready to send. |
| `rejected` | Meta won't deliver this. The rejection reason is shown in full on the template's detail dialog. |

**Only `approved` templates can be sent.** Naming a `pending` or `rejected` one returns `404 not_found` with `details.reason` of `"template_not_found"` — the name exists in your workspace, but not as something sendable.

::: note Statuses you did not expect
Meta occasionally reports states beyond these three, and they pass through lowercased rather than being forced into a bucket we would have to guess at. Treat anything that is not the literal string `approved` as not sendable.
:::

## Variables

Variables are numbered placeholders: `{{1}}`, `{{2}}`, `{{3}}`. You write them into the body when you author the template, and supply the values at send time.

```text title="Body"
Hi {{1}}, your order {{2}} has shipped and arrives by {{3}}.
```

Meta reviews the template with sample values filled in, so the composer asks for one sample per placeholder. Use realistic values — `Priya` and `AM-10428`, not `xxx` and `123`. A reviewer reading `Hi xxx, your order 123 has shipped` is being shown something that looks like spam.

Rules the composer enforces before it will submit, because Meta rejects on all of them:

- **A body cannot start or end on a placeholder.** *"The message can't start or end on a `{{n}}` — put words around it."*
- **Two placeholders cannot be adjacent.** *"Two `{{n}}` next to each other reads as blank to a reviewer — separate them with words."*
- **Numbering must be contiguous from 1.** *"Numbers must run 1, 2, 3… — `{{5}}` appears without `{{2}}`."*
- **Every placeholder needs a sample.**
- **Footers cannot contain placeholders.**

### Supplying values at send time

Values are matched to placeholders **by position**. Two shapes are accepted:

```json title="Positional array"
{ "variables": ["Asha", "AM-4821", "6 PM today"] }
```

```json title="Numbered object"
{ "variables": { "1": "Asha", "2": "AM-4821", "3": "6 PM today" } }
```

They mean the same thing. The array is less error-prone in code you will read again in six months; the object survives refactoring better when a template gains a placeholder.

Header and button variables are supplied separately, with `header_variables` and `button_variables`, using the same two shapes.

Passing the wrong number of values returns `400 invalid_argument` with `details.reason` of `"template_variables"`. Values are stripped of newlines and tabs and truncated at 1024 characters before they reach Meta — WhatsApp does not allow a placeholder to inject line breaks into a reviewed layout.

## Buttons

Three button types exist. Nothing else.

| Value | Console label | What it does |
|---|---|---|
| `QUICK_REPLY` | Quick reply | Sends its own label back to you as a message from the customer, which also opens the 24-hour window. |
| `URL` | Visit website | Opens a link. The link may end in a single `{{1}}` so you can point at a specific order or booking. |
| `PHONE_NUMBER` | Call phone number | Dials a number you specify, in full international form. |

Limits, all enforced before submission:

- **10 buttons maximum** on a template.
- **WhatsApp shows three.** Past that it hides the rest behind a "See all options" control. Treat three as the practical design limit and 10 as the ceiling.
- **At most 2 `URL` buttons.**
- **At most 1 `PHONE_NUMBER` button.**
- **Labels up to 25 characters**, no duplicates, no placeholders in labels.
- **Quick replies must be grouped together** — Meta rejects them mixed in between link and call buttons.
- A `URL` button's link must start with `http://` or `https://`, may end in one `{{1}}` and nothing else, and needs an example of the full link with the value filled in.

## Languages

A template is identified by **name and language together**, not by an id. That pair is what Meta matches on when you send.

The console offers: `en`, `en_US`, `en_GB`, `hi`, `mr`, `gu`, `ta`, `te`, `bn`, `kn`, `ml`, `pa`.

At send time you may omit `language`, or name one that has no exact match. Resolution then tries, in order: an exact match, then the same base language (`en_US` falls back to `en`), then any `en*` variant, then the first approved template with that name. This means a send does not fail merely because you asked for `en_GB` and only `en` was approved.

To offer a template in a second language, duplicate it, keep the name, and change the language. Same name plus same language is rejected as a duplicate.

## Writing one

::: steps

::: step Open the composer

**Channels → WhatsApp → Templates → New template**. It is a single form, not a wizard.

:::

::: step Describe the message, or write it yourself

The composer can draft the whole template from a plain-English description — *"Let customers know their order shipped, with a tracking link"* — including placeholder placement, sample values and category. If the agent you selected has a knowledge base, the draft is written from your actual business rather than generically.

Whatever it produces is a starting point. Read every line before submitting; you are the one accountable for what Meta reviews.

:::

::: step Name it for the system that will send it

`order_shipped`, `appointment_reminder_confirm`, `payment_receipt`. Lowercase, underscores, no spaces. Customers never see the name — your code does, and so does whoever debugs it.

:::

::: step Check the preview

The preview renders both what the customer receives (samples filled in) and what Meta's reviewer reads (placeholders visible). Read the reviewer view. Most rejections are obvious from it.

:::

::: step Submit for review

Choose **Submit for review**. The template appears as `pending`. Review usually takes a few minutes to a day, and the status updates itself.

If the new template is not in the list immediately, press **Sync** — that pulls the current state of every template from Meta, including ones you created directly in WhatsApp Manager.

:::

:::

## Templates cannot be edited

There is deliberately no edit control. An approved template is a thing Meta reviewed; changing its text would mean sending customers something that was never reviewed.

To change one, open it and choose **Duplicate as new**:

- **Change the name** to create a separate template. Both exist; you switch your code over when the new one is approved, then delete the old one.
- **Keep the name and change the language** to add a language variant.

This is also why deploying a template change is a two-step release: get the new template approved first, then point your code at it. Doing it in the other order means an outage between the code deploy and the approval.

::: danger Deleting removes every language variant
Meta deletes templates by name, not by id. Deleting `order_shipped` removes the English, Hindi and Marathi versions together, and anything still sending that name starts failing with `template_not_found` immediately. There is no undo and no grace period.
:::

## Sending one

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-shipped" \
  -d '{
    "to": "+919876543210",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "variables": ["Asha", "AM-4821", "6 PM today"],
      "button_variables": ["AM-4821"]
    }
  }'
```

```javascript Node.js
const response = await fetch("https://services.amomic.in/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-shipped`,
  },
  body: JSON.stringify({
    to: order.customerPhone,
    template: {
      name: "order_shipped",
      language: "en",
      variables: [order.customerName, order.reference, order.etaLabel],
      button_variables: [order.reference],
    },
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}/${error.details?.reason}: ${error.message}`);
}
```

```python Python
import os, httpx

response = httpx.post(
    "https://services.amomic.in/api/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
        "Idempotency-Key": f"order-{order.id}-shipped",
    },
    json={
        "to": order.customer_phone,
        "template": {
            "name": "order_shipped",
            "language": "en",
            "variables": [order.customer_name, order.reference, order.eta_label],
            "button_variables": [order.reference],
        },
    },
)
response.raise_for_status()
```

:::

```json title="201 Created"
{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "sent"
}
```

`status: "sent"` means we accepted it and Meta took it. It is an acceptance acknowledgement, not a delivery receipt — delivery and read state arrive later on the `message.status` [webhook](/webhooks/events).

Send the `Idempotency-Key`. A network timeout on a template send is exactly the case where a naive retry messages a customer twice. See [Idempotency](/api/idempotency).

## Errors you will actually hit

```responses
[
  {"status": 404, "code": "not_found", "reason": "template_not_found", "description": "No approved template with that name. Either the name is wrong, or the template is still `pending` or was `rejected`."},
  {"status": 400, "code": "invalid_argument", "reason": "template_variables", "description": "Wrong number or shape of variables for that template's placeholders."},
  {"status": 403, "code": "permission_denied", "reason": "suppressed", "description": "The recipient has opted out. Templates do not bypass suppression."},
  {"status": 412, "code": "failed_precondition", "reason": "channel_not_connected", "description": "No WhatsApp sender is connected to this workspace."}
]
```

Note what is *not* in that list: there is no window error on a template send. Templates work whether the window is open or closed — that is their entire purpose.

## Practical guidance

::: tip One template per system event, named after the event
`order_shipped`, `order_delivered`, `payment_received`. Resist the general-purpose template with six placeholders that any system can fill — it reviews badly, reads badly, and the day one caller passes the wrong argument order you have shipped nonsense to real customers.
:::

- **Get templates approved before you write the integration.** Review time is not under your control. Building first means your launch date is Meta's decision.
- **Put a `QUICK_REPLY` on anything you want a response to.** A tapped quick reply is an inbound message, so it opens the 24-hour window and your agent can take the conversation from there in free-form text.
- **Keep the body under 1024 characters and well under it in practice.** Long templates read as promotional regardless of category.
- **Do not put an opt-out line in the footer of a utility template** unless you want it there; the opt-out keywords work whether or not you advertise them. `Reply STOP to opt out` is standard on marketing and unnecessary noise on a delivery notification.
- **Watch the quality rating** on the sender after you start sending at volume. Red quality means recipients are blocking or reporting you, and Meta reduces messaging limits if it stays that way.

## Next

::: cards

::: card The 24-hour window
[Why templates exist](/channels/whatsapp-window) and when a free-form send is legal instead.
:::

::: card POST /messages
[The complete send contract](/api/messages), including sender selection and metadata.
:::

::: card Order-shipped update
[End to end](/recipes/order-updates) — template, idempotent send, and the webhook that confirms delivery.
:::

::: card Tools & actions
[Let the agent send a template itself](/build/tools), restricted to the ones you allow.
:::

:::


----------------------------------------------------------------------------
## How voice works
URL: https://docs.amomic.in/channels/voice
----------------------------------------------------------------------------

A customer dials your number. It rings once, maybe twice, and your agent answers — the same agent that answers on your website and on WhatsApp, with the same knowledge base behind it. It speaks first, listens, answers, and hangs up when the conversation is done. Afterwards you get a transcript, an outcome, and response-time numbers for every turn.

This page is about the inbound side: what the platform does with a call from the moment it arrives to the moment it finalises. Placing calls yourself is covered in [Outbound calls](/channels/outbound-calls).

## The path a call takes

```
Customer dials your number
  → the number identifies the workspace and the deployment on it
  → the deployment identifies the agent that answers
  → the call is answered
  → recording notice, if recording is on
  → the agent's opening line
  → the conversation
  → hangup, transcript written, outcome recorded
```

Every step depends on the one before it, and the first two are where nearly all setup problems live.

### Routing is by the number that was dialled

The dialled number is the routing key. Not the caller, not the agent, not the workspace — the number.

One number carries exactly one deployment, and that deployment names exactly one published agent version. Two numbers in the same workspace can answer with two completely different agents, in two different languages, with recording on for one and off for the other. Nothing about that is shared.

This has a consequence worth internalising before you debug anything: **you cannot change what a number does by editing an agent.** Editing an agent produces a new draft. The number keeps answering with the version frozen into its live deployment until you publish and roll a new one. That is the whole point — see [Deployments](/build/deployments).

### Three ways a call does not reach an agent

They look similar from the outside and are completely different underneath.

| What happened | What the caller experiences | What you see |
|---|---|---|
| The number is not in your workspace at all | The call is refused before it is answered | Nothing. No call record, no charge — there is nothing to attach a record to |
| The number is yours, but no agent is deployed to it | The call is refused before it is answered | Nothing, for the same reason |
| Your workspace is billing-suspended | The call **is** answered, the agent speaks a short out-of-service line, then hangs up | A call record with outcome `suspended` |

::: warning A number with no deployment is silent, not broken
A provisioned number that has never had an agent deployed to it refuses calls. Nobody hears an error message and nothing appears on the Calls page, which makes it look like the number was never provisioned. Check **Channels → Phone / Voice** — an owned number with no agent shows *"Ready to connect to an agent"* rather than *"Answered by …"*.

Assigning an agent tenant-wide does not help either. A number must be explicitly deployed to. See [Numbers & KYC](/channels/phone-numbers).
:::

## The agent always speaks first

There is no silent pickup and no "please state your query after the tone". The moment the call connects, the agent speaks: the recording notice if recording is enabled, then the opening line, and only then does it start listening.

That ordering is deliberate. A caller who hears nothing for two seconds assumes the call failed and hangs up, and a recording notice that arrives after the caller has already said something is not a notice at all.

The opening line is free text you set per number, up to 500 characters. Keep it to one or two sentences — it is spoken, not read, and a long greeting is a long wait before the caller can talk. If you leave it empty, a written-in fallback is used in the call's opening language; the English one is:

> Hello, thank you for calling! I'm your virtual assistant — how may I help you today?

You can also have the opening line drafted from the agent's knowledge base — **Generate with AI** in the voice settings writes one short line grounded in what the agent actually knows. It is a proposal: it appears in the field for you to read, edit, and save. Nothing is generated at call time, so the greeting a caller hears is always a string you approved.

::: note Outbound calls do not use this greeting
"Thank you for calling" is wrong on a call you placed. Outbound calls open with a fixed template that names your business, discloses that the caller is an assistant, and asks whether now is a good time. See [Outbound calls](/channels/outbound-calls).
:::

## Settings live on the number, not on the workspace

This is the single most common mental-model error on this channel.

The greeting, the opening language, the call language mode, recording, and the maximum call length are all properties of **the deployment on one number**. Change them and you change what that number does. The number next to it is unaffected.

A workspace-level set of the same values exists, and it is used only as a fallback for a number that has no value of its own. It is not a control panel for your voice channel — if you set the workspace greeting and the number has its own, the number wins, every time.

Two practical consequences:

- **Roll out changes per number.** Turning recording on for one number does not turn it on anywhere else. If you need it everywhere, do it everywhere.
- **Saving voice settings rolls a new deployment.** The console tells you so: *"Saving rolls a new deployment onto this number so the change is auditable. Calls already in progress finish on the old settings."* A call in flight never changes language or greeting under the caller.

The full field list, with limits, is in [Numbers & KYC](/channels/phone-numbers#settings-that-live-on-a-number).

## What a transcript contains

Every finalised call carries a transcript: an ordered list of turns, each one a speaker, the text, and an offset from the start of the call. The Calls page renders it with `mm:ss` offsets, the caller labelled `Caller` and the agent labelled with its own name.

```mock
{"component": "CallsScreen", "props": {"caption": "One call, fully expanded: outcome badge, response-time tiles, recording, and the turn-by-turn transcript."}}
```

Four things about transcripts that matter when you are auditing a call:

**There are exactly two speakers.** Every turn is either the caller or the agent. There is no third role, no system speaker, and no separate channel for tool activity in the transcript itself.

**Offsets are relative to the start of the call**, in milliseconds, not wall-clock timestamps. `00:14` means fourteen seconds after the call connected. Use `started_at` on the call record if you need absolute times.

**An interrupted agent turn is recorded as what the caller actually heard**, with the suffix `—[interrupted]`. If the agent was three words into a sentence when the caller spoke over it, the transcript holds those three words and the marker — not the sentence the agent intended to say. Audio that was never played is never written down. This is what makes a transcript usable as evidence: it is a record of the call, not of the agent's intentions.

**Spoken filler is in there too.** When the agent says something deterministic — a hold line while it looks something up, a check that you are still there, a goodbye — that line is written as an agent turn. It reads as slightly repetitive prose in the transcript, which is exactly what it sounded like on the phone.

In the linked inbox conversation, those operational lines are separated out onto their own rail so they do not clutter the message history, and they are excluded from message counts.

### Response times, not per-turn latency

Each call carries aggregate response-time statistics — the median, p95, and slowest turn, measured from the moment the caller stopped speaking to the moment the first audio came back. The console shows them under **Response performance** with a target of 1.5 seconds on the median.

There are no per-turn latency numbers. If one answer felt slow, the slowest-turn figure tells you how slow the worst turn was, but not which turn it was.

::: note There is no automatic call summary
The call record has a `summary` field and it is not populated. Do not build reporting on it. What you have is the transcript and the outcome; if you need a summary, generate one yourself from the transcript.
:::

## Recording

Recording is **off by default**, on every number, and stays off until someone explicitly turns it on for that number's deployment.

When it is on, the caller hears a notice before the greeting — before anything else on the call:

> Just to let you know, this call may be recorded for quality and training purposes.

On a Hindi or mixed-language call the same notice is spoken in the Hinglish register instead.

::: warning It is an announcement, not a consent gate
The caller is told. There is no key to press to decline, no branch that continues without recording, and no way for the caller to opt out mid-call short of hanging up. If your obligations require a real opt-out, this feature does not provide one — and telling callers something is optional when it is not is worse than not telling them.

Whether recording a given call is lawful is your decision to make, per jurisdiction and per use case, before you enable it.
:::

The recording is a single audio file per call, produced by the platform rather than by the phone network. Caller and agent are on separate stereo channels — caller left, agent right — laid on one shared timeline with silence filled in, so the two sides line up and you can hear exactly where an interruption landed.

Play recordings from the call detail pane on the Calls page. Playback links are minted on demand and expire after an hour, so a link you copied yesterday will not work today; open the call again. Over the API, `recording_uri` on [`GET /calls/{call_id}`](/api/calls) is a storage reference rather than a ready-to-play URL.

::: danger There is no automatic deletion
No retention schedule runs against call recordings today. A recording you make stays until it is deliberately removed. Do not enable recording on the assumption that the platform will age the audio out for you, and factor that into whatever you tell callers and whatever your own policy says.
:::

## Call statuses

`status` is where the call is in its lifecycle. These are the exact strings written to the call record and returned by the API.

| Status | Meaning |
|---|---|
| `in_progress` | The call is connected and the conversation is happening. The Calls page badges this `Live`. |
| `ringing` | An outbound call has been dialled and the destination handset is ringing. Nobody has answered. |
| `dialing` | A bridged call — one where a member of your team is being connected to a customer — is being set up. |
| `completed` | The call finalised. This includes outbound calls nobody answered, which finalise as `completed` with a duration of zero. |
| `failed` | The call could not be set up, or the carrier refused to place it. |
| `no_answer` | A bridged call that never connected both legs. |

::: warning `completed` does not mean the conversation happened
An outbound call that rang out lands on `completed` with `duration_seconds: 0` and an outcome that tells you why. Always read `status` and `outcome` together — and if you are branching in code, read `outcome`.
:::

## Call outcomes

`outcome` is the richer field: *why* the call ended. It is `null` while a call is live and set once at finalisation.

| Outcome | What it means | Console label |
|---|---|---|
| `caller_hangup` | The caller ended the call. This is the ordinary ending for a conversation that ran its course, and the default when nothing more specific applies. | `Completed` |
| `agent_hangup` | The agent decided the conversation was finished and ended the call itself — the customer said thanks and goodbye, and the agent took them at their word. | `Completed by agent` |
| `idle` | The line went quiet. The agent checked whether the caller was still there, got nothing back, said goodbye and hung up. Usually a caller who walked away or a dead handset. | `Idle hangup` |
| `max_duration` | The call hit the maximum length configured on that number and was ended. If you see this often, either the cap is too tight or the agent is not reaching a conclusion. | `Time cap` |
| `suspended` | The workspace is billing-suspended. The call was answered only to say the service is unavailable, then ended. No agent ran. | — |
| `setup_error` | The call was answered but the audio path failed to come up, so no conversation was possible. The caller heard silence and hung up. | `Setup failed` |
| `originate_error` | The call was never placed — the carrier refused it at dial time. Outbound only. | — |
| `hangup` | A bridged call in which both legs were connected ended normally. Not an AI conversation. | — |
| `no_answer` | Nobody picked up, or the network ended the call for a reason we do not map more precisely. Outbound and bridged calls only. | — |

Outcomes marked `—` have no badge of their own on the Calls page; those rows fall back to showing the call's status.

The outcome filter on the Calls page is deliberately narrower than this list — it offers `All outcomes`, `Completed`, `Idle hangup`, `Time cap`, and `Failed`. To see everything, clear the filter and read the badges.

::: note Outbound network outcomes
Calls you place through the API can also finalise as `busy`, `rejected`, `invalid_number`, `unreachable`, or `congestion`, depending on what the network reported. Those are documented alongside the endpoint in [Calls](/api/calls).
:::

### Which outcomes are your problem

- `caller_hangup`, `agent_hangup` — nothing to do. These are calls that worked.
- `idle` — worth sampling. A handful is normal. A spike usually means the agent asked something the caller could not answer, or a long silence while it looked something up.
- `max_duration` — read the transcripts. A call that hits the cap is almost never a call that went well.
- `setup_error`, `originate_error` — infrastructure. Not caused by the caller and not fixable in the agent's instructions.
- `suspended` — billing. Every call is being answered with an out-of-service line; fix it before you look at anything else on this page.

## Finding a call

Open **Calls** in the console. Every call, inbound and outbound, in one list, newest first.

- **Search** by caller, by number, or by call id.
- **Filter** by direction, by outcome, and by agent.
- **Metric cards** across the top: `Loaded calls`, `Talk time`, `Completion`, `Median response`. They describe the calls currently loaded, not your account for all time — load older calls and they change.
- **Select a call** for the full detail pane: the meta tiles (`Business number`, `Direction`, `Duration`, `Conversation turns`), response performance, the recording if there is one, and the transcript.

From your own systems, read one call with [`GET /api/v1/calls/{call_id}`](/api/calls), or subscribe to `call.started` and `call.ended` [webhooks](/webhooks/events) and stop polling. There is no endpoint that lists calls — the console list is not backed by a public API, so keep the `call_id` values you create.

## Troubleshooting

::: details Callers say it rings and then cuts off
No agent is deployed to that number, or the number is not in your workspace. Both refuse the call before answering, so there is no call record to look at — the absence of a record is the diagnosis. Check **Channels → Phone / Voice** for `Ready to connect to an agent`.
:::

::: details Every call ends immediately with outcome `suspended`
The workspace is billing-suspended. Callers are hearing an out-of-service line. No agent runs, no greeting is spoken, and nothing you change on the number will help until billing is resolved.
:::

::: details The greeting is not the one I set
You almost certainly set it in a different place than the one the call read. The number's own value wins over the workspace value. Open the voice settings for the deployment on *that number* and check the opening line there.

If you edited the agent instead, remember that editing produces a draft — the number keeps running the version its live deployment froze until you publish and roll a new deployment.
:::

::: details The agent answered in the wrong language
Two settings control this and they are not the same thing: the call language mode decides what the agent can follow, and the opening language decides which one it starts in. See [Languages](/channels/voice-languages).
:::

::: details Recording is on but there is no audio
The call detail pane distinguishes the cases: *"Recording was enabled, but the audio is unavailable."* means recording was on for that call and the file did not survive. A call with recording off shows no recording section at all. Also check whether recording was turned on *after* the call — the setting applies from the next call onwards.
:::

::: details Response times are fine but the call felt slow
Median and p95 measure the gap between the caller finishing and the first audio coming back. They do not measure how long the agent then talked for. A verbose agent feels slow with excellent latency numbers — tighten the instructions rather than chasing milliseconds.
:::

## Next

::: cards

::: card Get a number
[Numbers & KYC](/channels/phone-numbers) — the compliance review, the request lifecycle, and every setting that lives on a number.
:::

::: card Languages
[Call mode versus opening language](/channels/voice-languages), the eleven languages, and how to pick.
:::

::: card Place calls yourself
[Outbound calls](/channels/outbound-calls) — what the customer hears first, and what you are responsible for.
:::

::: card Drive it from code
[POST /calls](/api/calls) — place, read, and hang up calls over the REST API.
:::

:::


----------------------------------------------------------------------------
## Numbers & KYC
URL: https://docs.amomic.in/channels/phone-numbers
----------------------------------------------------------------------------

Phone numbers are regulated. You cannot click a button and have one thirty seconds later, and anyone offering you that in India is skipping a step you are legally on the hook for. Getting a number here is a three-part process: verify your business once, request a specific number and have it reviewed, then deploy an agent onto it.

The first part takes a day or so. The second takes hours. The third takes a minute. Plan the first one into your timeline and the rest stops being a surprise.

```mock
{"component": "PhoneScreen", "props": {"caption": "Channels → Phone / Voice: the numbers your workspace owns, which agent answers on each, and any request still in review."}}
```

## One-time business verification

Before your workspace can search for a number at all, it needs verified business identity on file. This is a **one-time step per workspace** — do it once and every number you request afterwards skips straight to number search.

The console is blunt about why: *"Telecom regulations require verified business identity before a phone number can be issued."*

### What you submit

Two text fields and two documents. Everything is required; there is no partial submission.

| Field | What it is |
|---|---|
| **Legal name** | Your registered entity name, exactly as it appears on the registration document. Not your brand, not your trading name. |
| **Alias** | A short name for this profile — usually your brand. This is the label, the legal name is the identity. |
| **Registration certificate** | Certificate of Incorporation, or your Udhyam registration. |
| **Tax proof** | GST certificate, or your business PAN. |

Both documents: PDF, PNG or JPEG, up to 15 MB each. Both are validated before either is uploaded, so a bad second file does not leave you with a half-finished submission to clean up.

::: warning The legal name must match the document
This is the single most common rejection. If the certificate says `Acme Technologies Private Limited`, submit that — not `Acme`, not `Acme Technologies Pvt Ltd`. A reviewer comparing two strings that do not match has no way to approve you, and a rejection restarts the clock.
:::

### The review, and what to expect

A person reads your submission. That is the honest description — it is not an automated check that fails in three seconds, and it is not a queue that takes a fortnight.

> Usually the same business day, up to 5 business days.

Treat the second number as the one to plan around, especially if you submit late on a Friday. You are notified in the console and by email when it resolves.

| Status | Console badge | What it means |
|---|---|---|
| `pending` | `Under review` | Submitted. Number search is still locked. |
| `approved` | `Verified` | Number search is unlocked for the whole workspace, permanently. |
| `rejected` | `Rejected` | Something did not check out. The reason is shown with the badge. |

::: note Resubmission starts the review fresh
You can only resubmit from `Rejected`. A resubmission replaces the previous one entirely — new documents, new details, new review. There is no way to amend a submission that is already `Under review`; wait for it to resolve.
:::

Until verification is approved, the request dialog blocks you with *"One-time verification required"* and sends you to **Settings → Compliance**. Nothing about number search is available before that.

## Requesting a number

Once verification is approved, **Channels → Phone / Voice → Request number**.

::: steps

::: step Search for a number

Pick a country and, if you care about the digits, a pattern — a prefix like `8069` narrows the results. Leave it empty to see whatever is available.

Each result shows the number, its type, and where it is. If nothing matches, the pattern is usually the reason: *"Try a different pattern or leave it empty."*

:::

::: step Send one number for review

Choose a number and confirm. The console states exactly what happens next, and it is worth reading rather than clicking past:

- *"Your selection goes to the Amomic-AI team for review. No purchase happens yet."*
- *"After approval, we purchase and configure it, then notify you here and by email."*
- *"Open Manage number and connect it directly to the agent that should answer."*

Nothing is bought at this point. Your request is a request.

:::

::: step Wait for provisioning

After approval, the number is purchased, attached to the voice network, and registered to your workspace. Then it appears in your numbers list as `Active`.

:::

::: step Put an agent on it

A provisioned number with no agent answers nothing. See [Assigning an agent](#assigning-an-agent) below.

:::

:::

### Request statuses

A request moves through these states. The console badge and the copy underneath tell you which one you are in.

| Status | Console badge | What it means |
|---|---|---|
| `pending_review` | `Under review` | Waiting on the Amomic-AI team. *"No purchase has been made. Our team is reviewing your selection."* |
| `provisioning` | `Setting up` | Approved. The number is being purchased and configured. *"Approved — we're purchasing and configuring the number."* |
| `provisioned` | — | Done. The number leaves the request list and appears as an owned number, `Active`. |
| `rejected` | `Not approved` | A reviewer declined. The reason is shown, or *"Choose another number or contact support."* |
| `failed` | `Needs attention` | Approved, but provisioning did not complete. *"Our team has been notified and will follow up."* You do not need to do anything. |

Releasing a number runs through the same reviewed lifecycle in reverse: `releasing`, then `released`.

::: note There is no direct purchase
Every number goes through review. There is no self-serve buy path, no API to purchase a number, and no way to skip the queue. If you already have a number provisioned on the Amomic-AI platform, the numbers card has an **Add number** disclosure for attaching it to this workspace.
:::

### Releasing a number

**Manage → Request deletion**, which creates a reviewed request exactly like a purchase does.

> Deletion is never immediate. It creates an admin request, and the number keeps routing calls until approval.

That is intentional. A number that vanishes the instant someone clicks a button is a number your customers are still dialling. Calls continue normally while the request is reviewed, and the row shows `Deletion requested` and then `Deleting` while it moves.

## Assigning an agent

A number and an agent are joined by a **deployment**, not by a setting on the number. Two routes reach the same place.

**From the number.** **Manage** on the number, then **Answering agent**. Pick a published agent and save. The console notes that *"Reassignment takes effect on the next call"* — a call already in progress finishes with whoever answered it.

**From the agent.** **Deploy → Phone**, then choose the number. Same result, written from the other side.

Either way, three rules follow:

- **One number, one agent.** There is no round-robin, no fallback agent, no time-of-day routing. If you need two agents, use two numbers.
- **The agent must be published.** A draft cannot be deployed; the console blocks with *"Publish the agent before deploying it to a channel."* A deployment freezes a published version so it cannot change under your customers.
- **Pausing the deployment unassigns the number.** The number stays yours and stays active, but it stops answering. Callers get a refused call and no call record appears — see [How voice works](/channels/voice).

You can also unassign deliberately: the agent picker has a `No agent (unassign)` option.

## Settings that live on a number

These are the runtime settings for one number, set on the deployment that binds an agent to it. They are per number. A second number in the same workspace has its own set and is unaffected by anything here.

| Setting | Values | Default |
|---|---|---|
| **Opening line** | Free text, up to **500 characters**. Spoken the moment the call connects, before the caller says anything. Empty falls back to a written-in greeting in the call's opening language. | empty |
| **Greet callers in** | One of the eleven supported languages, and it must be allowed by the call language mode. | Depends on the mode — see [Languages](/channels/voice-languages) |
| **Call language** | `en`, `multi`, or `indic`. What the agent can understand and speak on this number. | `multi` |
| **Record calls** | On or off. When on, callers hear a recording notice before the greeting. | **off** |
| **Maximum call length** | **60 to 3600 seconds**. The call is ended when it hits the cap, with outcome `max_duration`. | **600 seconds** (10 minutes) |

A few notes that save time later:

- **The opening line counter says `{n}/500 · spoken in {language}`.** That second half is a live reminder of which language the line will be read in. Writing English text and setting the opening language to Hindi produces English words in a Hindi voice, which sounds exactly as bad as it reads.
- **`Generate with AI`** drafts a single short opening line from the agent's knowledge base and puts it in the field. It is a suggestion — read it, edit it, save it. Nothing is generated during a call.
- **The maximum call length is a safety net, not a target.** Ten minutes is generous for a support call and thin for a detailed booking. Set it high enough that a genuine conversation is never cut off, then look at how many calls end on `max_duration` — if the answer is more than a few, the agent is not reaching a conclusion and the cap is only hiding it.

::: note Saving rolls a new deployment
The console says so directly: *"Saving rolls a new deployment onto this number so the change is auditable. Calls already in progress finish on the old settings."*

A live deployment is immutable by design. Changing a setting clones it, validates the clone, and activates it in place of the old one, so there is a record of what the number was configured to do at any point in time. See [Deployments](/build/deployments).
:::

## Using a number as caller ID

The numbers you own are also the numbers you can place calls from. When you call [`POST /api/v1/calls`](/api/calls), the `from_number` must be an active number in your workspace, and the agent that speaks is **the agent deployed to that number** — not the one named in `agent_id`.

That means a number is a routing decision in both directions. Pick the caller ID and you have picked the agent. See [Outbound calls](/channels/outbound-calls).

## Troubleshooting

::: details Number search is greyed out
Business verification is not approved. Check **Settings → Compliance** for the badge: `Under review` means wait, `Rejected` means fix and resubmit.
:::

::: details Verification was rejected and I do not know why
The reason is shown next to the badge, and repeated in the email. The usual causes are a legal name that does not match the registration document, an expired or illegible document scan, or a tax proof that belongs to a different entity than the registration certificate.
:::

::: details The request has been `Under review` since yesterday
Number requests are reviewed by a person, on business days. If it has been longer than the compliance SLA, contact support with the request open in front of you.
:::

::: details The number is `Active` but nobody can reach it
No agent is deployed. An owned number with no agent shows *"Ready to connect to an agent"* instead of *"Answered by …"*, and refuses calls without producing a call record.
:::

::: details I deployed an agent but calls still use the old greeting
Check which number you edited. Settings are per number, and the greeting you set on the workspace-level card is only a fallback for numbers that have none of their own.
:::

::: details Can I move a number to another workspace
Not directly. A number belongs to one workspace. Release it through the reviewed deletion flow, then request it again from the other workspace — with no guarantee it is still available in between.
:::

## Next

::: cards

::: card How voice works
[The inbound call path](/channels/voice), transcripts, recording, and every status and outcome.
:::

::: card Languages
[Call mode and opening language](/channels/voice-languages) — the distinction that decides what your agent can follow.
:::

::: card Outbound calls
[Calling customers](/channels/outbound-calls) from a number you own, and what you are responsible for.
:::

::: card Deployments
[How a published agent gets onto a channel](/build/deployments), and why a live one cannot be edited in place.
:::

:::


----------------------------------------------------------------------------
## Languages
URL: https://docs.amomic.in/channels/voice-languages
----------------------------------------------------------------------------

Voice has two language settings and they do different jobs. Nearly every "the agent answered in the wrong language" report is someone who changed one and expected the other.

- **Call mode** — which languages the agent is able to understand and speak on this number, for the whole call.
- **Opening language** — which single language it says its first sentence in.

The mode is the boundary. The opening language is a starting point inside that boundary. You must set both, and the opening language must be one the mode allows.

## Call mode

Three values. The field is called **Call language** in the console; the values are exactly these strings.

| Value | Console label | What the agent can follow |
|---|---|---|
| `en` | `English only` | English. Nothing else. |
| `multi` | `Hindi + English` | Hindi and English, including callers who switch between them mid-sentence. |
| `indic` | `All Indian languages` | All eleven languages below, and switches with the caller mid-call. |

The console describes them the same way, and the descriptions are accurate rather than promotional:

- `English only` — *"Highest transcription accuracy. Best when your callers speak English."*
- `Hindi + English` — *"Natural Hinglish — handles callers switching mid-sentence. The usual choice for India."*
- `All Indian languages` — *"Follows the caller across Hindi, Bengali, Marathi, Tamil, Telugu, Gujarati, Kannada, Malayalam, Punjabi and Odia — and switches with them mid-call."*

Call mode is set per number, on the deployment that binds an agent to it. Two numbers in the same workspace can run in two different modes. See [Numbers & KYC](/channels/phone-numbers#settings-that-live-on-a-number).

## The eleven languages

These are the language codes for the opening language. The names are the ones the console shows.

| Code | Language |
|---|---|
| `EN` | English |
| `HI` | Hindi |
| `BN` | Bengali |
| `MR` | Marathi |
| `TA` | Tamil |
| `TE` | Telugu |
| `GU` | Gujarati |
| `KN` | Kannada |
| `ML` | Malayalam |
| `PA` | Punjabi |
| `OR` | Odia |

The console renders each one as `English name · native script` — `Hindi · हिन्दी`, `Tamil · தமிழ்`, and so on.

## What each mode allows

The mode gates the opening language. Pick a mode and the console greys out every language it does not allow.

| Call mode | Opening language may be | Default |
|---|---|---|
| `en` | `EN` only | `EN` |
| `multi` | `EN` or `HI` | `HI` |
| `indic` | Any of the eleven | `HI` |

Two things follow from that table.

**`en` collapses the choice.** With English-only mode there is exactly one legal opening language, so the picker is disabled. That is not a bug in the console — there is nothing to pick.

**`multi` defaults to Hindi, not English.** If you want a Hinglish-capable number that opens in English, set the opening language to `EN` explicitly. Leaving it alone gets you Hindi.

If you try to save an impossible pair, you are stopped:

> That opening language isn't available in this call language mode.

The console explains the same thing in place, naming the way out:

> Only English available on this call language. Choose "Hindi + English" or "All Indian languages" above to greet in another language.

::: note A stale combination is repaired, not fatal
Settings get edited in two steps and out of order — someone narrows a number from `indic` to `en` while its opening language is still `TA`. That combination is nonsense, and it does not fail the call. At call time the mismatch is resolved to a language the mode does allow, and the call proceeds normally.

A caller never hears a failure because of this. But the greeting they hear is not the one you configured, so if a number is opening in an unexpected language, check the mode before you check anything else.
:::

## Choosing a mode

The right answer is usually `multi`, and the reasoning is worth having in full because the wrong choice is quiet — it does not error, it just degrades every call.

### `multi` — the right default for Indian support

Real callers do not stay in one language. A caller opens in English, gets frustrated, switches to Hindi for the complaint, then reads out an order number in English again. `multi` is built for exactly that sentence and handles the switch without a beat.

Choose it unless you have a specific reason not to. It is the mode most support lines in India should run in, and it is the platform default.

### `en` — when you genuinely only serve English

Constraining the model to one language is the single biggest accuracy win available on this channel. There is no code-switching to detect and no ambiguity between two plausible transcriptions, so English names, addresses and reference codes come through more reliably.

The condition is real, though: *genuinely* only English. If one caller in twenty speaks Hindi, `en` does not politely handle them — it transcribes their Hindi as garbled English and the agent answers the garbage. Pick `en` for an international product line or an internal desk where the language is a given, not because most of your callers speak English.

### `indic` — when your callers span regions

A national helpline, a service with customers across states, a number printed on a product sold everywhere. `indic` lets the caller lead and follows them.

The cost is breadth: recognising eleven languages is a harder problem than recognising two, and accuracy on any one of them is not what a narrower mode gives you. Do not choose `indic` "just in case" on a number whose callers are all in Delhi. Choose it when the spread is real.

::: tip One number per language community beats one number for everyone
If you have both a Mumbai line and a Chennai line, two numbers — `multi` on one, `indic` on the other, or `indic` opening in `TA` — will outperform a single `indic` number for both. Mode and opening language are per number precisely so you can do this.
:::

## Switching language mid-call

Inside whatever the mode allows, the agent follows the caller. If a `multi` call opens in Hindi and the caller answers in English, the agent continues in English.

Switching requires **clear evidence** — a substantial stretch of speech in the other language, not one word. That threshold exists because the alternative is worse. A single stray token is enough for a recogniser to guess wrong, and an agent that flips language on one ambiguous word will spend the rest of the call in a language the caller never asked for. Being slightly slow to switch is recoverable. Switching on a false positive is not.

Two consequences worth knowing:

- **A one-word answer will not flip the call.** `"haan"` in an English call is not a request to switch to Hindi, and the agent treats it accordingly.
- **A caller who wants to switch should say a sentence.** In practice they do; people who change language rarely do it one word at a time.

## Where to set it

Both settings live in the same place, on the deployment that puts an agent on a number.

::: steps

::: step Open the number's voice settings

From the agent, open the phone deployment and choose **Voice settings**. From the channel, **Channels → Phone / Voice → Manage** on the number.

:::

::: step Set the call language first

**Call language** is the radio group at the top. Setting it first is not a style preference — it decides which options the language picker below it will even offer.

:::

::: step Then set the opening language

**Greet callers in** lists the eleven languages with the disallowed ones greyed out. If the one you want is greyed out, the mode above is the reason.

:::

::: step Rewrite the opening line if you changed language

The greeting is text you wrote; changing the opening language does not translate it. The counter under the field reads `{n}/500 · spoken in {language}` — check that the second half matches the language the text is actually in.

:::

::: step Save, then make a real call

Saving rolls a new deployment onto the number, so the change is auditable and calls in progress finish on the old settings. Then dial the number yourself. A test call is thirty seconds and catches the greeting-in-the-wrong-language mistake before a customer does.

:::

:::

There is also a workspace-level version of these settings on the **Phone / Voice** page. It is a fallback for numbers that carry no value of their own, not a master switch — a number's own setting always wins. If you are changing settings and hearing no difference, you are probably editing the fallback.

## Related language behaviour

**The greeting is text, in the language you chose.** The opening line is free text you write. Nothing translates it. If the opening language is `TA` and your greeting is written in English, the call opens with English words spoken in the Tamil voice. The console shows `spoken in {language}` under the field for exactly this reason — write the greeting in the language you selected.

**The recording notice has two registers.** When recording is on, the notice spoken before the greeting exists in English and in the Hindi/English register. An `indic` number uses the Hindi/English line rather than the caller's own language, because the notice is spoken before anyone has said anything and there is no caller language to match yet. See [How voice works](/channels/voice#recording).

**Outbound opening lines have two variants.** The fixed opening on a call you place exists in English and in Hindi/English. An `indic` outbound number opens in the Hindi/English register. See [Outbound calls](/channels/outbound-calls).

## Troubleshooting

::: details The greeting language picker is disabled
The call mode is `en`, which allows one opening language. Change the mode first, then the language.
:::

::: details I set the opening language and the call opened in a different one
Either the mode did not allow it and the value was repaired at call time, or you set it on the workspace-level card while the number carries its own value. The number's value wins.
:::

::: details The agent understands the caller but replies in the wrong language
Check the mode. On `en`, a Hindi caller is transcribed as approximate English and the agent replies in English to something the caller did not say. That is a mode problem, not an instruction problem — no amount of prompting fixes it.
:::

::: details Callers switch to Hindi and the agent stays in English
It needs more than a word or two of evidence before switching. Read the transcript: if the caller genuinely spoke a full Hindi sentence and the agent stayed in English, check that the number is on `multi` or `indic` rather than `en`.
:::

::: details Can I force a call to stay in one language
Yes — set the mode to `en`. There is no per-language lock inside `multi` or `indic`; following the caller is what those modes are for.
:::

## Next

::: cards

::: card How voice works
[The call path end to end](/channels/voice) — routing, the opening line, transcripts, and outcomes.
:::

::: card Numbers & KYC
[Where these settings live](/channels/phone-numbers#settings-that-live-on-a-number), and every other per-number option.
:::

::: card Outbound calls
[What the customer hears first](/channels/outbound-calls) on a call you placed, in each register.
:::

:::


----------------------------------------------------------------------------
## Outbound calls
URL: https://docs.amomic.in/channels/outbound-calls
----------------------------------------------------------------------------

An outbound call is your agent picking up the phone and dialling someone. A payment failed on a delivery that is already moving, a ₹40,000 cart stalled at checkout, an appointment needs confirming today, a lead filled a form ninety seconds ago — moments where a message sits unread and a call does not.

You trigger it from your own systems. The full request contract — every parameter, every error, the response shape — is in the [Calls API reference](/api/calls). This page is the other half: what actually happens on the phone, and what you are on the hook for.

::: warning This is a phone ringing in someone's pocket
Everything on this page follows from that. A message that lands badly is ignored. A call that lands badly is an interruption, and at scale it is a complaint. Read the [responsible calling](#calling-responsibly) section before you ship anything that dials in a loop.
:::

## Which agent speaks

The agent is resolved from **the number you call out on**, not from anything else in the request.

Every number in your workspace has exactly one agent deployed to it. Pick the caller ID and you have picked the agent, its published version, its knowledge base, its instructions, its call language mode, and its time cap. There is no way to place a call with an agent that is not deployed to the number you are dialling from.

That design is not a limitation to work around; it is what makes the call auditable. The customer sees a number, and that number always maps to one agent. If you need a different agent, call from a different number.

The API's `agent_id` parameter does not select the agent. It asserts which one you expect, and the call is refused if it does not match what is actually deployed — a loud failure instead of the wrong agent quietly having the wrong conversation. Pass it for anything money-adjacent. [The details are in the API reference](/api/calls).

## What the customer hears first

The agent speaks the moment the call connects. The opening is a **fixed template** — not your inbound greeting, and not generated at call time.

```text title="English"
Hello, this is {agent name}, a virtual assistant calling on behalf of {company}. Is now a good time to talk?
```

```text title="Hindi + English"
Namaste, main {agent name} bol rahi hoon — {company} ki virtual assistant. Kya abhi baat karne ka sahi samay hai?
```

`{agent name}` is the agent's name, `{company}` is your company name as set on the agent. If either is missing you get a generic stand-in, which sounds exactly as vague as it looks — set both.

Three things happen in that one sentence, in this order, and the order is the point:

1. **It names the business.** The person who answers knows within two seconds who is calling. Not a number they do not recognise; a company they have a relationship with.
2. **It discloses that the caller is a virtual assistant.** Before anything is asked of them, and without being asked. Not doing this is the difference between an AI call people tolerate and one they report.
3. **It asks whether now is a good time.** A real question, with a real answer. Someone in a meeting says no, and the call ends there.

::: note Your inbound greeting is deliberately discarded
"Thank you for calling" is wrong on a call you placed, so the greeting configured on the number is not used for outbound. There is nothing to configure here — the opening is the same template for every outbound call, in the register the number's [call language mode](/channels/voice-languages) resolves to. A number running in `indic` mode opens in the Hindi/English register, because those are the two variants that exist.
:::

## How `purpose` shapes the call

`purpose` is the errand. It is free text you send with the request, it reaches the agent as the reason for the call, and it stays in context for the whole conversation.

Write it the way you would brief a colleague who is about to make the call for you — the situation, the outcome you want, and the fallback:

```json
{
  "purpose": "Confirm Asha's dental appointment on Tuesday 3 October at 4pm, and offer to reschedule if it does not suit."
}
```

```json
{
  "purpose": "Rohit's autopay for order AM-4821 failed this morning. Tell him the delivery is still scheduled, ask if he wants to pay by UPI link instead, and do not ask for card details on the call."
}
```

Note the second one includes something the agent must *not* do. Purpose is the right place for that, because it is the only part of the call that knows about this specific customer.

What `purpose` is not:

- **It is not the greeting.** The opening line is fixed. Purpose shapes what the agent says after the customer answers the "is now a good time" question.
- **It is not knowledge.** The agent still answers from the knowledge base bound to it. Facts a customer might ask about — your refund window, your delivery areas — belong in the knowledge base, where every call can use them. Purpose is for what is true about *this* call only.
- **It is not a script.** The agent is not going to read it out. A purpose written as dialogue produces a stilted call.

Purpose is stored on the call record, so a transcript months later still shows why the call was placed.

## The guards that protect you

These run before anything is dialled, in order, and the first one that trips is what you get back. They exist because the failure modes they prevent are expensive.

**Self-dial is rejected.** You cannot call one of your own numbers. Connecting the agent to the agent produces a conversation between two machines, on your minutes, that ends when one of them hits the time cap.

**Caller ID must be yours.** The number you dial out on has to be an active number in your workspace. You cannot present someone else's number, and you cannot present a number you have released. Number spoofing is not a feature and is not achievable through a misconfiguration.

**Ten concurrent calls per workspace.** A workspace runs at most ten live calls at once. Attempt the eleventh and it is refused with a rate-limit error naming concurrency as the reason — a distinct error from calling the API too fast, and it wants a different response from your code. Your loop is not too quick; your queue is draining faster than calls are ending. Wait for calls to finish rather than retrying immediately.

This cap is also a useful blast radius. A bug in your trigger logic can waste ten simultaneous calls, not ten thousand.

**A suspended workspace cannot dial.** Billing suspension stops outbound calling before any number is contacted. It is a configuration state, not a transient error — retrying will not clear it.

The exact error codes, reasons, and `details` payloads for all of these are in the [API reference](/api/calls#failures).

::: tip Always send an Idempotency-Key
A network timeout on a request that actually succeeded, retried without an idempotency key, is a second phone call to a real person about the same thing. Key it on the business event — `cart-88213-recovery`, not a random UUID — and a retry replays the original result instead of dialling again. See [Idempotency](/api/idempotency).
:::

## After you place the call

The request returns while the phone is still ringing. Everything the customer experiences happens after your code has moved on.

- **Nobody has answered yet.** A successful response means the carrier accepted the call. Duration, outcome, and timestamps are all empty by definition at that moment.
- **Get the result from `call.ended`.** Subscribe to the [webhook](/webhooks/events) and you are pushed the outcome the instant the call finalises. Polling works, but it spends your API rate limit and tells you nothing until the call is over anyway.
- **Unanswered calls still finalise.** A call that rings out ends with a zero duration and an outcome that says why — nobody answered, the line was busy, the number was invalid. Read the outcome, not the status.
- **The transcript and recording behave exactly as they do inbound.** Same page, same detail pane, same rules. See [How voice works](/channels/voice).

## Designing the thing that decides to call

The API call is the easy part. Almost every outbound problem originates in the system that decided to place it, so it is worth building that side deliberately.

**Trigger on an event, not on a schedule.** "Call everyone in this segment" produces calls with no reason attached, and the person who answers can tell. "Call this customer because their payment failed eleven minutes ago" produces a call with an obvious purpose and a much better reception.

**Make the decision idempotent before the request is.** The idempotency key protects you from a retried HTTP request. It does not protect you from two different jobs both deciding the same customer needs a call. Record "we called about this event" in your own database, and check it first.

**Cap yourself below the platform cap.** Ten concurrent calls is the ceiling, not a target. If you are draining a queue, hold your own in-flight count somewhere lower and leave headroom, so a genuinely urgent call is not refused because a batch job filled every slot.

**Decide what each ending means.** Map the outcome to a next action once, in one place, instead of scattering the logic:

| Outcome | A reasonable next action |
|---|---|
| `caller_hangup`, `agent_hangup` | The call happened. Read the transcript if you need the content; otherwise close the task. |
| `no_answer`, `busy` | They were unavailable. At most one retry, hours later, never the same minute. |
| `rejected` | They actively declined. Treat it as a soft signal to stop, not as a reason to try again. |
| `invalid_number` | The number is wrong. Fix the record — retrying cannot help. |
| `unreachable`, `congestion` | A network problem. One retry later is fair. |
| `idle` | Connected but nobody engaged. Do not immediately redial; look at a few transcripts first. |
| `max_duration` | The conversation ran long without concluding. A human should look at this one. |
| `setup_error`, `originate_error` | Your side and the customer both did nothing wrong. Retry once, then alert. |

**Log the `call_id` against your own record at the moment you place the call**, not when it ends. If the process dies in between, the id is the only way back to what happened.

## Calling responsibly

This section is not boilerplate. Outbound calling is the one thing on this platform that can do real damage to people who never asked to hear from you, and to your business through them.

### Get consent before you call

Not implied consent, not "they are a customer so it is fine". A specific, recorded basis for calling this person about this subject: they requested a callback, they bought something and this call is about that purchase, they filled in a form that said you would call. If you cannot point at the moment they agreed, do not place the call.

Keep that basis where your trigger logic can see it, so the check happens before the API call rather than after a complaint.

### Respect the time of day

Use the customer's local time, not your server's. Do not call early in the morning, do not call late at night, and be more conservative than the legal minimum — the legal minimum is not a target. A call at 8:45 p.m. that is technically permitted still lands as an intrusion.

**The platform does not enforce calling hours.** There is no quiet-hours window, no per-day cap per recipient, and no scheduling gate. If you place a call at 3 a.m., the call goes out at 3 a.m.

### Keep your own suppression list

Someone who says "stop calling me" must stop being called — on every number, for every campaign, permanently, and the moment they say it.

WhatsApp opt-outs are handled for you because WhatsApp has a keyword convention to hook into. **Voice has no equivalent.** A caller who tells your agent to stop calling has told your agent; nothing on the platform records that as a suppression, and the next job that queries your database will call them again.

So build the list yourself:

- Store an explicit do-not-call flag per contact and check it immediately before every call.
- Feed it from every channel a person can use to say no — the call transcript, an email, a support ticket, someone on your team.
- Make adding to it trivial and bypassing it impossible. A suppression list a campaign can skip is not a suppression list.
- Never delete an entry to "re-permission" someone.

### Do not use this for cold bulk calling

Placing calls to people who have no relationship with you and did not ask to hear from you is not what this channel is for. It generates complaints, gets numbers blocked, and puts your business on the wrong side of telecom regulation. There is no configuration that makes it acceptable.

::: danger Compliance is yours, and it is not optional
Amomic-AI places the call you ask for. It does **not** check the destination against any do-not-call, do-not-disturb, or preference registry. It does not check DND. It does not enforce calling hours. It does not cap calls per recipient per day. There is no consent registry and no built-in opt-out mechanism on this channel.

Compliance with Indian telecom regulation — including the DND registries, registration and scrubbing obligations, and the rules on unsolicited commercial communication — is **the caller's responsibility, which means yours**. Build those checks into the system that decides whom to call, before it ever reaches the API. Verify the current requirements with your own legal counsel; they change, and this page is documentation, not legal advice.
:::

## Next

::: cards

::: card The API reference
[POST /calls](/api/calls) — parameters, responses, every error code, and the idempotency rules.
:::

::: card Trigger a call from your CRM
[The full recipe](/recipes/crm-call) — trigger, idempotency, webhook, and writing the outcome back.
:::

::: card How voice works
[Transcripts, recording, statuses and outcomes](/channels/voice) — identical for outbound and inbound.
:::

::: card Get a number to call from
[Numbers & KYC](/channels/phone-numbers) — the caller ID is also the agent selector.
:::

:::


----------------------------------------------------------------------------
## Install the widget
URL: https://docs.amomic.in/channels/web-chat
----------------------------------------------------------------------------

The web widget is one line of HTML. There is no package to install, no build step, no framework plugin, and nothing to keep up to date — the script is served from our side and updates itself.

```html title="Paste before </body>"
<script async src="https://services.amomic.in/widget.js" data-bot="wgt_01JQRS4T8XZ0AB1CD2EF3GH4"></script>
```

Replace the `data-bot` value with your own. You get it from the **Install** step of the web widget setup in the console — it always starts with `wgt_`.

```mock
{"component": "WidgetMock", "props": {"caption": "The widget on a customer's screen. Colours, greeting, launcher and position all come from your configuration — the tag never changes."}}
```

## Where it goes

Immediately before the closing `</body>` tag, on every page you want the widget to appear on. Usually that means your site's base template, footer partial, or layout component — somewhere it renders once per page rather than once per route.

Two details:

- **`async` matters.** It keeps the script off your page's critical path. The widget appears a moment after your content, which is the correct trade for a support widget.
- **Include it once.** A second copy of the tag on the same page is ignored rather than producing two launchers, but there is no reason to rely on that. If you have both a site-wide layout and a per-page include, pick one.

If `data-bot` is missing or empty, the script exits without doing anything — no launcher, no error in the console, nothing. A widget that silently fails to appear is worth checking for a typo'd or absent `data-bot` before anything else.

## Framework variants

Every platform takes the same tag. Two have their own idiom worth using instead.

::: codegroup

```html HTML
<!-- Anywhere before </body>: static sites, WordPress themes,
     Shopify, Wix, Squarespace, Webflow, Framer, Google Tag Manager,
     React (Vite/CRA), Vue, Angular, Svelte — all take this tag as-is. -->
<script async src="https://services.amomic.in/widget.js" data-bot="wgt_01JQRS4T8XZ0AB1CD2EF3GH4"></script>
```

```jsx Next.js
// app/layout.tsx — use next/script so Next controls when it loads.
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://services.amomic.in/widget.js"
          data-bot="wgt_01JQRS4T8XZ0AB1CD2EF3GH4"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}
```

```javascript Nuxt
// nuxt.config.ts — registered once, injected on every page.
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: "https://services.amomic.in/widget.js",
          async: true,
          "data-bot": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4",
        },
      ],
    },
  },
});
```

:::

`strategy="lazyOnload"` on the Next.js variant is doing the same job `async` does in plain HTML: it defers the widget until the page has settled. Do not use `beforeInteractive` — a support widget should never compete with your own page for the first paint.

In the console's **Install** step there is a platform picker with per-platform notes for WordPress, Shopify, Wix, Squarespace, Webflow, Framer, Google Tag Manager and the major frameworks. They all resolve to the same tag; the notes just tell you where that platform hides its footer.

## Allow your domains

Until you list the sites the widget may run on, it will run anywhere. Set this in the **Install** step, under **Allowed websites** — one domain per line, or comma-separated. Your bot's own website address is always allowed.

The matching rules are specific, and knowing them saves an afternoon:

**Hostnames only.** Enter `acme.com`, not `https://acme.com/support`. The scheme and the port are ignored, so `http` and `https` behave identically and a dev server on `:3000` matches the same host as production.

**`www.` does not matter.** It is stripped from both what you configured and what the browser sent. Listing `acme.com` covers `www.acme.com`, and listing `www.acme.com` covers `acme.com`.

**A domain matches itself and its subdomains.** `acme.com` allows `acme.com`, `www.acme.com`, `shop.acme.com`, and `help.eu.acme.com`. You do not need to list subdomains separately.

**There are no wildcards.** `*.acme.com` is not a pattern — it is a literal string that will never match a hostname, so it quietly allows nothing. Enter the parent domain instead and let the subdomain rule do the work.

**`localhost` is always allowed.** You never have to add it, and it works even on a fully locked-down bot.

::: warning `127.0.0.1` is not `localhost`
They are the same machine and different hostnames, and matching is on the hostname. `localhost:3000` works out of the box; `127.0.0.1:3000` is rejected by a bot that has any domains configured. Develop against `localhost` and this never comes up.
:::

::: danger An unconfigured bot answers on any website
A bot with no website address and no allowed domains accepts every origin. That is deliberate — it is what lets you paste the tag into a scratch page while you are still building — and it is wrong for production. Anyone who finds your `wgt_` id in your page source can embed your agent on their own site and spend your usage on their visitors.

Add your domains before you ship. It is one field, in the same step as the snippet.
:::

## The two 403s

A misconfigured install produces one of two messages. They mean different things and have different fixes.

| What you see | Why | Fix |
|---|---|---|
| *"This widget is not enabled for this website."* | The page's hostname is not in the allowlist. | Add the domain in **Allowed websites**. Check for a subdomain you forgot, a `*` you typed, or `127.0.0.1`. |
| *"This chatbot isn't live yet."* | The origin is allowed, but the bot is still a draft. | Set the bot live — **Set live** in the Install step. |

The second one catches people who tested successfully in the console preview and then found nothing worked on their own site. The preview is not subject to the live check, on purpose, so you can build against a draft. Your website is.

Both are refusals to answer, not crashes. The launcher still renders.

## Opening and closing it from your own UI

The widget exposes exactly two methods on the page:

```javascript
window.AmomicWidget.open();
window.AmomicWidget.close();
```

Use them to wire your own triggers — a "Chat with us" link in the header, a help button on a pricing page, an offer to chat after a form fails validation.

```html
<button type="button" onclick="window.AmomicWidget.open()">
  Chat with us
</button>
```

```javascript title="Offer help when someone struggles with checkout"
let failedAttempts = 0;

paymentForm.addEventListener("invalid-submission", () => {
  failedAttempts += 1;
  if (failedAttempts === 2) {
    window.AmomicWidget.open();
  }
});
```

`window.AmomicWidget` is defined once the script has loaded. Because the tag is `async`, code that runs during initial page parse may execute before that. Guard it:

```javascript
function openChat() {
  if (window.AmomicWidget) {
    window.AmomicWidget.open();
  }
}
```

There is nothing else on the object. No event listeners, no message injection, no way to prefill the composer or start a conversation programmatically — `open()` and `close()` are the whole surface.

## What the visitor's browser stores

No cookies. The widget keeps a small amount of state in the visitor's `localStorage`: an anonymous visitor id, the current conversation id for this bot, and whether the [lead form](/channels/web-chat-leads) has already been dealt with.

Consequences worth knowing before someone asks:

- **Returning visitors keep their conversation.** Close the tab, come back tomorrow, and the thread is still there.
- **Clearing site data resets them completely.** New visitor, new conversation, and the lead form is asked again.
- **The visitor id is shared across bots on the same page**, but conversations are not — each bot keeps its own.
- **Private browsing behaves like a new visitor every time.** That is expected, not a bug.

The widget also renders inside an isolated shadow root, so your site's CSS cannot leak into it and its styles cannot leak into your page. If the widget looks wrong, it is a configuration problem rather than a CSS collision — see [Customise the widget](/channels/web-chat-config).

## Rate limit

**12 requests per 60 seconds, per visitor, per widget.** It applies to sending a message, sending an image, and submitting the lead form. Loading the widget and its configuration is not counted.

Over the limit, the visitor sees:

> You're sending messages too quickly — give it a moment.

There is no `Retry-After` header and nothing for you to configure. The window slides, so waiting a few seconds is enough.

Real people do not hit this. A visitor sending twelve messages in a minute is either testing, pasting, or automating. If your own testing keeps tripping it, clear the site data to get a new visitor id, or wait out the window.

## Troubleshooting

::: details The widget does not appear at all
Work through it in order:

1. **Is the script in the page?** View source on the live page — not your template file. Content management systems and tag managers strip or defer script tags in surprising ways.
2. **Is `data-bot` present and correct?** No id means the script exits silently. Copy it again from the Install step.
3. **Any network error on `widget.js`?** An aggressive content security policy or an ad blocker can stop it loading. Check the browser console.
4. **Is it behind something?** The launcher sits in a fixed corner. A cookie banner or a floating cart button in the same corner can cover it — move the widget to the other side in the appearance settings.
:::

::: details It works on localhost but not on the live site
The classic allowlist symptom. `localhost` is always allowed; your production hostname is not until you add it. Add the parent domain, not a wildcard.
:::

::: details It works on the main domain but not on a subdomain
It should — a listed domain covers its subdomains. Check that what you listed is the parent (`acme.com`) rather than a sibling (`www.acme.com` is fine, `shop.acme.com` alone is not enough for `help.acme.com`).
:::

::: details It worked in the console preview but not on my site
The preview bypasses the live-status check so you can build against a draft. Your site does not. Set the bot live.
:::

::: details Two launchers appeared
The tag is being included twice by two different templates. Remove one. A duplicate tag is normally ignored, so if you genuinely see two launchers you probably have two different bot ids on the page.
:::

::: details The chat is empty when a visitor returns
Their browser cleared site data, or they are in a private window. Conversation continuity lives entirely in the visitor's own storage.
:::

## Next

::: cards

::: card Make it yours
[Appearance, greeting, position and image upload](/channels/web-chat-config) — everything configurable from the console.
:::

::: card Capture leads
[Turn visitors into contacts](/channels/web-chat-leads) the agent can follow up with on WhatsApp.
:::

::: card Read the conversations
[Conversations & contacts](/concepts/conversations) — where widget chats land and how they thread.
:::

::: card Build the agent behind it
[Agents & versions](/build/agents) — the widget is a surface; the agent is the product.
:::

:::


----------------------------------------------------------------------------
## Customise the widget
URL: https://docs.amomic.in/channels/web-chat-config
----------------------------------------------------------------------------

Everything visual about the widget is set in the console and read by the script at load time. You never edit the snippet — [the tag](/channels/web-chat) stays exactly as it was pasted, and a colour change is live on the next page load.

Configuration lives in the web widget setup, split across two steps: **Identity** for what the widget says, **Appearance** for how it looks. A live preview sits next to both, running your actual bot against your actual knowledge base.

## Identity

| Setting | Notes |
|---|---|
| **Bot name** | Up to 60 characters. Shown in the chat header and used when the agent refers to itself. |
| **Company name** | Up to 120 characters. Used in the header and in what the agent says about who it works for. |
| **Welcome message** | Up to 500 characters. The first thing a visitor sees when the chat opens, before they type anything. |
| **Suggested questions** | Tappable chips shown before the first message. The console offers three; **the widget renders at most four**. |
| **Profile picture** | Shown in the chat header. Upload your own or keep the default. |

The welcome message is not a greeting to admire — it is the highest-traffic sentence in the whole product, and it should do a job. "Hi! How can I help you today?" is the default and it is fine. "Ask me about delivery times, returns, or your order status" is better, because it tells the visitor what this thing is actually good at and prevents the question it cannot answer.

Suggested questions do the same work more directly. Use them for the three questions your support team answers most, phrased the way a customer would phrase them.

## Appearance

| Setting | Values |
|---|---|
| **Brand colour** | A six-digit hex value, for example `#6E56CF`. The text colour on top of it is chosen automatically for contrast — you do not set it, and you cannot make it unreadable. |
| **Font** | A font name. Non-system fonts are loaded for you; leave it as `Inter` if you have no strong preference. |
| **Theme** | `Auto`, `Light`, or `Dark`. `Auto` follows the visitor's own system setting. |
| **Position** | `Bottom right` or `Bottom left`. |
| **Launcher button** | The floating button that opens the chat: `Chat`, `Spark`, `Bolt`, `Wave`, `Help`, or a custom image you upload. Its colour can differ from the brand colour. |

The brand colour input validates strictly: six hex digits with a leading `#`. Anything else is rejected with *"Brand color must be a hex value like #6E56CF."* Three-digit shorthand and named colours are not accepted.

::: tip Auto is the right theme unless you know better
`Auto` matches the visitor's system preference, which means the widget looks intentional on a dark-mode laptop at midnight and on a bright screen at noon. Pinning `Light` on a site that already respects dark mode is the combination people notice.
:::

**Custom images** — a launcher icon or a profile picture — accept PNG, JPG, JPEG, WEBP, SVG or GIF, up to 2 MB. Only an owner or admin can upload them.

If your bot was set up by reading your website, the colours and font are prefilled from what was found there. The console flags it: *"Matched from your website — tweak anything below."* Treat it as a starting point.

## The lead form

Whether the widget asks for a name, email or phone number — and when it asks — is configured in the same **Appearance** step, under **Ask for contact details**.

It has enough behaviour of its own to deserve a page: see [Capture leads](/channels/web-chat-leads).

## Image upload

When it is enabled, visitors can attach a photo to a message. This is the difference between "my item arrived damaged" and a picture of the damage.

| | |
|---|---|
| **Formats** | JPEG, PNG, WEBP, GIF |
| **Maximum size** | 5 MB |
| **Availability** | Paid plans |

The agent looks at the image and answers what it shows. If there is text alongside it, that text is the question and the image is the context — "is this the right cable for the model I bought?" with a photo attached is a single question, not two. An image sent on its own is answered on its own terms.

There is no separate step, no analysis job, and nothing for a visitor to wait for beyond the normal reply.

Errors a visitor can see:

| Message | Cause |
|---|---|
| *"Please upload a JPG, PNG, WEBP or GIF image."* | Any other file type, including PDFs and HEIC photos from an iPhone with the default camera format. |
| *"Image is too large (max 5 MB)."* | Over the size limit. |
| *"The image is empty."* | A zero-byte file. |
| *"Image upload isn't available on this plan."* | The workspace is on the free plan, or billing is suspended. |

::: note HEIC is the common surprise
An iPhone photographing something in its default format produces HEIC, which is rejected. Most sharing paths convert it to JPEG automatically, but a file picked directly from Files may not be. There is nothing to configure — it is worth knowing when a visitor says "it won't let me send the photo".
:::

## The attribution is not removable

The widget shows **Powered by Amomic-AI**. There is no setting to hide it, no plan that removes it, and no white-label option. If your requirement is an unbranded widget, this is not currently the product for that, and no amount of configuration will get you there.

## What is fixed

Not everything is a setting, and knowing which parts are not saves you looking:

- **Panel size and layout.** The chat panel has a fixed size that expands on larger screens and goes full-screen on narrow ones. The launcher is a fixed size in a fixed corner offset — you choose the side, not the coordinates.
- **The composer placeholder** reads `Ask anything…`.
- **The suggested-questions label** reads `Quick questions`.
- **The header subtitle** falls back to `Online` when there is nothing else to show.
- **Custom CSS.** There is none. The widget renders in an isolated shadow root specifically so your site's styles cannot reach it — which also means you cannot restyle it beyond the settings above.

## What the agent can render

The widget supports a deliberately small subset of markdown, so an agent's answer stays readable in a narrow panel:

`**bold**`, `*italic*`, `` `code` ``, links, images, and simple `-` or `*` bullet lists.

Tables, headings, code fences and blockquotes are not rendered. If your agent's answers keep coming out as literal markdown symbols, it is emitting something outside that list — adjust its instructions to answer in short prose and bullets. It is a chat panel; a five-column table would not fit anyway.

## Next

::: cards

::: card Install it
[The one-line tag](/channels/web-chat), the domain allowlist, and `window.AmomicWidget`.
:::

::: card Capture leads
[Name, email and phone](/channels/web-chat-leads) — the form, the validation, and what happens to a submission.
:::

::: card Plans
[What each plan includes](/operate/limits), including image upload.
:::

:::


----------------------------------------------------------------------------
## Capture leads
URL: https://docs.amomic.in/channels/web-chat-leads
----------------------------------------------------------------------------

A visitor asks a good question at 11 p.m., gets an answer, and leaves. Without a contact detail that conversation is over the moment the tab closes. With one, it is a contact your team can reach — and an agent that can follow up on WhatsApp instead of hoping they come back.

The lead form is a short panel inside the widget that asks for some combination of name, email and phone. It is off by default. Turn it on in the web widget setup, under **Ask for contact details** in the Appearance step.

## When it appears

Two timings, and the choice matters more than it looks.

| Timing | Console label | Trade-off |
|---|---|---|
| `before_chat` | `Before the chat` | *"Every visitor is identified, but some will leave rather than fill it in."* |
| `after_first_reply` | `After the first reply` | *"The assistant answers once first, so the ask lands with someone already engaged."* |

`before_chat` maximises capture rate per conversation and reduces the number of conversations. `after_first_reply` does the opposite: fewer forms shown, higher completion, and every lead has already seen the agent do something useful.

For support widgets, `after_first_reply` is almost always right — asking for an email before answering "where is my order" reads as a toll gate. For a sales enquiry form where every visitor is a potential deal, `before_chat` earns its friction.

::: note It is asked once per visitor, not once per conversation
A visitor who fills the form in — or dismisses it — is not asked again on their next visit from the same browser. The record lives in their own browser storage, so clearing site data resets it. Nobody gets nagged; nobody is asked twice in one session.
:::

## What you can ask for

Three fields. Each one can be shown or hidden, and each shown field can be optional or required.

| Field | Default |
|---|---|
| **Name** | Shown, required |
| **Email** | Shown, required |
| **Phone** | Shown, optional |

At least one field must be enabled. Turn all three off and the form is refused with *"Pick at least one detail to collect, or turn the form off."*

A field you disable is not collected, even if something submits it anyway — it is dropped server-side, not just hidden.

Three pieces of copy frame the ask:

| Setting | Limit | Default |
|---|---|---|
| **Headline** | 80 characters | `Before we start` |
| **Supporting text** | 240 characters | `Tell us how to reach you and we'll pick up right where you left off.` |
| **Consent line** | 300 characters | Empty |

The consent line is optional and renders with a checkbox the visitor must tick. Use it when your privacy notice requires an explicit act of agreement — *"I agree to be contacted about my enquiry."* — rather than an inferred one. If you leave it empty, no checkbox is shown and no consent is recorded.

::: tip Ask for less than you want
Every field is a reason to close the tab. Phone plus name beats phone plus name plus email plus company plus role, and a phone number is worth more than the rest combined because it is the one channel your agent can follow up on by itself.
:::

## What happens to a submission

Three things, in this order:

**A contact is created or matched.** The submission resolves against your CRM contacts: an existing contact if one matches, a new one if not. Either way you end up with a contact record you can see in **Contacts** and reach from anywhere else in the product.

**The conversation is stamped with the customer.** The chat that was anonymous ten seconds ago now carries a name, email and phone. Anyone opening it in the inbox sees who they are reading, and the agent has the same information for the rest of the conversation.

**A `lead.created` event fires.** If you have a webhook endpoint subscribed, your systems are told immediately — with the contact id, name, email and phone. That is the hook for pushing the lead into your own CRM, starting a nurture sequence, or paging a salesperson while the visitor is still on the page. See [Event reference](/webhooks/events).

::: note The lead is kept even if the contact is not
If contact resolution fails — a transient problem on the CRM side — the submission is still recorded and the visitor still sees a success. You do not lose a lead because a downstream write had a bad second. The trade is that the lead may not have a contact id attached, so treat `contact_id` in the webhook payload as something that can be absent.
:::

## Validation

The form validates on submit, and the messages a visitor sees are these exactly.

| Message | Cause |
|---|---|
| *"Please fill in every required field."* | A field marked required was left empty. The response names which ones. |
| *"Please share at least one contact detail."* | Every field was left empty. |
| *"That email address doesn't look right."* | The email failed the format check. |
| *"That phone number doesn't look right."* | The phone number could not be normalised into a usable international number. |
| *"This widget is not collecting contact details."* | Lead capture is switched off for this widget. A visitor should never see this; it means something is submitting to a form that is not enabled. |

Submitting the form counts against the widget's [rate limit](/channels/web-chat#rate-limit) of 12 requests per 60 seconds per visitor, like sending a message does.

### Email

The check is a format check, not a delivery check: some text, an `@`, a domain with a dot, and a plausible ending. `asha@example.com` passes. `asha@example` fails. `asha at example.com` fails.

Nothing verifies that the mailbox exists. `nobody@example.com` is a perfectly valid-looking address and will be accepted. If your process depends on the address being real, send something to it and see.

### Phone numbers

Phone input from real people is a mess — spaces, dashes, brackets, a leading zero out of habit, sometimes a country code and sometimes not. All of it is normalised into a single international form before it is stored.

The steps, in order:

1. **Everything that is not a digit is removed.** Spaces, dashes, brackets, dots and the `+` all disappear.
2. **Leading zeros are stripped.** The trunk prefix people type out of habit is not part of an international number.
3. **A bare 10-digit number gets `91` in front of it.** India is the assumed country.
4. **The result must be 10 to 15 digits.** Anything shorter or longer is rejected.
5. **The stored value is `+` followed by those digits.** Always. There is no other format on the way out.

Worked examples:

| Visitor typed | Stored as | Why |
|---|---|---|
| `9876543210` | `+919876543210` | Ten digits, so `91` is added. |
| `098765 43210` | `+919876543210` | Non-digits removed, leading zero stripped, ten digits left, `91` added. |
| `+91 98765 43210` | `+919876543210` | Twelve digits after cleaning — already has a country code, nothing added. |
| `(022) 6985 0800` | `+912269850800` | Punctuation removed, leading zero stripped, ten digits left, `91` added. |
| `+1 415 555 2671` | `+14155552671` | Eleven digits after cleaning, so it is left as it is. |
| `12345` | rejected | Too short. *"That phone number doesn't look right."* |

::: warning Ten digits always means India
Step 3 does not inspect the number to decide whether it looks Indian — any bare ten-digit input gets `+91`. A visitor in the United States typing `4155552671` without a country code is stored as `+914155552671`, which is not their number and never will be.

If you sell outside India, say so in the field: a supporting line asking for the country code, or a phone label that reads *"Include your country code"*, is the whole fix. There is no per-workspace default country to change.
:::

## Duplicate submissions

The same person, twice, is one contact.

A second submission carrying a phone number that already belongs to a contact resolves to **that existing contact** rather than creating a new one — even when the other details differ. Someone who submitted `asha@gmail.com` in March and `asha@acme.com` in August, with the same phone number both times, is one person in your CRM with an updated email, not two half-populated records.

The practical instruction for your own systems: **treat `contact_id` from the `lead.created` event as the identity, not the email address.** Two events can legitimately carry different emails and the same contact.

## Why the phone number is the valuable field

A captured phone number is what lets an agent continue the conversation on WhatsApp.

The chain is short: the lead becomes the conversation's customer, the customer carries a phone number, and an agent that has a phone number can send a WhatsApp message to it. A visitor who asks about delivery to Pune at midnight and leaves can get an answer on WhatsApp when the warehouse confirms in the morning — on a channel they will actually see, rather than an email they will not.

Two things to keep in mind before you build on it:

- **The [24-hour window](/channels/whatsapp-window) still applies.** Capturing a number does not open a WhatsApp session. Outside an open window you need an approved template, not free text.
- **A number in your CRM is not consent to message it.** The visitor gave you a way to reach them about *their enquiry*. Use the consent line if you need a recorded basis for anything broader, and honour opt-outs — they are enforced across every number in your workspace.

## Troubleshooting

::: details The form never appears
Check three things: lead capture is enabled on the deployment that is actually live, at least one field is enabled, and the visitor has not already answered it. Their browser remembers a previous submission or dismissal — clear site data to test again.
:::

::: details A visitor says their phone number was rejected
It cleaned down to fewer than 10 or more than 15 digits. Usually an extension typed on the end, a partially entered number, or a country code entered twice.
:::

::: details Leads arrive without a contact in the CRM
Contact resolution failed for that submission and the lead was kept anyway. The webhook payload will have no contact id. If it happens consistently rather than occasionally, something is wrong beyond one bad write — raise it with support.
:::

::: details Two leads created one contact, or one lead updated an existing contact
Working as designed. Phone number is the identity. See [duplicate submissions](#duplicate-submissions).
:::

::: details An international number came out with +91
Ten bare digits are assumed Indian. Ask visitors for a country code in the field copy.
:::

## Next

::: cards

::: card Install the widget
[The one-line tag](/channels/web-chat) and the domain allowlist that keeps it on your own site.
:::

::: card Customise it
[Appearance, greeting and image upload](/channels/web-chat-config) — the form lives in the same setup step.
:::

::: card Follow up on WhatsApp
[Set up WhatsApp](/channels/whatsapp) so a captured number becomes a conversation the customer will actually read.
:::

::: card Get the event
[`lead.created`](/webhooks/events) — push every capture straight into your own systems.
:::

:::


============================================================================
# SECTION: API reference
============================================================================



----------------------------------------------------------------------------
## API overview
URL: https://docs.amomic.in/api/overview
----------------------------------------------------------------------------

The Amomic-AI API lets your own systems do the four things your team does in the console: send a message, place an AI call, read a conversation, and open a ticket. It is a small, deliberately flat REST surface — fourteen routes, no nesting deeper than one level, one error envelope, one auth mechanism.

If you have not made a request yet, start with [Your first API call](/start/first-api-call). This page is the map you come back to.

## Base URL

```endpoint
https://services.amomic.in/api/v1
```

Every path on this page is relative to that. There is no other host, no `/api/v2`, no `Accept-Version` header, and no content negotiation — see [API versioning](/operate/versioning) for how changes are handled instead.

Your key carries an environment. A live key (`amk_live_…`) is the one that works against this host. A test key used here fails with `401` and `details.reason` of `wrong_environment` — a distinct, loud error rather than a silent no-op. [Authentication](/api/authentication) covers the split.

## What the API is for

The API is the *operational* surface. It drives agents you have already built:

- **Send** a WhatsApp message — free-form text inside the 24-hour window, or an approved template outside it.
- **Call** a number and have an agent hold the conversation, then read the outcome.
- **Read** conversations and their transcripts, whichever channel they happened on.
- **Open** a support ticket from your own system and read it back.
- **Upsert** a contact so a person your CRM knows about is the same person our inbox knows about.

It is not the agent-building surface. Agents, versions, knowledge bases, tools, deployments, phone numbers, and templates are configured in the console and have no public REST equivalent. That boundary is intentional: the things you change once a quarter live where humans can review them, and the things you call ten thousand times a day live here.

```mock
{"component": "PlatformDiagram", "props": {"caption": "Your backend calls /api/v1; events come back to you over webhooks. Everything an agent is made of is configured in the console."}}
```

## Server-side only

`/api/v1` sends **no CORS headers at all**. Not a restrictive `Access-Control-Allow-Origin` — none. Preflight requests are not answered. A browser cannot successfully call this API, and that is the design, not a gap.

The reason is the key itself. API keys are workspace-wide and carry every scope you granted them; there is no per-user, per-agent, or per-origin key. A key placed in front-end JavaScript is readable by anyone who opens your bundle, and the blast radius of that leak is your entire workspace. Removing CORS removes the temptation.

::: warning If you need something in the page
Use the [web chat widget](/channels/web-chat). It is built for in-page use and has its own origin-scoped auth — no API key involved.
:::

## The shape of every request

Four things make up a request. Only the first is always required.

```params
[
  {"name": "Authorization", "type": "header", "required": true, "description": "<code>Bearer amk_live_…</code>. Alternatively send <code>X-Api-Key: amk_live_…</code> — either is accepted, and <code>X-Api-Key</code> wins if you send both."},
  {"name": "Content-Type", "type": "header", "required": false, "description": "<code>application/json</code> on every request with a body. All four POST endpoints take JSON; none take form encoding or multipart."},
  {"name": "Idempotency-Key", "type": "header", "required": false, "description": "Honoured on <code>POST /messages</code>, <code>POST /calls</code>, and <code>POST /tickets</code>. Makes a retry safe. See <a href=\"/api/idempotency\">Idempotency</a>."},
  {"name": "X-Correlation-Id", "type": "header", "required": false, "description": "Your own trace id. Echoed back on the response and stored in your workspace request log, so one id joins your logs to ours. Generated for you if you omit it."}
]
```

A minimal request looks like this:

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-shipped" \
  -H "X-Correlation-Id: trace-9f2c1d" \
  -d '{"to": "+919876543210", "text": "Your order AM-4821 has shipped."}'
```

```javascript Node.js
const response = await fetch("https://services.amomic.in/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-shipped`,
    "X-Correlation-Id": traceId,
  },
  body: JSON.stringify({
    to: order.customerPhone,
    text: `Your order ${order.reference} has shipped.`,
  }),
});
```

```python Python
import os, httpx

response = httpx.post(
    "https://services.amomic.in/api/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
        "Idempotency-Key": f"order-{order.id}-shipped",
        "X-Correlation-Id": trace_id,
    },
    json={"to": order.customer_phone, "text": f"Your order {order.reference} has shipped."},
)
```

:::

### What comes back

| Header | When | Meaning |
|---|---|---|
| `X-Correlation-Id` | every response | Your `X-Correlation-Id` echoed, or one we generated. |
| `X-RateLimit-Limit` | successful responses only | Requests allowed per minute for this key. |
| `X-RateLimit-Remaining` | successful responses only | Requests left in the current minute. |

There is no `X-Request-Id` response header. The request id appears inside error envelopes as `error.request_id`, and nowhere else. There is no `Retry-After` and no `X-RateLimit-Reset` — [Rate limits](/api/rate-limits) explains how to back off without them.

Successful responses are `200`, except the four creates, which are `201`.

Every non-2xx response uses one envelope:

```json title="403 Forbidden"
{
  "error": {
    "code": "permission_denied",
    "message": "This API key does not have the `messages:send` scope.",
    "details": { "reason": "missing_scope", "required_scope": "messages:send" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Nine `code` values exist and no others can. [Errors](/api/errors) has the full map and the complete `details.reason` catalogue.

## Ids

Every id we mint is a prefix, an underscore, and a body. The prefix tells you what you are holding even when it is out of context in a log line.

| Prefix | What it identifies | Where you see it |
|---|---|---|
| `con_` | A conversation | `conversation_id` |
| `msg_` | A chat message | `message_id` on transcript rows |
| `call_` | A call | `call_id` |
| `tkt_` | A ticket | `ticket_id` |
| `AM-XXXXXXXX` | A ticket's human reference | `public_ref` — the one you quote to a customer |
| `req_` | One API request | `error.request_id` |
| `cor_` | One trace | `error.correlation_id`, `X-Correlation-Id` |
| `evt_` | One webhook delivery | The webhook envelope `id` and `Amomic-Event-Id` |
| `amk_` | An API key token | Shown once, at creation |
| `whsec_` | A webhook signing secret | Shown once, at endpoint creation |
| `wamid.` | A WhatsApp message | `message_id` from `POST /messages` — WhatsApp's format, not ours |

Most of these bodies are ULIDs: 26 characters of Crockford base32, time-ordered, so sorting the strings sorts by creation time. That property is load-bearing — the message cursor in [Pagination](/api/pagination) is just a `message_id`.

Treat every id as an opaque string. Do not parse the body, and do not assume a length: `tkt_` and `evt_` ids are hex, not ULIDs, and `wamid.` belongs to WhatsApp.

## Timestamps

Two shapes exist, and confusing them is a real source of bugs.

| Where | Shape | Example |
|---|---|---|
| Every REST resource on `/api/v1` | ISO 8601 with microseconds and a numeric UTC offset | `2026-08-01T10:00:00.123456+00:00` |
| The webhook envelope's `created_at` | ISO 8601 to the second with a literal `Z` | `2026-08-01T10:00:00Z` |

Both are UTC. Both parse with any conforming ISO 8601 parser — but a hand-rolled regex or a `strptime` format string written against one will fail on the other.

Every timestamp field is nullable. A value that cannot be formatted comes back as `null` rather than raising, so `created_at: null` means "not recorded", not "epoch".

## The route table

Fourteen routes, and that is the entire public surface. Thirteen sit behind an API key; the OpenAPI document needs nothing.

| Method | Path | Scope | Idempotent | Success |
|---|---|---|---|---|
| GET | `/openapi.json` | none — unauthenticated | – | 200 |
| GET | `/ping` | any valid key | – | 200 |
| GET | `/channels` | any valid key | – | 200 |
| POST | `/messages` | `messages:send` | yes | 201 |
| POST | `/calls` | `calls:write` | yes | 201 |
| GET | `/calls/{call_id}` | `calls:write` | – | 200 |
| POST | `/calls/{call_id}/hangup` | `calls:write` | – | 200 |
| GET | `/conversations` | `conversations:read` | – | 200 |
| GET | `/conversations/{conversation_id}` | `conversations:read` | – | 200 |
| GET | `/conversations/{conversation_id}/messages` | `conversations:read` | – | 200 |
| GET | `/agents` | `agents:read` | – | 200 |
| POST | `/contacts` | `contacts:write` | no | 201 |
| POST | `/tickets` | `tickets:write` | yes | 201 |
| GET | `/tickets/{ticket_id}` | `tickets:write` | – | 200 |

Two rows deserve a second look:

- **`GET /tickets/{ticket_id}` requires `tickets:write`.** There is no `tickets:read` scope. Granting a key the ability to read a ticket necessarily grants it the ability to open one. [Scopes](/api/scopes) explains the reasoning and what to do about it.
- **`POST /contacts` does not honour `Idempotency-Key`.** It is naturally convergent — it matches on email then phone and updates in place — so a retry resolves to the same contact. It is the one POST where the header is ignored.

### The machine-readable version

```endpoint
GET /api/v1/openapi.json
```

An OpenAPI 3.1 document describing exactly these routes, fetchable with no key at all. Feed it to a client generator, or hand it to a coding agent alongside [these docs](/agents-setup).

## What this API deliberately does not do

This is scope, not a roadmap. Building against an assumption in this list will not work today and is not waiting on a release.

- **It is not callable from a browser.** No CORS headers, no preflight. Use the [widget](/channels/web-chat) for in-page work.
- **There is no bulk or batch send.** `POST /messages` sends one message to one number. A campaign is your loop plus your own pacing, inside the [rate limit](/api/rate-limits).
- **There is no scheduling.** No `send_at`, no delay parameter. Hold the message until you want it sent.
- **There is no media upload on messages.** `POST /messages` accepts text and approved templates. There is no attachment field and no upload endpoint to put a file behind one.
- **There are no SDKs.** No official client library in any language. The API is plain HTTP and JSON on purpose — `fetch` and `httpx` are the whole dependency list, and `GET /openapi.json` generates a client if you want one.
- **There is no key or webhook management API.** Keys and webhook endpoints are created, rolled, and revoked in the console by an admin. There is no public route that mints a credential.
- **There is no read side for messages or contacts.** No `GET /messages`, no message list, no `GET /contacts/{id}`. Read message history through [conversations](/api/conversations).
- **Nothing can be updated or deleted.** No `PATCH`, no `PUT`, no `DELETE` anywhere on `/api/v1`. Tickets cannot be commented on or closed through the API.
- **There is no sandbox mode.** The only split is `live` versus `test`, and it follows the environment a key was issued in. You cannot obtain a test key that works against production.

## Next

::: cards

::: card Authentication
[How keys work](/api/authentication) — the format, the one-time reveal, rolling, and the six distinct causes of a 401.
:::

::: card Scopes
[What a key can do](/api/scopes) — six scopes, the read-only default, and the endpoint matrix.
:::

::: card Errors
[One envelope, nine codes](/api/errors) — and the full `details.reason` catalogue for branching on.
:::

::: card Send something
[POST /messages](/api/messages) — the endpoint most integrations exist for.
:::

:::


----------------------------------------------------------------------------
## Authentication
URL: https://docs.amomic.in/api/authentication
----------------------------------------------------------------------------

Every call to `/api/v1` except the OpenAPI document carries an API key. There is one credential type, one place to get it, and — importantly — six different reasons a `401` comes back. Reading `details.reason` before you start debugging saves most of the time people lose here.

## Sending the key

Two header forms are accepted. Use whichever your HTTP client makes cleaner.

::: codegroup

```bash Authorization
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer amk_live_7Fk2xQ..."
```

```bash X-Api-Key
curl https://services.amomic.in/api/v1/ping \
  -H "X-Api-Key: amk_live_7Fk2xQ..."
```

:::

They are equivalent. If you send both, **`X-Api-Key` wins** — it is checked first and the `Authorization` header is never read. That matters when a proxy or gateway in front of your service injects its own `Authorization` header: put your key in `X-Api-Key` and it will not be shadowed.

The `Bearer ` prefix is matched case-insensitively and the token is trimmed, so `bearer amk_live_…` and a stray trailing space both work. Anything else in the `Authorization` header is treated as no key at all.

Send neither and you get:

```json title="401 Unauthorized"
{
  "error": {
    "code": "unauthenticated",
    "message": "Provide your API key as `Authorization: Bearer amk_…` or `X-Api-Key`.",
    "details": { "reason": "missing_api_key" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Every `401` also carries a `WWW-Authenticate: Bearer` response header, so standards-aware HTTP clients recognise it as an authentication challenge rather than a generic failure.

## Key format

```
amk_live_7Fk2xQ9pLm4RtY8vN3wZ0aB6cD1eF5gH7iJ2kL4mN6o
│   │    └─ secret: 32 random bytes, base64url, padding stripped — 43 characters
│   └────── environment: exactly "live" or "test"
└────────── product prefix: always "amk"
```

Each part earns its place:

- **`amk`** is a constant so that secret scanners — GitHub's, your own pre-commit hook, your log scrubber — can find a leaked Amomic-AI key by pattern. A key that looks like generic base64 is a key nobody notices in a diff.
- **`live` / `test`** makes the environment visible at a glance, in a log line, in a `.env` file, in a screenshot on a support call. It is also enforced server-side; see [environments](#environments-test-versus-live) below.
- **The secret** is 256 bits from a cryptographic RNG. Nothing about it is derived from your workspace, your email, or the time it was created.

A token that is not exactly three underscore-separated parts, whose second part is not `live` or `test`, or whose secret is shorter than 20 characters is rejected as malformed **before any lookup happens**. A truncated key pasted from a terminal fails instantly with `malformed_api_key`, not with a vague "invalid".

## We store a hash, not your key

When a key is created, the raw token is generated, returned to you, and then discarded. What is stored is a SHA-256 hash of the secret plus a six-character display hint for the masked form you see in the console (`amk_live_7Fk2xQ…`).

::: danger The secret is shown exactly once
There is no second look. Support cannot retrieve it. An engineer with database access cannot retrieve it — the value is not there. Put the key in your secret manager before you close the creation dialog.

Lost it? Do not create a second key and leave the first one live. **Roll** it: you get a new secret and the old one keeps working for 24 hours, so you can deploy without a gap. See [Rolling a key](#rolling-a-key-without-downtime).
:::

SHA-256 rather than bcrypt or Argon2 is a deliberate choice, and the reasoning is worth understanding because it is the opposite of the right answer for passwords. Password hashing is slow on purpose because human passwords are guessable and an attacker with the hash file can grind them. An API key secret is 256 bits from a CSPRNG — there is nothing to grind. Brute force is not the threat model, so the design optimises for what is: verification is a single fast lookup, which is what lets a revoked key stop working in seconds instead of minutes.

```mock
{"component": "ApiKeysScreen", "props": {"caption": "Keys after creation: name, environment, scopes, and a masked prefix. The full secret is never shown again."}}
```

## Environments: test versus live

There is one production API. The `live` / `test` distinction is not a mode you toggle per request — it is baked into the key at creation and checked against the host it is used on.

- A key issued in production is a **live** key. It works against `services.amomic.in`. Real messages leave the building, real calls are dialled, real money is spent.
- A key issued in a non-production environment is a **test** key, and it only works there.

Cross them and you get a `401` that names the problem exactly:

```json title="401 Unauthorized"
{
  "error": {
    "code": "unauthenticated",
    "message": "That is a test key; this environment expects a live key.",
    "details": { "reason": "wrong_environment" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

::: note wrong_environment is not a bad secret
This is the single most misread error on the API. `wrong_environment` means the key is genuine, unrevoked, and correctly formatted — it is simply the wrong side of the environment boundary. Nobody needs to re-issue anything. Your staging deployment is pointed at the production host, or your production deployment picked up the staging secret. Check which `AMOMIC_API_KEY` your process actually loaded before you touch the console.
:::

Note it is a `401`, not a `403`. The key is not recognised *as a credential here*, which is an authentication outcome, not a permission one.

## The validation order

Checks run in a fixed order, and each one produces a different error. Knowing the order tells you what has already been proven true by the time you see a given failure.

::: steps

::: step Is a key present?
Neither header set, or an `Authorization` header that is not a bearer token.
→ `401` `unauthenticated`, `reason: missing_api_key`
:::

::: step Does it parse?
Three parts, `amk` first, `live` or `test` second, a secret of at least 20 characters. **No datastore lookup happens at this stage** — a malformed token never touches storage.
→ `401` `unauthenticated`, `reason: malformed_api_key`, message `"That doesn't look like an Amomic-AI API key."`
:::

::: step Does the secret match a real key?
The record is looked up and the hash compared.
→ `401` `unauthenticated`, `reason: invalid_api_key`, message `"That API key is not valid."`
:::

::: step Has it been revoked?
→ `401` `unauthenticated`, `reason: revoked_api_key`, message `"That API key has been revoked."`
:::

::: step Has it expired?
Only rolled keys expire, when their 24-hour grace window closes.
→ `401` `unauthenticated`, `reason: expired_api_key`, message `"That API key was rolled and its grace period has ended."`
:::

::: step Is it the right environment?
→ `401` `unauthenticated`, `reason: wrong_environment`
:::

::: step Is the key within its rate limit?
→ `429` `rate_limited`. See [Rate limits](/api/rate-limits).
:::

::: step Does it have the scope this route needs?
→ `403` `permission_denied`, `reason: missing_scope`. See [Scopes](/api/scopes).
:::

:::

Read that backwards when you are debugging. A `403` proves your key is valid, unrevoked, in the right environment, and under its rate limit — the only thing wrong is what it is allowed to do. A `429` proves everything except the scope check. And an `invalid_api_key` proves the token was well-formed, which usually means you are holding a *real* key from another workspace or another environment's database, not a typo.

### The six causes of a 401

| `details.reason` | Message | What it actually means |
|---|---|---|
| `missing_api_key` | Provide your API key as `Authorization: Bearer amk_…` or `X-Api-Key`. | No header reached us. Check for a proxy stripping `Authorization`. |
| `malformed_api_key` | That doesn't look like an Amomic-AI API key. | Truncated paste, wrapped line, quotes included, or a placeholder that was never substituted. |
| `invalid_api_key` | That API key is not valid. | Well-formed but unknown. Usually a key from a different workspace, or one character altered. |
| `revoked_api_key` | That API key has been revoked. | Someone revoked it in the console. Permanent — mint a new key. |
| `expired_api_key` | That API key was rolled and its grace period has ended. | The old half of a roll, more than 24 hours later. Deploy the new secret. |
| `wrong_environment` | That is a `<env>` key; this environment expects a `<env>` key. | Right key, wrong host. Not a credential problem. |

All six are `code: "unauthenticated"` and HTTP `401`. Branch on `details.reason`, never on the message text — messages are written for humans and may be reworded.

## The five-second verification cache

A verified key record is cached in-process for **5 seconds**. This is why the API can afford a single hash lookup per request without a datastore round-trip on every call.

Two consequences you will actually notice:

- **Changes take effect within seconds, not instantly everywhere.** Narrowing a key's scopes, rolling it, or revoking it takes effect immediately on the instance that served the change, and everywhere else within 5 seconds. If you revoke a leaked key and a request slips through 2 seconds later, that is this window — not a failure of the revoke.
- **`last_used_at` in the console is coarse.** It is written at most once a minute per key, so a key that fired 4,000 requests in the last minute may show a `last_used_at` up to a minute stale. Use it to answer "is this key still in use at all", not "when exactly was the last call". For per-request truth, use the request log.

## Rolling a key without downtime

Rolling is how you rotate a secret without a deployment window. In the console, on the key, choose **Roll**.

What happens:

1. A **new** key is minted with the same name, the same scopes, and the same rate limit. Its secret is returned once, right there — this is the only response other than creation that carries a secret.
2. The old key is marked as rolling and given an expiry **24 hours** from that moment.
3. **Both keys authenticate for those 24 hours.**

So the safe sequence is: roll, copy the new secret into your secret manager, deploy, confirm traffic is flowing on the new key, and let the old one lapse. You never have a moment where no valid key exists.

After the grace window closes, the old secret returns `401` with `reason: expired_api_key`. Nothing is deleted before then, and nothing needs to be cleaned up after.

::: tip Rolling is the answer to more than rotation
Lost the secret, a laptop went missing, a contractor left, the key showed up in a CI log — all of these are rolls, not revokes. Revoke is for when you need the old secret dead *now* and can accept the outage. Roll is for everything with a deploy in front of it.
:::

A key that has already been revoked cannot be rolled; the console rejects it with `failed_precondition` and the message `"That key is already revoked."`

## Revoking a key

Revoking is immediate and permanent. In the console, delete the key. Within 5 seconds every request carrying it fails with `401` and `reason: revoked_api_key`.

**There is no un-revoke.** If you revoke the wrong key, you create a new one and redeploy — the secret is genuinely gone.

Revoke, rather than roll, when the secret is known to be compromised and you would rather break your own integration than leave a window open. That is the whole trade: roll keeps you running, revoke stops the bleeding.

## Key hygiene that actually helps

These are not ceremony. Each one exists because of a specific bad hour it prevents.

::: steps

::: step One key per system that calls us
Not one per workspace, not one shared across every service. The order service, the CRM sync, and the analytics exporter get three keys.

The payoff arrives when something goes wrong: you can revoke the leaked one without taking down the other two, you can read the request log per key to see who is generating the errors, and you can scope each one to exactly what it needs — the analytics exporter never gets `messages:send`.
:::

::: step Name the key after the system, not the person or the date
`Order service` and `Zoho sync (prod)` are good names. `Vinit's key`, `test`, and `key 2` are not. At 3 a.m., when one key is throwing 429s, the name is the only thing that tells you which deployment to look at — and the person who created it may have left the company.
:::

::: step Give it the narrowest scope that works
New keys are read-only by default (`conversations:read`, `agents:read`) precisely because widening a key later is a two-click change and un-leaking one is impossible. Add scopes when a request 403s, not in advance because you might need them. See [Scopes](/api/scopes).
:::

::: step Keep it out of source control, images, and logs
The `amk_` prefix exists so scanners can catch it — enable secret scanning on your repositories and add the pattern to your log scrubber. Load it from your secret manager at runtime; do not bake it into a container image, where it survives in every layer that ever held it.
:::

::: step Roll on staff change and on schedule
When someone with console access leaves, roll every key they could have read. Absent that, a quarterly roll costs one deploy and bounds how long any undetected leak stays useful.
:::

::: step Point every key at the right host
The environment is in the key. Load `amk_live_…` in production and `amk_test_…` in staging, and make your config loader assert the prefix matches the environment it thinks it is running in. That one assertion turns a confusing `wrong_environment` in production into a startup failure in staging.
:::

:::

## Verify all of this in one call

`GET /ping` is the fastest way to find out what the API thinks of your key. No side effects, no scope required beyond a valid key.

::: codegroup

```bash cURL
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```javascript Node.js
const response = await fetch("https://services.amomic.in/api/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` },
});
console.log(await response.json());
```

```python Python
import os, httpx

response = httpx.get(
    "https://services.amomic.in/api/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"},
)
print(response.json())
```

:::

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order service",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

That response answers four questions at once: the key is valid, it is pointed at the right workspace, it is the environment you expected, and it holds the scopes you think it does. Run it in your integration's startup health check.

## Next

::: cards

::: card Scopes
[What each scope unlocks](/api/scopes), the read-only default, and the endpoint matrix.
:::

::: card Errors
[The full error contract](/api/errors) — nine codes, one envelope, every `details.reason`.
:::

::: card Rate limits
[120 requests per key per minute](/api/rate-limits), and how to back off without a `Retry-After`.
:::

::: card Security and data
[What we store and for how long](/operate/security), including the request log.
:::

:::


----------------------------------------------------------------------------
## Scopes
URL: https://docs.amomic.in/api/scopes
----------------------------------------------------------------------------

A scope is a capability you grant an API key. There are exactly six, they are set when the key is created and editable afterwards, and they are the **only** thing that partitions what a key can do. There is no per-user key, no per-agent key, and no per-deployment key — a key is workspace-wide, and its scopes are the whole story.

The set is deliberately short because scopes are named after things a customer would say out loud — "can it send messages?", "can it read our conversations?" — rather than after HTTP routes. That is why `calls:write` covers reading a call as well as placing one: from the outside, placing calls and checking on them are one capability.

## The six scopes

```params
[
  {"name": "messages:send", "type": "write", "required": false, "description": "Send WhatsApp messages — free-form text and approved templates."},
  {"name": "calls:write", "type": "write", "required": false, "description": "Place outbound AI calls, read their status and outcome, and hang them up."},
  {"name": "conversations:read", "type": "read", "required": false, "description": "List conversations, read one, and read its transcript. Granted by default."},
  {"name": "contacts:write", "type": "write", "required": false, "description": "Create or update a contact by email or phone."},
  {"name": "tickets:write", "type": "write", "required": false, "description": "Open a support ticket <em>and</em> read one back. There is no separate read scope."},
  {"name": "agents:read", "type": "read", "required": false, "description": "List the agents in the workspace. Granted by default."}
]
```

Those six strings are the complete vocabulary. There is no `tickets:read`, no `messages:read`, no `contacts:read`, no `webhooks:*`, no `admin`, and no wildcard. If you see any of those in code an assistant wrote for you, it was invented.

## What each scope unlocks

### `messages:send`

- `POST /api/v1/messages`

One endpoint, and the one most integrations exist for. It covers both free-form text and approved templates — there is no separate template scope, because from the workspace's point of view both are "sending a message to a customer".

### `calls:write`

- `POST /api/v1/calls`
- `GET /api/v1/calls/{call_id}`
- `POST /api/v1/calls/{call_id}/hangup`

The whole call lifecycle, including the read. A key that can poll a call's outcome can also dial. If you want an integration that only *watches* calls, do not build it on a polled `GET` — subscribe to the `call.ended` [webhook](/webhooks/events) instead and give that service no `calls:write` scope at all.

### `conversations:read`

- `GET /api/v1/conversations`
- `GET /api/v1/conversations/{conversation_id}`
- `GET /api/v1/conversations/{conversation_id}/messages`

Read-only, and one of the two scopes on a new key. This is the scope an analytics exporter or a data-warehouse sync needs, and it is the only one it needs.

### `contacts:write`

- `POST /api/v1/contacts`

There is no corresponding read. The endpoint resolves a contact by email then phone and returns the result, so the "read" is a side effect of the upsert. A key with only `contacts:write` can therefore look a contact up by identity — hold that in mind when scoping a key that should not see customer records.

### `tickets:write`

- `POST /api/v1/tickets`
- `GET /api/v1/tickets/{ticket_id}`

Both directions, on one scope. See [the asymmetry](#the-tickets-asymmetry) below.

### `agents:read`

- `GET /api/v1/agents`

Read-only, and the second scope on a new key. Lists the agents in the workspace with their name and status, so an integration can resolve an `agent_id` without a human copying one out of the console.

## The matrix

| Endpoint | `messages:send` | `calls:write` | `conversations:read` | `contacts:write` | `tickets:write` | `agents:read` |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
| `GET /openapi.json` | – | – | – | – | – | – |
| `GET /ping` | – | – | – | – | – | – |
| `GET /channels` | – | – | – | – | – | – |
| `POST /messages` | ● | | | | | |
| `POST /calls` | | ● | | | | |
| `GET /calls/{call_id}` | | ● | | | | |
| `POST /calls/{call_id}/hangup` | | ● | | | | |
| `GET /conversations` | | | ● | | | |
| `GET /conversations/{id}` | | | ● | | | |
| `GET /conversations/{id}/messages` | | | ● | | | |
| `GET /agents` | | | | | | ● |
| `POST /contacts` | | | | ● | | |
| `POST /tickets` | | | | | ● | |
| `GET /tickets/{ticket_id}` | | | | | ● | |

No endpoint requires two scopes. No scope is implied by another — holding `messages:send` does not give you `conversations:read`, even though a message you sent appears in a conversation.

## Endpoints that need no scope

Three routes sit outside the matrix.

| Route | Requires |
|---|---|
| `GET /api/v1/openapi.json` | **Nothing.** No key at all. |
| `GET /api/v1/ping` | Any valid key, whatever its scopes. |
| `GET /api/v1/channels` | Any valid key, whatever its scopes. |

`ping` and `channels` are scope-free on purpose: they are the two calls you make *before* you know whether the rest of your configuration is right. If `ping` needed a scope, a misconfigured key would fail the diagnostic and the real request identically, and you would learn nothing from the difference. As it stands, a `200` from `ping` followed by a `403` from `POST /messages` localises the problem to one line in your console settings.

`openapi.json` needs no key because a machine-readable contract is not a secret — it describes the shape of the API, not your workspace. Hand it to a client generator or to [a coding agent](/agents-setup) before you have a key at all.

## New keys are read-only

A key created in the console starts with exactly two scopes:

```json
["conversations:read", "agents:read"]
```

This is not a default someone forgot to change. The reasoning is asymmetry of cost: **a key is easy to widen later and impossible to un-leak.**

Widening takes two clicks in the console and applies within seconds. Discovering three months later that a read-only reporting key had `messages:send` all along — and that it was sitting in a repository, or a CI log, or an ex-contractor's `.env` — costs you a rotation, an audit of every message that key could have sent, and a conversation you would rather not have.

So the workflow is: create the key read-only, run your integration, and add a scope each time you hit a `403` that names one. The 403 tells you exactly which scope to add, so this converges in minutes and leaves you with a key that holds nothing it never used.

::: tip Scope by system, not by convenience
Three keys with one scope each beat one key with six. When the CRM sync leaks, you revoke a key that could only write contacts. When the analytics exporter leaks, you revoke a key that could only read. Combine that with [naming each key after its system](/api/authentication) and an incident becomes a lookup rather than an investigation.
:::

Scopes are deduplicated and sorted when saved, so the order you tick them in does not matter and `GET /ping` always returns them alphabetically.

## When a scope is missing

```json title="403 Forbidden"
{
  "error": {
    "code": "permission_denied",
    "message": "This API key does not have the `messages:send` scope.",
    "details": {
      "reason": "missing_scope",
      "required_scope": "messages:send"
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

`details.required_scope` is the machine-readable answer: it names the exact string to tick in the console. Branch on it rather than parsing the message.

A `403` is also a proof of everything upstream of it. Scope is the last check in the [validation order](/api/authentication) — so a `permission_denied` means your key is genuine, unrevoked, in the right environment, and under its rate limit. The credential is fine; only the grant is wrong. Never respond to a `403` by re-issuing a key.

::: warning A 403 is not retryable
Nothing about waiting and trying again changes the scopes on a key. Treat `permission_denied` as terminal in your retry logic, log `required_scope`, and alert a human. See [Errors](/api/errors) for the full retryable/terminal split.
:::

## The tickets asymmetry

Reading a ticket requires `tickets:write`:

```endpoint
GET /api/v1/tickets/{ticket_id}
```

There is no `tickets:read` scope, so there is no way to grant a key the ability to check a ticket's status without also granting it the ability to open tickets.

This is worth planning around rather than working around. Two practical consequences:

- **A status-checking integration can create tickets.** If you build a dashboard that polls ticket status, its key can also open tickets. Scope that key to `tickets:write` and nothing else, so the worst case of a leak is spurious tickets in your queue rather than messages to your customers.
- **Prefer the webhook for status.** `ticket.created` and `ticket.updated` [webhook events](/webhooks/events) carry `ticket_id`, `public_ref`, `subject`, `status`, `priority`, and `channel`. A consumer that receives those needs no API key and therefore no scope at all. Polling `GET /tickets/{id}` is the fallback for when you have missed an event, not the primary mechanism.

The same shape appears more mildly on `calls:write` and `contacts:write` — in both cases a read is reachable through a write scope. The rule of thumb across all three: **if you only need to observe, observe over webhooks.** The API's read scopes cover conversations and agents; everything else observes better by being told than by asking.

## Checking what a key holds

```bash
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order service",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

Assert this in your integration's startup check. A service that fails fast at boot with "expected `messages:send`, key has only `conversations:read`" is far cheaper than one that discovers the same fact at 2 a.m. on the first order of the day.

## Next

::: cards

::: card Authentication
[How keys work](/api/authentication) — format, rolling, revoking, and the six causes of a 401.
:::

::: card Errors
[Every code and reason](/api/errors), including which are worth retrying.
:::

::: card Webhook events
[The nine events](/webhooks/events) — how to observe without holding a key that can act.
:::

::: card Going live
[The pre-launch checklist](/operate/going-live), including key and scope review.
:::

:::


----------------------------------------------------------------------------
## Errors
URL: https://docs.amomic.in/api/errors
----------------------------------------------------------------------------

Every failure on `/api/v1` comes back in the same envelope, with a code drawn from a closed set of nine. That uniformity is the point: one error handler covers the entire API, and you never have to guess whether a given endpoint reports failure differently.

The interesting part is `details.reason`. The code tells you the *class* of problem — is this my fault, your fault, or a precondition? — and the reason tells you exactly which problem it is. Handle both, in that order.

## The envelope

```json title="412 Precondition Failed"
{
  "error": {
    "code": "failed_precondition",
    "message": "This workspace has no WhatsApp sender connected.",
    "details": { "reason": "channel_not_connected" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Five fields, always present.

```params
[
  {"name": "error.code", "type": "string", "required": true, "enum": ["invalid_argument", "unauthenticated", "permission_denied", "not_found", "conflict", "failed_precondition", "rate_limited", "provider_error", "internal"], "description": "The class of failure. Exactly nine values are possible — see the map below. Branch on this first."},
  {"name": "error.message", "type": "string", "required": true, "description": "One human-readable sentence, written for a developer reading a log. <strong>Never branch on this.</strong> Wording can change without notice; codes and reasons cannot."},
  {"name": "error.details", "type": "object", "required": true, "description": "Always an object — <code>{}</code> when there is nothing to add. Usually carries <code>reason</code>, and sometimes extra keys specific to that reason (<code>required_scope</code>, <code>limit</code>, <code>supported</code>, <code>deployed_agent_id</code>, <code>errors</code>)."},
  {"name": "error.request_id", "type": "string", "required": true, "description": "Identifies this one request in our systems, prefix <code>req_</code>. Log it. Quoting it to support turns a support thread into a lookup."},
  {"name": "error.correlation_id", "type": "string", "required": true, "description": "Identifies the trace, prefix <code>cor_</code>. If you sent <code>X-Correlation-Id</code>, this echoes your value, which is how your logs and ours line up."}
]
```

::: warning details.reason is optional, error.details is not
`error.details` is always an object, but it is sometimes empty. A handful of errors carry no `reason` — see [errors without a reason](#errors-that-carry-no-reason). Write `error.details?.reason` (or `.get("reason")`), never `error.details.reason` on the assumption it exists.
:::

The `request_id` also appears against the request in your workspace's request log in the console, along with method, path, status, duration, which key was used, and the error code. If a request failed before authentication — a malformed key, no key at all — it cannot be attributed to a workspace and will not appear there. That absence is itself a diagnosis.

## Code to HTTP status

Nine codes. No tenth code can exist: the error type rejects any value outside this map at construction time.

| `code` | HTTP | What it means | Whose move |
|---|---|---|---|
| `invalid_argument` | 400 | The request is malformed or semantically wrong. | Fix the request. |
| `unauthenticated` | 401 | The key is missing, malformed, unknown, revoked, expired, or from the wrong environment. | Fix the credential or the host. |
| `permission_denied` | 403 | The key is valid but lacks the scope — or is reaching for something that is not its workspace's. | Grant a scope, or stop. |
| `not_found` | 404 | No such resource in this workspace. | Check the id. |
| `conflict` | 409 | The request collides with existing state. | Resolve the collision. |
| `failed_precondition` | 412 | The request is well-formed but the workspace is not in a state where it can succeed. | Change configuration. |
| `rate_limited` | 429 | Too many requests, or too many concurrent calls. | Back off. |
| `internal` | 500 | Something broke on our side. | Retry, then escalate. |
| `provider_error` | 502 | An upstream provider — the messaging or telephony network — failed or answered badly. | Retry with backoff. |

Note the two that surprise people:

- **412, not 501 or 503**, for "this capability is not available here". A 412 says the *precondition* for your request is unmet — no WhatsApp sender connected, no phone number on the workspace, the voice channel not configured. The request would be perfectly valid once that precondition is met, and repeating it unchanged will keep failing until a human changes something in the console.
- **403 for a foreign resource**, occasionally. Most cross-workspace access is answered with `404` — a call, conversation, or ticket belonging to another workspace reads as "not found" rather than "not yours", which leaks nothing about whether the id exists. The exception is `from_number` on a call, where a `403` is the honest answer to "that number is not yours".

## Validation failures are 400, not 422

If you have used other Python-backed APIs you may expect a `422 Unprocessable Entity` for schema violations. This API returns **400** with `code: "invalid_argument"`, so that field-level validation and hand-written rules land in the same branch of your handler.

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "loc": ["body", "to"],
          "msg": "String should match pattern '^\\+?\\d+$'",
          "type": "string_pattern_mismatch"
        },
        {
          "loc": ["body", "template", "name"],
          "msg": "String should have at least 1 character",
          "type": "string_too_short"
        }
      ]
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

The shape:

- `message` is always the literal `"Request validation failed."` — the useful detail is in `details.errors`.
- `details.errors` is an **array**, so several bad fields are reported at once rather than one per round trip.
- Each entry has `loc` (the path to the offending field, starting with `"body"` or `"query"`), `msg` (a human sentence), and `type` (a stable machine token like `string_too_short`, `missing`, `greater_than_equal`).

Note that a validation `400` has **no `details.reason`** — it has `details.errors` instead. That is the one place the two shapes differ, and it is why `reason` must always be read defensively.

The most common cause by a distance is phone-number formatting. `to` must match `^\+?\d+$` — digits with an optional leading `+`, 6 to 20 characters. `+919876543210` and `919876543210` both pass. `+91 98765 43210`, `+91-98765-43210`, and `(+91) 98765 43210` are all rejected here, before anything is sent. Strip separators before you call.

## Statuses the contract does not name

A few failures happen before your request reaches any handler — a wrong method, an oversized body, the wrong content type. These still come back in the envelope, mapped by a simple rule:

- **Any 4xx** the contract does not name → `code: "invalid_argument"`, original status preserved.
- **Any 5xx** the contract does not name → `code: "internal"`, original status preserved.

So a `POST` to a `GET`-only route returns HTTP `405` with `code: "invalid_argument"`, and the framework's `Allow` response header is preserved alongside the envelope. Your handler should therefore branch on `error.code` for behaviour but log the HTTP status too — they do not always match the table above, and when they diverge the status is the more specific fact.

Unhandled exceptions on our side always render as:

```json title="500 Internal Server Error"
{
  "error": {
    "code": "internal",
    "message": "Internal server error.",
    "details": {},
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

The message is deliberately opaque — the real exception is logged on our side only, because stack traces in an API response are a disclosure risk. This is the case where `request_id` earns its keep: send it to support and the underlying error is one lookup away.

## The complete `details.reason` catalogue

Grouped by where they come from. Every reason below is a stable string you can branch on.

### Authentication — `unauthenticated` / 401

| `reason` | Meaning | Fix |
|---|---|---|
| `missing_api_key` | Neither `Authorization: Bearer` nor `X-Api-Key` reached us. | Send the header. Check for a proxy stripping `Authorization`. |
| `malformed_api_key` | The token is not `amk_{live\|test}_{secret}`. No lookup was performed. | Truncated paste, wrapped line, quotes included, unsubstituted placeholder. |
| `invalid_api_key` | Well-formed, but no such key. | A key from another workspace, or one altered character. |
| `revoked_api_key` | The key was revoked in the console. Permanent. | Create a new key and redeploy. |
| `expired_api_key` | The old half of a roll, past its 24-hour grace. | Deploy the new secret. |
| `wrong_environment` | A `test` key against production, or a `live` key against a non-production host. | Point the right key at the right host. The credential is fine. |

Full detail in [Authentication](/api/authentication).

### Scope — `permission_denied` / 403

| `reason` | Extra fields | Meaning |
|---|---|---|
| `missing_scope` | `required_scope` | The key lacks the named scope. `details.required_scope` is the exact string to grant. |

See [Scopes](/api/scopes).

### Rate limiting — `rate_limited` / 429

| `reason` | Extra fields | Meaning |
|---|---|---|
| `rate_limited` | `limit`, `window_seconds` | The per-key request limit. `limit: 120`, `window_seconds: 60`. |
| `call_concurrency` | `limit` | Too many calls in progress for this workspace. `limit: 10`. Unrelated to the request limit. |

Both are `429`, and they need different responses — one waits for the next minute, one waits for a call to end. See [Rate limits](/api/rate-limits).

### Idempotency — `conflict` / 409

| `reason` | Meaning |
|---|---|
| `idempotency_key_reuse` | The same `Idempotency-Key` was already used on this endpoint, with a **different** request body. |

See [Idempotency](/api/idempotency).

### Contacts — `conflict` / 409

| `reason` | Meaning |
|---|---|
| `identity_conflict` | The `email` and `phone` you sent already belong to two different existing contacts. |

The API refuses to guess which one you meant, and refuses to merge them silently. Message: `"Those details belong to two different contacts."` Resolve the duplicate in the console, or send one identifier rather than two.

### Capability — `failed_precondition` / 412

| `reason` | Extra fields | Meaning |
|---|---|---|
| `unsupported_channel` | `supported` | The channel you asked for is not available on this deployment. `supported` lists the channels that are. |
| `unsupported_resource` | – | The resource family — conversations, tickets — is not available on this deployment. |

These say "this deployment does not carry that capability at all", which is different from "your workspace has not configured it". They are answered honestly rather than half-working, because a public API caller sent an explicit instruction and is entitled to a real error. `GET /api/v1/channels` is the supported way to discover what a deployment can do before you rely on it.

### Messages

| `reason` | Code / HTTP | Meaning |
|---|---|---|
| `empty_message` | `invalid_argument` / 400 | Neither `text` nor `template` was provided. Message: `"Provide either \`text\` or \`template\`."` |
| `template_variables` | `invalid_argument` / 400 | The wrong number or shape of variables for that template's placeholders. |
| `template_not_found` | `not_found` / 404 | No **approved** template by that name in this workspace. Message: `"No approved WhatsApp template named '<name>'."` |
| `channel_not_connected` | `failed_precondition` / 412 | The workspace has no WhatsApp sender connected. |

`template_not_found` catches two different mistakes: a genuine typo, and a template that exists but is not yet approved. Both look identical from here. Check the approval state in the console before you assume it is a spelling problem. [Templates](/channels/whatsapp-templates) covers the lifecycle.

### Calls

| `reason` | Code / HTTP | Meaning |
|---|---|---|
| `voice_not_configured` | `failed_precondition` / 412 | Voice is not configured for this deployment. |
| `workspace_suspended` | `failed_precondition` / 412 | The workspace is suspended and cannot place calls. |
| `self_dial` | `invalid_argument` / 400 | The destination is one of this workspace's own numbers. |
| `no_phone_number` | `failed_precondition` / 412 | The workspace owns no phone number to call from. See [Numbers and KYC](/channels/phone-numbers). |
| `unknown_from_number` | `permission_denied` / 403 | The `from_number` you specified is not owned by this workspace. |
| `no_agent_deployed` | `failed_precondition` / 412 | No agent is deployed to the caller-ID number, so nobody would be on the line. |
| `agent_number_mismatch` | `failed_precondition` / 412 | The `agent_id` you asserted is not the agent deployed to that number. `details.deployed_agent_id` names the one that is. |
| `originate_failed` | `internal` / 500 | The call could not be placed on the telephony network. |

`agent_number_mismatch` is worth understanding rather than working around. The agent that speaks on an outbound call is resolved **from the caller-ID number**, not from `agent_id` — `agent_id` is an assertion, and this error is that assertion failing. `details.deployed_agent_id` tells you what is actually deployed there. See [Outbound calls](/channels/outbound-calls).

### Errors that carry no reason

These come back with `details: {}` and rely on `code` plus `message`:

| Situation | Code / HTTP | Message |
|---|---|---|
| Unknown or foreign call id | `not_found` / 404 | `Call not found.` |
| Unknown or foreign conversation id | `not_found` / 404 | `Conversation not found.` |
| Unknown or foreign ticket id | `not_found` / 404 | `Ticket not found.` |
| `POST /contacts` with neither email nor phone | `invalid_argument` / 400 | `Provide an email or a phone number.` |
| `POST /tickets` with no requester detail | `invalid_argument` / 400 | `Provide at least one requester detail (name, email, or phone).` |
| Call destination shorter than 8 digits | `invalid_argument` / 400 | `That destination number is too short.` |
| Schema validation failure | `invalid_argument` / 400 | `Request validation failed.` — carries `details.errors` instead |
| Unhandled server exception | `internal` / 500 | `Internal server error.` |

The three `not_found` cases are worth a note: an id belonging to **another workspace** returns exactly the same `404` as an id that does not exist. That is an intentional guard — the API will not confirm the existence of a resource you cannot see. If you are certain an id is real and still getting `404`, check which workspace's key you are holding.

## How to handle errors well

### 1. Branch on `code`, then on `reason`

`code` decides the shape of your response — retry, alert, give up, surface to a user. `reason` decides the message you write into your own log or your own UI. Never parse `message`, and never branch on the HTTP status alone: `originate_failed` is a `500` that means "the call did not go through", which is a different thing from a generic server error even though the status matches.

### 2. Log `request_id` on every failure

Log it structurally, next to your own trace id, on every non-2xx. It is the only identifier that lets us find your exact request. Send `X-Correlation-Id` on the way in and `error.correlation_id` will echo it, so one grep spans both systems.

### 3. Know what is retryable

| Class | Retry? | How |
|---|---|---|
| `rate_limited` / `rate_limited` | **Yes** | Wait for the next minute boundary. See [Rate limits](/api/rate-limits). |
| `rate_limited` / `call_concurrency` | **Yes** | Wait for a call to finish — seconds to minutes, not milliseconds. |
| `internal` (500) | **Yes** | Exponential backoff, a small number of attempts, then alert. |
| `provider_error` (502) | **Yes** | The upstream network hiccuped. Backoff, then alert. |
| Connection errors, timeouts | **Yes** | Treat as `internal`. Assume the request **may** have succeeded. |
| `invalid_argument` (400) | No | The request is wrong. Retrying it identically is wrong identically. |
| `unauthenticated` (401) | No | Except after you have deployed a new secret. |
| `permission_denied` (403) | No | Nothing changes by waiting. Alert a human to grant the scope. |
| `not_found` (404) | No | Unless you are polling for something you believe is about to exist. |
| `conflict` (409) | No | Both `idempotency_key_reuse` and `identity_conflict` need your input, not time. |
| `failed_precondition` (412) | No | A human must change configuration. Retrying floods your logs and fixes nothing. |

::: danger Always retry POSTs with an Idempotency-Key
A timeout tells you nothing about whether the request ran. A message may have been delivered, a call may be ringing. Send `Idempotency-Key` on `POST /messages`, `POST /calls`, and `POST /tickets` and a retry replays the stored response instead of doing the thing twice. Without it, your retry is a second WhatsApp message to a real customer. See [Idempotency](/api/idempotency).
:::

### 4. Fail loudly on 412

`failed_precondition` almost always means a configuration gap: no sender connected, no phone number, no agent deployed to a DID. These are not transient and they are not your code's fault. Route them to an alert with the `reason` attached rather than into a retry queue where they will churn silently until someone notices no messages went out today.

### 5. A handler you can copy

::: codegroup

```javascript Node.js
const RETRYABLE_CODES = new Set(["rate_limited", "internal", "provider_error"]);

class AmomicError extends Error {
  constructor(status, error) {
    super(`${error.code}: ${error.message}`);
    this.status = status;
    this.code = error.code;
    this.reason = error.details?.reason ?? null;
    this.details = error.details ?? {};
    this.requestId = error.request_id;
    this.correlationId = error.correlation_id;
    this.retryable = RETRYABLE_CODES.has(error.code);
  }
}

async function amomicRequest(path, options = {}, attempt = 1) {
  const response = await fetch(`https://services.amomic.in/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  if (response.ok) return response.json();

  const body = await response.json();
  const err = new AmomicError(response.status, body.error);

  console.error("amomic_api_error", {
    status: err.status,
    code: err.code,
    reason: err.reason,
    request_id: err.requestId,
    correlation_id: err.correlationId,
    path,
  });

  // Configuration problems need a human, not a retry.
  if (err.code === "failed_precondition" || err.code === "permission_denied") {
    await alertOps(err);
    throw err;
  }

  if (err.retryable && attempt < 4) {
    // The per-key limit resets on the minute boundary; everything else backs off.
    const waitMs =
      err.reason === "rate_limited"
        ? (60 - new Date().getSeconds()) * 1000 + 250
        : 500 * 2 ** (attempt - 1);
    await new Promise((r) => setTimeout(r, waitMs));
    return amomicRequest(path, options, attempt + 1);
  }

  throw err;
}
```

```python Python
import logging, os, time
import httpx

RETRYABLE_CODES = {"rate_limited", "internal", "provider_error"}
BASE = "https://services.amomic.in/api/v1"
log = logging.getLogger(__name__)


class AmomicError(Exception):
    def __init__(self, status: int, error: dict):
        super().__init__(f"{error['code']}: {error['message']}")
        self.status = status
        self.code = error["code"]
        self.details = error.get("details") or {}
        self.reason = self.details.get("reason")
        self.request_id = error.get("request_id")
        self.correlation_id = error.get("correlation_id")
        self.retryable = self.code in RETRYABLE_CODES


def amomic_request(client: httpx.Client, method: str, path: str, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"}
    headers.update(kwargs.pop("headers", {}))

    for attempt in range(1, 5):
        response = client.request(method, f"{BASE}{path}", headers=headers, **kwargs)
        if response.is_success:
            return response.json()

        err = AmomicError(response.status_code, response.json()["error"])
        log.error(
            "amomic_api_error",
            extra={
                "status": err.status,
                "code": err.code,
                "reason": err.reason,
                "request_id": err.request_id,
                "correlation_id": err.correlation_id,
                "path": path,
            },
        )

        # Configuration problems need a human, not a retry.
        if err.code in ("failed_precondition", "permission_denied"):
            alert_ops(err)
            raise err

        if not err.retryable or attempt == 4:
            raise err

        if err.reason == "rate_limited":
            # The per-key window is fixed on the minute; wait it out.
            wait = 60 - time.gmtime().tm_sec + 0.25
        else:
            wait = 0.5 * (2 ** (attempt - 1))
        time.sleep(wait)
```

:::

Both examples send `Idempotency-Key` only if you pass one — on any `POST`, you should. Add `X-Correlation-Id` from your own tracing context and the two systems' logs join on one value.

## Next

::: cards

::: card Rate limits
[120 per key per minute](/api/rate-limits), a fixed window, and how to back off without a `Retry-After`.
:::

::: card Idempotency
[Make retries safe](/api/idempotency) on the three endpoints that honour the header.
:::

::: card Scopes
[Every 403 names a scope](/api/scopes) — here is the full matrix.
:::

::: card Troubleshooting
[Symptom-first debugging](/operate/troubleshooting) for when the error is not the problem.
:::

:::


----------------------------------------------------------------------------
## Rate limits
URL: https://docs.amomic.in/api/rate-limits
----------------------------------------------------------------------------

Two independent limits apply to the API. They have nothing to do with each other, they produce the same HTTP status, and they need completely different responses — so read `details.reason` before you decide what to do.

| Limit | Scope | Value | `details.reason` |
|---|---|---|---|
| Requests | Per API key, per minute | 120 | `rate_limited` |
| Concurrent outbound calls | Per workspace | 10 | `call_concurrency` |

## 120 requests per key per minute

Every API key gets 120 requests a minute. That is the limit for all keys; there is no self-serve way to raise it and no per-request parameter that changes it.

The budget belongs to the **key**, not to the workspace, not to your IP, not to an endpoint. Two consequences follow, and they pull in opposite directions:

- **Separate keys have separate budgets.** Your order service and your nightly conversation exporter each get their own 120 a minute. A runaway batch job on one key cannot starve the other. This is the strongest practical argument for [one key per system](/api/authentication).
- **A shared key shares one budget.** If ten replicas of the same service all hold the same key, those ten processes are collectively capped at 120 a minute — not 120 each. Autoscaling a service that was comfortable at two replicas can start throwing 429s at ten without any change in per-instance behaviour.

### What counts

The limit is consumed **after** your key is verified and **before** the scope check. In practice:

- A request rejected for a bad, missing, revoked, or wrong-environment key never reaches the limiter and never costs you a slot.
- A request that authenticates and then fails — a `403` for a missing scope, a `400` for a bad phone number, a `404` for an unknown id — **does** consume a slot. A tight retry loop against a request that will always 400 will exhaust your minute.
- `GET /ping` and `GET /channels` count like anything else. Do not poll them.
- `GET /api/v1/openapi.json` takes no key and is not counted.

## The window is fixed, not sliding

The counter is keyed on the wall-clock minute and reset when that minute rolls over. It is not a rolling 60-second window and not a token bucket.

This has a consequence worth designing around: **you can legitimately issue 240 requests in a 60-second span.** Fire 120 at 10:00:59 and 120 more at 10:01:01 and every one succeeds — they fall in different windows. Conversely, if you spend all 120 in the first two seconds of a minute, you are blocked for the remaining 58 seconds even though your average rate is well under the limit.

So the naive approach — hammer until you get a 429, then wait — is the worst-performing one. It clusters your traffic at the start of each window, wastes most of the minute in backoff, and produces a sawtooth throughput graph. Pacing yourself at roughly two requests a second gets more work through the same limit with no 429s at all.

The counter is maintained centrally, so the limit behaves identically whether your traffic lands on one of our instances or spreads across many.

## The headers

Successful responses carry two headers:

| Header | Example | Meaning |
|---|---|---|
| `X-RateLimit-Limit` | `120` | Requests allowed per minute for this key. |
| `X-RateLimit-Remaining` | `97` | Requests left in the current minute. |

::: warning These headers appear on successful responses only
They are attached on the non-exception path, so **no error response carries them — including the 429 itself.** You cannot read your remaining budget off a rejection, and you cannot watch the headers to detect that you are about to be throttled unless your requests are succeeding.

Practically: cache `X-RateLimit-Remaining` from the last successful response and use it as your pacing signal. When it drops below a threshold you have chosen, slow down proactively rather than waiting for the rejection.
:::

There is **no `X-RateLimit-Reset` header** and **no `Retry-After` header** anywhere on this API. Nothing tells you when the window turns over. You compute it, and it is easy to compute because the window is fixed to the clock: the reset is the **next minute boundary**. Sleep `60 - now.seconds` and a fraction, and you are in a fresh window.

## The 429 body

```json title="429 Too Many Requests"
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 120 requests/minute exceeded for this key.",
    "details": {
      "reason": "rate_limited",
      "limit": 120,
      "window_seconds": 60
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

`details.limit` and `details.window_seconds` restate the limit machine-readably, so your backoff logic does not have to hard-code 120 and 60.

A `429` with `reason: "rate_limited"` also proves your key is valid, unrevoked, and in the right environment — the limiter runs after all of those checks. It says nothing about scope, which is checked afterwards. Getting under the limit may simply reveal a `403` underneath.

## The limiter fails open

If the counter store is unreachable, the request is **served** rather than rejected. We would rather let a burst through than take your integration down because our bookkeeping had a bad minute.

Two things follow:

- **Do not use our rate limit as your safety brake.** If a bug in your code puts a message loop into overdrive, this limiter is not guaranteed to stop it. Put the guard in your own code — a queue, a semaphore, a per-customer send cap.
- **Absence of 429s is not proof you are under the limit.** During a fail-open period the counter is not being enforced, and `X-RateLimit-Remaining` will not reflect reality. Instrument your own request rate.

## Staying under it

::: steps

::: step Pace, do not burst
Two requests per second uses the full budget with zero rejections. A client-side limiter — a semaphore, a queue with a fixed drain rate, a token bucket refilling at 2/s — is a dozen lines and removes the problem entirely.
:::

::: step Give each system its own key
Separate budgets mean one system's bad afternoon is not another system's outage, and the [request log](/operate/troubleshooting) tells you which key generated the 429s.
:::

::: step Prefer webhooks to polling
Most 429 storms are polling loops. Do not poll `GET /calls/{id}` in a tight loop waiting for a call to end — subscribe to `call.ended`. Do not walk `GET /conversations` every thirty seconds — subscribe to `conversation.started` and `message.received`. [Webhooks](/webhooks/overview) turn a per-minute budget problem into a push.
:::

::: step Do not treat bulk sending as a loop over /messages
There is no batch endpoint, so a broadcast is your own loop. Pace it, checkpoint it so a crash does not restart from zero, and send each message with an [`Idempotency-Key`](/api/idempotency) derived from the recipient's record id — otherwise a restart re-messages everyone who already received it.
:::

::: step Watch the boundary, not the average
Because the window is fixed, an hourly job that fires 200 requests in one burst will always 429, however low its hourly average is. Spread the burst across the minutes it needs.
:::

:::

## Backing off correctly

The only correct wait for `reason: "rate_limited"` is "until the next minute boundary". Exponential backoff from an arbitrary base either waits too long — burning throughput you were entitled to — or too short, producing another 429 immediately.

::: codegroup

```javascript Node.js
// Waits until the start of the next minute, when the fixed window resets.
function msUntilNextWindow() {
  const now = new Date();
  return (60 - now.getSeconds()) * 1000 - now.getMilliseconds() + 250;
}

async function sendWithBackoff(payload, idempotencyKey, attempt = 1) {
  const response = await fetch("https://services.amomic.in/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(payload),
  });

  if (response.ok) {
    // Only successful responses carry these. Use them to pace the next call.
    const remaining = Number(response.headers.get("X-RateLimit-Remaining"));
    if (Number.isFinite(remaining) && remaining < 10) {
      await new Promise((r) => setTimeout(r, msUntilNextWindow()));
    }
    return response.json();
  }

  const { error } = await response.json();

  if (error.code === "rate_limited" && error.details?.reason === "rate_limited" && attempt < 5) {
    await new Promise((r) => setTimeout(r, msUntilNextWindow()));
    return sendWithBackoff(payload, idempotencyKey, attempt + 1);
  }

  if (error.code === "rate_limited" && error.details?.reason === "call_concurrency") {
    // A different problem entirely — a line has to free up. Requeue, do not spin.
    throw Object.assign(new Error(error.message), { requeueAfterSeconds: 30 });
  }

  throw new Error(`${error.code}: ${error.message} (request_id ${error.request_id})`);
}
```

```python Python
import os, time
import httpx

BASE = "https://services.amomic.in/api/v1"


def seconds_until_next_window() -> float:
    """The window is fixed to the wall clock, so the reset is the next minute."""
    now = time.time()
    return (60 - (now % 60)) + 0.25


def send_with_backoff(client: httpx.Client, payload: dict, idempotency_key: str):
    for attempt in range(1, 6):
        response = client.post(
            f"{BASE}/messages",
            headers={
                "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
                "Idempotency-Key": idempotency_key,
            },
            json=payload,
        )

        if response.is_success:
            # Present on successful responses only. Pace off it.
            remaining = response.headers.get("X-RateLimit-Remaining")
            if remaining is not None and int(remaining) < 10:
                time.sleep(seconds_until_next_window())
            return response.json()

        error = response.json()["error"]
        reason = (error.get("details") or {}).get("reason")

        if error["code"] == "rate_limited" and reason == "rate_limited":
            time.sleep(seconds_until_next_window())
            continue

        raise RuntimeError(
            f"{error['code']}: {error['message']} (request_id {error.get('request_id')})"
        )

    raise RuntimeError("Still rate limited after 5 windows — check your send rate.")
```

:::

Both examples pass an `Idempotency-Key`. That is not optional decoration on a retry loop: without it, a request that timed out after the server accepted it will be executed a second time when you retry. See [Idempotency](/api/idempotency).

## The other 429: concurrent calls

A workspace may have **10 calls in progress at once**. Once that many are live, the next `POST /api/v1/calls` is rejected:

```json title="429 Too Many Requests"
{
  "error": {
    "code": "rate_limited",
    "message": "This workspace already has 10 calls in progress (limit 10). Try again shortly.",
    "details": {
      "reason": "call_concurrency",
      "limit": 10
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

This is a completely different constraint from the request limit and needs a completely different response.

- It is **per workspace**, not per key. Splitting your dialler across two keys does not buy you twenty lines.
- It counts **live calls**, not requests. You do not clear it by waiting for a minute boundary — you clear it when a call ends, which could be twenty seconds or four minutes away.
- Backing off to the next minute is the wrong move. **Requeue the call** with a delay of tens of seconds and let your queue's own concurrency limiter hold the line at ten.

The right structure for an outbound campaign is a worker pool sized at or below ten, driven by a queue, where `call.ended` webhooks release capacity. That way you never see this error at all. [Outbound calls](/channels/outbound-calls) covers the rest of the dialling model, and [Trigger a call from your CRM](/recipes/crm-call) shows the queue pattern end to end.

::: note One key, one budget, one exception
Everything on this page except call concurrency is per key. If you remember one thing: `rate_limited` means wait for the clock; `call_concurrency` means wait for a phone to hang up.
:::

## Next

::: cards

::: card Idempotency
[Retry safely](/api/idempotency) — required reading before you write any backoff loop.
:::

::: card Errors
[The full error contract](/api/errors), including which codes are worth retrying.
:::

::: card Webhooks
[Stop polling](/webhooks/overview). Most rate-limit problems are a polling loop wearing a costume.
:::

::: card Limits and plans
[Everything else that is capped](/operate/limits) across the platform.
:::

:::


----------------------------------------------------------------------------
## Idempotency
URL: https://docs.amomic.in/api/idempotency
----------------------------------------------------------------------------

A request that times out tells you nothing. The socket closed; the message may already be on a customer's phone, the call may already be ringing in their pocket. You have two options and both are wrong: retry and risk doing it twice, or give up and risk never doing it at all.

`Idempotency-Key` removes the choice. You label the operation, we store the first response against that label, and every subsequent attempt with the same label gets the stored response back instead of executing again.

## Where it works

```params
[
  {"name": "Idempotency-Key", "type": "header", "required": false, "description": "Any string you choose, up to 200 characters. Read case-insensitively, surrounding whitespace stripped, and truncated at 200 characters if you send more."}
]
```

Three endpoints honour it. One deliberately does not.

| Endpoint | `Idempotency-Key` | Replayed status |
|---|---|---|
| `POST /api/v1/messages` | **Honoured** | `201` |
| `POST /api/v1/calls` | **Honoured** | `201` |
| `POST /api/v1/tickets` | **Honoured** — and deduplicates even without it | `201` |
| `POST /api/v1/contacts` | Ignored | – |

Every `GET` on the API is naturally idempotent — reading twice costs you a rate-limit slot and nothing else — so the header has no meaning there and is not read.

`POST /contacts` is the interesting omission. It is an **upsert**: it matches an existing contact on email, then on phone, and updates it in place, creating one only if nothing matched. Sending it twice with the same body resolves to the same contact both times. There is no duplicate to prevent, so there is no mechanism, and adding one would imply a hazard that does not exist. [Contacts](/api/contacts) covers the matching rules and the one case where a repeat *does* fail — `identity_conflict`, which no idempotency key would have saved you from.

## The mechanism

```mock
{"component": "IdempotencyDiagram", "props": {"caption": "First attempt executes and the response is stored. A retry with the same key and the same bytes returns that stored response without touching the provider."}}
```

::: steps

::: step You send a key

The header travels with your `POST`. We hash your workspace, the specific API key you authenticated with, the endpoint, and your key string into one record id.
:::

::: step We look for a stored response

If a record exists for that id and the body hash matches, the stored JSON body is returned immediately. Nothing else runs — the WhatsApp sender is never contacted, no call is placed, no ticket is opened.
:::

::: step Otherwise the request executes normally

The handler runs, you get your `201`, and the response body is written to the idempotency record for the next 24 hours.
:::

:::

## How the key is scoped

The stored record is keyed on four things together:

**your workspace** + **the API key you used** + **the endpoint** + **your key string**

Three consequences worth knowing before you design your key format.

**You do not have to namespace by endpoint.** `Idempotency-Key: order-4821-shipped` on `POST /messages` and the identical string on `POST /calls` are two independent records. They cannot collide, cannot replay each other's response, and cannot 409 each other. Use whatever name describes the operation and let the scoping do the separating.

**Two API keys in the same workspace do not share records.** If your sender service and your reconciliation job hold different keys, they each get their own idempotency namespace, even for byte-identical requests.

::: warning Rolling a key mid-retry loses the replay
Because the API key is part of the scope, an attempt made with the old half of a [rolled key](/api/authentication) and a retry made with the new half are two separate operations. The retry executes for real. If you are rolling keys and running a retry queue at the same time, drain the queue first.
:::

**The key is yours, the record id is not.** We never return the record id and there is no endpoint to inspect, list, or delete idempotency records. The only way to observe one is to send the request again.

## What a replay looks like

Exactly like the original. That is not a simplification — it is the whole contract.

- The **status code** is the endpoint's normal success status, so `201` for all three, not `200` and not `208`.
- The **body** is the stored JSON, byte for byte what you got the first time. The same `message_id`, the same `call_id`, the same `ticket_id`.
- There is **no marker header** and **no field** saying "this was replayed". No `Idempotent-Replay: true`, nothing in the envelope.

::: warning You cannot detect a replay from the response
If your code needs to know whether this attempt was the one that actually did the work — to decide whether to write an audit row, or increment a counter — the API will not tell you. Decide from your own state instead: check your "already sent" flag before you call, and set it after. The idempotency key protects the customer from a duplicate; only your own record protects your reporting from a double count.
:::

## Reusing a key with a different body

A stored record remembers a hash of the request body it was created from. Send the same key with a different body and you get a `409` rather than either behaviour you might have wanted:

```json title="409 Conflict"
{
  "error": {
    "code": "conflict",
    "message": "This Idempotency-Key was already used with a different request body.",
    "details": { "reason": "idempotency_key_reuse" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

We refuse rather than guess. Replaying the old response would silently drop your new request; executing the new one would break the promise the key made. Neither is safe, so the ambiguity comes back to you.

This is almost never a race. It is almost always one of two ordinary mistakes:

- **The key is too coarse.** `order-4821` used for the "shipped" message and again for the "delivered" message. Two different messages, one key. Put the event in the key.
- **The body was re-serialised.** Read the next section, because this one catches people who did everything else right.

## The body hash is over raw bytes

The match is `sha256` of the exact bytes of your request body. Not a normalised form, not a parsed structure — the bytes.

These two bodies are the same object to every JSON parser on earth, and two different bodies to us:

```json title="First attempt"
{"to":"+919876543210","text":"Your order AM-4821 has shipped."}
```

```json title="Retry — same data, different bytes"
{"text":"Your order AM-4821 has shipped.","to":"+919876543210"}
```

Key order changed, so the hash changed, so the retry is `409 idempotency_key_reuse`. Whitespace does it too: a pretty-printed retry of a compact original is a different body.

::: danger Serialise once, resend the same string
This is the failure that survives code review. A retry loop that rebuilds the payload from a dictionary each time is at the mercy of your serialiser's key ordering — which in several languages is stable within a process and not stable across versions or across a `dict` that was mutated in between.

Build the JSON string **before** the first attempt, hold it in a variable, and pass that same string to every attempt. In Python that means `content=payload` rather than `json=payload`; in Node it means one `JSON.stringify` outside the loop.
:::

The same rule applies to `metadata`. A `metadata` object that includes an attempt counter, a timestamp taken at call time, or a hostname produces a different body on every attempt and defeats the key entirely while looking correct.

## Records live for 24 hours

An idempotency record expires 24 hours after it is written. After that it reads as absent, so the same key executes a fresh request.

That boundary is real and it has a real failure mode: a job that fails, sits in a dead-letter queue over a weekend, and is replayed on Monday will send the message again. The key it carries is three days old and no longer matches anything.

If your queue can replay work that old — and most can — the idempotency key is not your last line of defence. Check your own "already notified" flag before you call. The key protects a retry loop measured in seconds and minutes; your database protects everything longer.

## The small race window

The stored response is written **in the background, just after the response is returned to you**. For a brief window — milliseconds — the first request has answered but its record does not exist yet. A retry that lands inside that window finds nothing stored and executes for real.

This is not a common event, because a retry inside a few milliseconds of a *successful* response means your client gave up on a response it had already received. But it is possible, and the honest description of the guarantee is:

> A retry spaced by at least a second, after a timeout or a `5xx`, will replay. A retry fired immediately might not.

Every backoff pattern in these docs starts at 500 ms or higher, which puts you outside the window. Do not build a tight loop that retries with zero delay — it is the one shape that can defeat the mechanism.

## Tickets deduplicate without a key

`POST /tickets` has a second, independent guard. Even with no `Idempotency-Key` header at all, the ticket id is derived from a hash of your request body, so an identical body sent twice converges on the **same ticket** instead of opening a second one.

That is why a `tkt_` id is a hash rather than a time-ordered id like `con_` or `call_`.

It is a useful floor, not a substitute for the header, because it defines "the same request" as "the same bytes" — and a description containing a timestamp, or a subject with the retry count in it, is not the same bytes. The header lets *you* declare what "the same request" means: one key per incident, per order, per reconciliation run. [Tickets](/api/tickets) has the detail.

## Choosing a key

This is the part that decides whether any of the above helps you. The mechanism is simple; picking the label is where integrations go wrong.

**A key names a real-world operation, not an attempt.** "The shipping notification for order 4821" is an operation. "The HTTP request I am about to make" is an attempt. There can be many attempts of one operation, and they must all carry the same key.

**Derive it, do not generate it.** The best key is a pure function of data you already have — an id from your own database, plus the event that triggered the send.

```
order-4821-shipped
renewal-8821-2026-08-01
ticket-sync-INC-9931
cart-88213-recovery
```

Every one of those can be recomputed from scratch after a process crash, a redeploy, or a queue redelivery, without having stored anything extra. That property is the whole point: a derived key survives situations where a generated key is already lost.

### Never a fresh UUID per attempt

```javascript
// Wrong. This defeats the entire mechanism.
headers: { "Idempotency-Key": crypto.randomUUID() }
```

A key generated inside the request function is a new key on every attempt. Every attempt therefore looks like a brand-new operation, executes for real, and sends a second message. The header is present, the code looks careful, and you have exactly the duplicate you were trying to prevent — with the added cost of believing you were protected.

This is the single most common way this feature is misused, and it is invisible until the day a network blip produces two WhatsApp messages to the same customer.

A UUID generated **once** and persisted alongside your record is correct, and is the right answer when nothing in your data identifies the operation. It is still weaker than derivation, because there is a window between generating it and durably storing it. Crash inside that window and the retry generates a new UUID. Derivation has no such window.

### Put the event in the key, not just the entity

`order-4821` is too coarse. The order will be the subject of several messages over its life — shipped, out for delivery, delivered, feedback request — and the second one to reuse that key gets a `409` because its body differs.

`order-4821-shipped` names one message about one order. The next notification is a different operation and gets a different key.

### Add a discriminator when a repeat is intentional

Some operations are *meant* to happen more than once with identical content: a daily reminder, a monthly statement, an OTP the customer asked to be resent. For those, the thing that makes the second one legitimately different is the occurrence, so put the occurrence in the key.

```
statement-8821-2026-08
reminder-INV-4410-2026-08-01
otp-919876543210-1754049600
```

Now the second send is a different operation, gets a different record, and executes — while a retry *within* that occurrence still replays.

### The table

| Key | Verdict |
|---|---|
| `order-4821-shipped` | Good. Derived, names one operation, recomputable. |
| `renewal-8821-2026-08-01` | Good. Repeats are legitimate and the date discriminates them. |
| `a3f0c9e1-…` persisted with the record | Acceptable. Correct if you write it before the first attempt. |
| `order-4821` | Too coarse. The next message about this order will `409`. |
| `crypto.randomUUID()` at call time | Broken. Every attempt is a new operation. |
| `order-4821-attempt-2` | Broken. The attempt number is exactly what must not vary. |
| `order-4821-${Date.now()}` | Broken. Same reason, harder to spot. |
| `whatsapp-send` | Broken the other way. Every send in 24 hours after the first one `409`s. |

Two smaller rules:

- **Keep the distinguishing part early.** The value is truncated at 200 characters. A key that only differs after character 200 is not a different key.
- **Treat the value as loggable.** It travels as a plain header and lands in log lines on both sides. If your logs are less protected than your database, do not build the key out of a raw email address.

## A retry loop that is actually safe

Both examples do the four things that matter: derive the key once, serialise the body once, reuse both on every attempt, and treat `idempotency_key_reuse` as a bug rather than something to retry.

::: codegroup

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function sendShippedNotice(order) {
  // Derived from data we already have. Recomputable after any crash.
  const idempotencyKey = `order-${order.id}-shipped`;

  // Serialised ONCE. Every attempt sends these exact bytes.
  const body = JSON.stringify({
    to: order.customerPhone,
    template: {
      name: "order_shipped",
      language: "en_US",
      variables: [order.customerName, order.reference],
    },
  });

  for (let attempt = 1; attempt <= 4; attempt++) {
    let response;

    try {
      response = await fetch(`${BASE}/messages`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      // Timeout or connection reset. The send may already have happened —
      // the key is what makes retrying it the right move rather than a gamble.
      if (attempt === 4) throw err;
      await sleep(500 * 2 ** (attempt - 1));
      continue;
    }

    // 201 on the first success, and 201 again on every replay. Indistinguishable.
    if (response.ok) return response.json();

    const { error } = await response.json();

    if (error.details?.reason === "idempotency_key_reuse") {
      // Our own bug: the body changed between attempts. Retrying cannot fix it.
      throw new Error(
        `Idempotency-Key ${idempotencyKey} was reused with a different body ` +
          `(request_id ${error.request_id})`,
      );
    }

    const retryable = ["rate_limited", "internal", "provider_error"].includes(error.code);
    if (!retryable || attempt === 4) throw new Error(`${error.code}: ${error.message}`);

    await sleep(500 * 2 ** (attempt - 1));
  }
}
```

```python Python
import json
import os
import time

import httpx

BASE = "https://services.amomic.in/api/v1"
RETRYABLE = {"rate_limited", "internal", "provider_error"}


def send_shipped_notice(client: httpx.Client, order) -> dict:
    # Derived from data we already have. Recomputable after any crash.
    idempotency_key = f"order-{order.id}-shipped"

    # Serialised ONCE, and sent as `content=` so httpx cannot re-encode it.
    # `json=payload` would rebuild the bytes on every attempt.
    body = json.dumps(
        {
            "to": order.customer_phone,
            "template": {
                "name": "order_shipped",
                "language": "en_US",
                "variables": [order.customer_name, order.reference],
            },
        },
        separators=(",", ":"),
    ).encode("utf-8")

    headers = {
        "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": idempotency_key,
    }

    for attempt in range(1, 5):
        try:
            response = client.post(
                f"{BASE}/messages", headers=headers, content=body, timeout=15.0
            )
        except httpx.RequestError:
            # No response at all. The send may already have happened.
            if attempt == 4:
                raise
            time.sleep(0.5 * 2 ** (attempt - 1))
            continue

        # 201 on the first success, and 201 again on every replay.
        if response.is_success:
            return response.json()

        error = response.json()["error"]

        if (error.get("details") or {}).get("reason") == "idempotency_key_reuse":
            raise RuntimeError(
                f"Idempotency-Key {idempotency_key} was reused with a different body "
                f"(request_id {error.get('request_id')})"
            )

        if error["code"] not in RETRYABLE or attempt == 4:
            raise RuntimeError(f"{error['code']}: {error['message']}")

        time.sleep(0.5 * 2 ** (attempt - 1))
```

:::

## Failures

```responses
[
  {"status": 201, "code": "", "reason": "", "description": "Either the request executed, or it replayed a stored response. You cannot tell which, and you should not need to."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "This key already has a stored response created from a different request body. Fix the caller — either the key is too coarse or the payload is being re-serialised. Do not retry."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Ordinary validation. Note that a request rejected at validation stores nothing, so the same key is still free."}
]
```

A request that fails is not stored, which means a `4xx` you caused does not burn the key. Fix the payload, keep the key, send again.

## Related

::: cards

::: card Errors
[The full catalogue](/api/errors) — nine codes, every `details.reason`, and which of them are worth retrying.
:::

::: card Rate limits
[120 requests per key per minute](/api/rate-limits) — the other half of any retry loop you write.
:::

::: card Messages
[POST /messages](/api/messages) — the endpoint where a missing key costs a customer a duplicate.
:::

::: card Order updates recipe
[End to end](/recipes/order-updates) — derived keys, backoff, and the webhooks that confirm delivery.
:::

:::


----------------------------------------------------------------------------
## Pagination
URL: https://docs.amomic.in/api/pagination
----------------------------------------------------------------------------

Every list on this API returns the same two-field envelope and follows the same stopping rule. Learn it once and it applies everywhere, because there are only three endpoints that return a list and two of them are the same shape as each other.

```json
{
  "items": [ … ],
  "next_cursor": "…" 
}
```

That is the entire contract. No total, no page numbers, no links, no metadata block.

## What actually paginates

| Endpoint | Paginates | `limit` default | `limit` max | Cursor is |
|---|---|---|---|---|
| `GET /api/v1/conversations` | **Yes** | `25` | `100` | The last item's `updated_at` |
| `GET /api/v1/conversations/{id}/messages` | **Yes** | `100` | `200` | The last item's `message_id` |
| `GET /api/v1/agents` | No | – | – | Always `null` |

`GET /agents` returns the identical envelope — `items` plus `next_cursor` — but accepts no `limit`, accepts no `cursor`, and never sets `next_cursor` to anything but `null`. It gives you every agent in the workspace in one response. Write your client so that consuming it through the same generic walk function is harmless: the loop reads one page, sees a `null` cursor, and stops. See [Agents and channels](/api/discovery).

Nothing else on the API returns a list. There is no `GET /messages`, no `GET /calls`, no contact list, and no ticket list — [Overview](/api/overview) has the full route table and the reasoning.

## The stopping rule

**`next_cursor` is non-null only when the page came back full.**

The server counts the rows it returned. If that count equals the `limit` you asked for, there might be more, so it hands you a cursor. If the count is even one short, there cannot be more, so it hands you `null`.

```
limit=25, got 25 items  →  next_cursor: "2026-08-01T10:02:55.118307+00:00"   keep going
limit=25, got 24 items  →  next_cursor: null                                  stop
limit=25, got 0 items   →  next_cursor: null                                  stop
```

This is the only signal. Do not infer "more pages" from the size of `items` yourself, and do not stop early because a page looked short in a way you did not expect — stop when the cursor is `null`, and only then.

::: note One extra request at the boundary
If the number of matching rows is an exact multiple of your `limit`, the last real page comes back full, so it carries a cursor. Following it returns `{"items": [], "next_cursor": null}` and the walk ends there.

That empty page is correct behaviour, not an error. A loop that handles it naturally — process zero items, see a null cursor, stop — needs no special case. A loop that assumes every page has at least one item does need one.
:::

## Using the cursor

Pass `next_cursor` back as the `cursor` query parameter on the next request. Change nothing else — keep the same `limit` and the same filters.

```
GET /api/v1/conversations?limit=50
GET /api/v1/conversations?limit=50&cursor=2026-08-01T10:02:55.118307%2B00:00
```

::: warning URL-encode it
The conversations cursor is an ISO timestamp with a `+00:00` offset, and a raw `+` in a query string means a space. Use your HTTP client's parameter encoding — `URLSearchParams` in Node, `params={}` in `httpx`, `--data-urlencode` with `curl -G` — never string concatenation. A cursor that loses its `+` is a cursor that does not mean what you sent.
:::

### Treat it as opaque

The values are not random: for conversations the cursor is the last row's `updated_at`, and for messages it is the last row's `message_id`. Knowing that helps you read a log line. It is not permission to build one.

- **Do not construct a cursor** from a timestamp you have lying around. There is no documented behaviour for a value we did not issue.
- **Do not parse a cursor** to learn where you are. For conversations, `items[-1].updated_at` is the same value and is part of the response contract; for messages, `items[-1].message_id` is.
- **Do not persist a cursor** as a long-lived bookmark between scheduled runs. It is a position inside one walk, not a subscription. Persist a value from the data instead — the highest `updated_at` you have processed — and start each run from page one. [Conversations](/api/conversations) has that pattern written out.

A cursor from `/conversations` has no meaning on `/conversations/{id}/messages`, and the reverse is equally meaningless. They are different types that happen to share a parameter name.

## Ordering

The two paginating endpoints order in opposite directions, and both choices are deliberate.

**Conversations: newest activity first.** Ordered by `updated_at` descending. Page one is what changed most recently, which is what makes an incremental sync possible — you walk forward until you reach something you have already seen, then stop.

**Messages: oldest first.** Ordered by `message_id` ascending, and those ids are time-ordered, so this is chronological order. Paginating forward reads the conversation from its opening line to its last turn. That is reading order, and it is the order you want when you are rendering a transcript or feeding one to a model.

::: warning A live list is not a stable snapshot
Conversations are ordered by recent activity, so a conversation that receives a message *while you are paginating* jumps to the front of the list — behind the cursor you already passed. You will not see it in this walk, and a conversation that moves from page 3 to page 1 can push another one across the page boundary you already crossed, so you can also see the same conversation twice.

Neither is a bug you can configure away; it is what "ordered by mutable field" means. Design around it:

- **Upsert, never append.** Key on `conversation_id` and `message_id` so a duplicate is a no-op.
- **Let the next run catch what moved.** A conversation that jumped forward has a newer `updated_at` than your watermark, so the next scheduled walk picks it up first.

Messages do not have this problem. `message_id` never changes and new turns are always appended at the end, so a forward walk is stable.
:::

## Choosing a limit

Bigger pages mean fewer requests, and requests are the scarce resource — you have [120 per key per minute](/api/rate-limits).

| Situation | Suggested `limit` |
|---|---|
| Backfilling a workspace's history | `100` conversations, `200` messages — the maxima |
| An incremental sync every few minutes | `100` conversations; you will usually stop inside page one |
| Rendering a list in your own UI | Match your page size, `25`–`50` |

A `limit` outside the endpoint's bounds is a `400`, not a silent clamp:

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "loc": ["query", "limit"],
          "msg": "Input should be less than or equal to 100",
          "type": "less_than_equal"
        }
      ]
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Note the two maxima are different — `100` for conversations, `200` for messages. Sending `limit=200` to `/conversations` fails. See [Errors](/api/errors) for the validation shape.

## Walking a list correctly

One generic function handles every list on the API, including the one that does not paginate.

::: codegroup

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };

/**
 * Yields every item across every page.
 * Works for /conversations, /conversations/{id}/messages, and /agents —
 * the last one simply returns one page with a null cursor.
 */
async function* paginate(path, query = {}) {
  let cursor = null;

  for (;;) {
    const params = new URLSearchParams(query);
    if (cursor) params.set("cursor", cursor); // URLSearchParams encodes the +

    const response = await fetch(`${BASE}${path}?${params}`, { headers: HEADERS });

    if (!response.ok) {
      const { error } = await response.json();
      throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
    }

    const { items, next_cursor } = await response.json();

    // An empty final page is normal when the row count divides evenly.
    for (const item of items) yield item;

    if (!next_cursor) return; // the only stop condition
    cursor = next_cursor;
  }
}

// Every conversation handled by one agent.
for await (const conversation of paginate("/conversations", {
  limit: "100",
  agent_id: agentId,
})) {
  await upsertConversation(conversation); // idempotent — pages can overlap
}

// A full transcript, oldest turn first.
const turns = [];
for await (const message of paginate(`/conversations/${conversationId}/messages`, {
  limit: "200",
})) {
  turns.push(message);
}
```

```python Python
import os
from collections.abc import Iterator

import httpx

BASE = "https://services.amomic.in/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"}


def paginate(
    client: httpx.Client, path: str, **query: str | int
) -> Iterator[dict]:
    """Yield every item across every page.

    Works for /conversations, /conversations/{id}/messages, and /agents —
    the last one simply returns one page with a null cursor.
    """
    cursor: str | None = None

    while True:
        params = dict(query)
        if cursor:
            params["cursor"] = cursor  # httpx encodes the + for you

        response = client.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=30.0)

        if not response.is_success:
            error = response.json()["error"]
            raise RuntimeError(
                f"{error['code']}: {error['message']} ({error.get('request_id')})"
            )

        page = response.json()

        # An empty final page is normal when the row count divides evenly.
        yield from page["items"]

        if not page["next_cursor"]:  # the only stop condition
            return
        cursor = page["next_cursor"]


with httpx.Client() as client:
    # Every conversation handled by one agent.
    for conversation in paginate(client, "/conversations", limit=100, agent_id=agent_id):
        upsert_conversation(conversation)  # idempotent — pages can overlap

    # A full transcript, oldest turn first.
    turns = list(
        paginate(client, f"/conversations/{conversation_id}/messages", limit=200)
    )
```

:::

Three properties make those loops correct rather than nearly correct:

- **The cursor is the only stop condition.** Not an item count, not an empty page, not a comparison against `limit`.
- **The query stays constant across pages.** Changing `limit` or `agent_id` mid-walk pairs a cursor with a different result set.
- **The consumer is idempotent.** Because a live list can hand you the same row twice, `upsert` is the only safe verb.

## What does not exist

Do not build against any of these. They are not missing features waiting on a release; the envelope has two fields and that is the design.

| You might expect | Reality |
|---|---|
| `total`, `count`, `total_pages` | No count of any kind. Counting rows to answer a query nobody asked for costs a scan on every page. |
| `has_more` | Redundant. `next_cursor !== null` is the same fact. |
| `prev_cursor` | Forward only. To go back, restart the walk. |
| `page=3`, `offset=50` | Cursor only. Offsets skip and duplicate rows when the underlying list is changing, which this one always is. |
| `sort` or `order` | Fixed per endpoint. Conversations descending by activity, messages ascending by id. |
| `Link` headers | Nothing is in the response headers. The cursor is in the body. |
| A cursor that expires | Not documented, so do not build a refresh path — but also do not hold one for hours. Persist a watermark instead. |

## Pagination and your rate limit

Each page is one request against the [120 per key per minute](/api/rate-limits) budget.

A first-run backfill is where this bites: one request per page of conversations, plus one request per page of transcript for each conversation. A workspace with two thousand conversations is well over two thousand requests, which is at least seventeen minutes at the limit even if nothing else is running.

Two things make that survivable:

- **Sleep between pages**, or use the largest `limit` each endpoint allows so you need fewer of them.
- **Give the backfill its own API key.** Scopes and rate limits are per key, so a backfill on a separate key cannot starve your production sends. [Scopes](/api/scopes) covers creating a narrow, read-only key for exactly this.

A `429` mid-walk is recoverable: the cursor you are holding is still valid, so back off and retry the same request rather than restarting.

## Related

::: cards

::: card Conversations
[The endpoints that paginate](/api/conversations) — the conversation object, the transcript, and a worked incremental sync.
:::

::: card Agents & channels
[GET /agents](/api/discovery) — the list that returns this envelope but never paginates.
:::

::: card Rate limits
[120 per key per minute](/api/rate-limits) — the ceiling every backfill meets first.
:::

::: card Sync conversations
[The complete recipe](/recipes/sync-conversations) — watermarks, scheduling, and where webhooks fit alongside a walk.
:::

:::


----------------------------------------------------------------------------
## Messages
URL: https://docs.amomic.in/api/messages
----------------------------------------------------------------------------

```endpoint
POST /api/v1/messages
```

One endpoint, one job: put a WhatsApp message in front of a specific phone number, from one of your connected senders.

## When you use this

You use `POST /messages` when *your* system knows something the customer needs to hear and no conversation is in progress — an order shipped, a payment failed, an appointment is tomorrow, a ticket was resolved. Your backend already has the trigger; this endpoint is the last hop.

What it is not: a chat API. You do not use it to reply on behalf of an agent — a deployed agent answers inbound messages on its own, and those replies land in the inbox without you doing anything. You also cannot read messages back through it; there is no `GET /api/v1/messages` and no message list endpoint. To see what was said, read the [conversation](/api/conversations); to learn what happened to a message you sent, subscribe to the `message.status` [webhook](/webhooks/events).

Scope required: `messages:send`. See [Scopes](/api/scopes).

::: note WhatsApp is the only sendable channel
`channel` is a single-value enum today. Web chat is inbound-only from the visitor's browser, and voice is a call, not a message — that is [`POST /calls`](/api/calls). Sending any other `channel` value is a schema error, not a capability error, and comes back as a 400 before anything is attempted.
:::

## Parameters

```params
[
  {"name": "channel", "type": "string", "required": false, "default": "whatsapp", "enum": ["whatsapp"], "description": "The only accepted value is <code>whatsapp</code>. Any other value fails request validation with <code>400 invalid_argument</code>."},
  {"name": "to", "type": "string", "required": true, "description": "Destination phone number. 6–20 characters, digits with an optional leading <code>+</code> — pattern <code>^\\+?\\d+$</code>. No spaces, dashes, or parentheses."},
  {"name": "text", "type": "string", "required": false, "default": "null", "description": "Free-form message body, maximum 4096 characters. Only deliverable while the 24-hour window is open. Mutually exclusive in practice with <code>template</code>; supply one."},
  {"name": "template", "type": "object", "required": false, "default": "null", "description": "An approved WhatsApp template to send instead of free-form text. See <code>PublicTemplate</code> below. Works whether the window is open or closed."},
  {"name": "sender_id", "type": "string", "required": false, "default": "null", "description": "Which connected WhatsApp sender to send from, maximum 64 characters. Omit to use the workspace default sender. Get ids from <a href=\"/api/discovery\">GET /channels</a>."},
  {"name": "metadata", "type": "object", "required": false, "default": "{}", "description": "Free-form key/value object stored with the message record. Use it to carry your own order id or job id. Not sent to the customer and not returned in the response."}
]
```

### The `PublicTemplate` object

```params
[
  {"name": "name", "type": "string", "required": true, "description": "The template name exactly as approved in your WhatsApp Business account. 1–120 characters. Template names are lowercase with underscores, for example <code>order_shipped</code>."},
  {"name": "language", "type": "string", "required": false, "description": "The template's language code, maximum 16 characters — for example <code>en</code>, <code>en_US</code>, or <code>hi</code>. Omit and the default language is used. Lookup prefers an exact match, then the same base language, then any variant."},
  {"name": "variables", "type": "array | object", "required": false, "description": "Values for the body placeholders. Either a positional array <code>[\"Asha\", \"AM-4821\"]</code> or a numbered object <code>{\"1\": \"Asha\", \"2\": \"AM-4821\"}</code>."},
  {"name": "header_variables", "type": "array | object", "required": false, "description": "Values for placeholders in the template's header component. Separate from the body — header placeholders are numbered from 1 within the header."},
  {"name": "button_variables", "type": "array | object", "required": false, "description": "Values for placeholders in dynamic URL buttons. Separate from the body, numbered per button."}
]
```

### Either `text` or `template` — never neither

Both fields are optional in the schema, but a request with neither is rejected before the provider is touched:

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Provide either `text` or `template`.",
    "details": { "reason": "empty_message" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

An empty string in `text` counts as nothing and produces the same `empty_message` reason. If you build the body dynamically, check for the empty case in your own code rather than discovering it as a 400 in production — a template render that returns `""` is a bug in your system, and this error is where it surfaces.

If you send both `text` and `template`, the template is what goes out. Do not rely on that; pick one at the call site.

### Phone number format

`to` is validated against `^\+?\d+$` with a length between 6 and 20 characters. The pattern is deliberately strict: a number that reaches the provider with punctuation in it fails deep in the send path where the error is much harder to read, so it is rejected at the door instead.

| Input | Result |
|---|---|
| `+919876543210` | Accepted |
| `919876543210` | Accepted — the leading `+` is optional |
| `+91 98765 43210` | **Rejected** — spaces |
| `+91-98765-43210` | **Rejected** — dashes |
| `(+91) 9876543210` | **Rejected** — parentheses |
| `+91.98765.43210` | **Rejected** — dots |
| `98765 43210` | **Rejected** — spaces, and no country code |

A rejected number comes back as a request-validation error:

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "loc": ["body", "to"],
          "msg": "String should match pattern '^\\+?\\d+$'",
          "type": "string_pattern_mismatch"
        }
      ]
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

There is no leniency layer and no country-code inference — strip everything that is not a digit or a leading `+` before you call. The `to` in the response is always normalised to `+` followed by digits, so you can store the response value as your canonical form.

::: warning Numbers stored by humans are rarely clean
If your numbers came from a CRM, a spreadsheet, or a web form, assume they carry spaces and dashes. Normalise once at the boundary — `"+" + value.replace(/\D/g, "")` in JavaScript, `"+" + re.sub(r"\D", "", value)` in Python — rather than at each call site.
:::

### Template variables, positionally or by number

A template body contains placeholders `{{1}}`, `{{2}}`, and so on. You fill them either way:

```json title="Positional"
{ "variables": ["Asha", "AM-4821", "3 October"] }
```

```json title="Numbered"
{ "variables": { "1": "Asha", "2": "AM-4821", "3": "3 October" } }
```

The numbered form is worth the extra characters when the values come from different parts of your code and a silent reordering would be invisible — a positional array does not complain when you swap the customer name and the order reference, it just sends the wrong message.

Header and button placeholders are **separate namespaces**, each numbered from 1, and each has its own field:

```json title="A template with a header and a dynamic URL button"
{
  "to": "+919876543210",
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "header_variables": ["Acme Retail"],
    "variables": ["Asha", "AM-4821"],
    "button_variables": ["AM-4821"]
  }
}
```

Put a header value in `variables` and you get a `template_variables` error, because the body then has one more value than it has placeholders. When you get that error, count the placeholders in each component separately — that is almost always the discrepancy.

::: note The template must already be approved
This endpoint sends templates; it does not create them. The name you pass must exist in your WhatsApp Business account with status `approved`. Create and submit templates in the console — see [Templates](/channels/whatsapp-templates) for the components, limits, and the review cycle.
:::

## Example

Sending an order update to a customer who has not messaged you recently — so a template, not text.

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-shipped" \
  -d '{
    "to": "+919876543210",
    "sender_id": "was_9f2c41ab77de1063c8a4b512",
    "template": {
      "name": "order_shipped",
      "language": "en_US",
      "variables": ["Asha", "AM-4821"]
    },
    "metadata": { "order_id": "4821", "source": "fulfilment-worker" }
  }'
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";

async function sendOrderShipped(order) {
  const response = await fetch(`${BASE}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `order-${order.id}-shipped`,
    },
    body: JSON.stringify({
      to: `+${order.customerPhone.replace(/\D/g, "")}`,
      sender_id: process.env.AMOMIC_SENDER_ID,
      template: {
        name: "order_shipped",
        language: "en_US",
        variables: [order.customerName, order.reference],
      },
      metadata: { order_id: order.id, source: "fulfilment-worker" },
    }),
  });

  const payload = await response.json();
  if (!response.ok) {
    const { code, message, details, request_id } = payload.error;
    throw new Error(`${code}/${details.reason ?? "-"}: ${message} (${request_id})`);
  }
  return payload.message_id;
}
```

```python Python
import os, re, httpx

BASE = "https://services.amomic.in/api/v1"


def send_order_shipped(order) -> str:
    response = httpx.post(
        f"{BASE}/messages",
        headers={
            "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
            "Idempotency-Key": f"order-{order.id}-shipped",
        },
        json={
            "to": "+" + re.sub(r"\D", "", order.customer_phone),
            "sender_id": os.environ["AMOMIC_SENDER_ID"],
            "template": {
                "name": "order_shipped",
                "language": "en_US",
                "variables": [order.customer_name, order.reference],
            },
            "metadata": {"order_id": order.id, "source": "fulfilment-worker"},
        },
        timeout=30.0,
    )
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(
            f"{error['code']}/{error['details'].get('reason', '-')}: "
            f"{error['message']} ({error['request_id']})"
        )
    return response.json()["message_id"]
```

:::

Free-form text is the same call with `text` in place of `template`:

```json title="Request body — only valid inside the 24-hour window"
{
  "to": "+919876543210",
  "text": "Your refund of ₹1,240 has been processed and should reach your account in 3 working days."
}
```

```mock
{"component": "WhatsAppMock", "props": {"body": "Hi Asha, your order *AM-4821* has shipped and is out for delivery today.", "footer": "Acme Retail", "buttons": ["Track order"], "time": "10:04", "caption": "What the template above renders as on the customer's phone. The variables you passed are substituted into the approved body."}}
```

## Response

```json title="201 Created"
{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4RDU5OTQ2NUEwQjc4AA==",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "sent"
}
```

| Field | Type | Notes |
|---|---|---|
| `message_id` | string | The provider's message id — a WhatsApp `wamid.…`. Store it: this is the join key for every later `message.status` webhook about this message. |
| `channel` | string | Always `whatsapp` today. |
| `to` | string | Your `to`, normalised to `+` followed by digits. |
| `status` | string | Always `sent` on a 201. |

::: warning `sent` means accepted, not delivered
`status: "sent"` is an acknowledgement that the message was accepted for delivery. It is not a delivery receipt and says nothing about whether the handset was reachable. Delivery outcomes arrive later on the `message.status` webhook, which carries WhatsApp's own status string — the expected set is `sent`, `delivered`, `read`, and `failed`, with a `reason` attached on failure. See [Event reference](/webhooks/events).
:::

`metadata` is stored, not echoed. If you need to correlate the response to your own record, key off `message_id`, or use your own id as the `Idempotency-Key`.

### Idempotency

`POST /messages` honours the `Idempotency-Key` header. Send one on every call. A retry after a socket timeout replays the stored 201 instead of messaging the customer a second time, and the provider is never reached on the replay. Keys live for 24 hours and are scoped to your workspace, your specific API key, and this endpoint. Reusing a key with a different body is a `409`. The full mechanics are in [Idempotency](/api/idempotency).

## Failures

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "empty_message", "description": "Neither `text` nor `template` was supplied, or `text` was empty. Nothing was sent."},
  {"status": 400, "code": "invalid_argument", "reason": "template_variables", "description": "The number or shape of variables does not match the approved template. Count body, header, and button placeholders separately."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Request validation failed — a bad `to` pattern, `text` over 4096 characters, an unknown `channel`, or a missing `template.name`. `details.errors` names the field."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, invalid, revoked, expired after a roll, or used against the wrong host. Read `details.reason` before assuming a bad secret."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key is valid but lacks `messages:send`. `details.required_scope` names it."},
  {"status": 403, "code": "permission_denied", "reason": "suppressed", "description": "The recipient opted out by replying STOP. Nothing is sent until they reply START. This applies to templates too."},
  {"status": 404, "code": "not_found", "reason": "template_not_found", "description": "No approved template with that name in this workspace. Check spelling, and check the template is `approved` rather than `pending` or `rejected`."},
  {"status": 409, "code": "conflict", "reason": "session_window_closed", "description": "Free-form `text` outside the 24-hour customer service window. Send an approved template instead."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "The same `Idempotency-Key` was already used with a different request body."},
  {"status": 412, "code": "failed_precondition", "reason": "channel_not_connected", "description": "This workspace has no WhatsApp sender connected. Connect one in the console first."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_channel", "description": "This deployment carries no WhatsApp module at all. `details.supported` lists the channels that are available."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests per minute per API key exceeded. `details.limit` and `details.window_seconds` are included."},
  {"status": 502, "code": "provider_error", "reason": "", "description": "WhatsApp itself returned an error after retries. `details` carries `provider_code`, `provider_subcode`, `provider_message`, and `provider_user_message`."}
]
```

### The three you will actually hit

**`session_window_closed` (409).** You sent `text` when the customer last messaged you more than 24 hours ago. This is the single most common integration surprise, and it is a WhatsApp platform rule rather than ours. The fix is a template, not a retry. [The 24-hour window](/channels/whatsapp-window) explains exactly when the window opens, what re-opens it, and why nothing is auto-queued for later.

The safe pattern for anything triggered by your own system rather than by the customer:

```javascript
// Do not branch on window state — you cannot query it, and it can close
// between your check and your send. Send the template and be done.
await sendTemplate(customer.phone, "order_shipped", [customer.name, order.ref]);
```

**`template_not_found` (404).** The message reads `No approved WhatsApp template named '<name>'.` Three causes, in order of likelihood: a typo, a template still sitting at `pending` in Meta's review queue, or a template that exists in a different language than the one you asked for. Template names are matched exactly and are lowercase with underscores.

**`channel_not_connected` (412).** No WhatsApp sender exists in the workspace. Distinct from `unsupported_channel`, which means the deployment cannot do WhatsApp at all. Call [`GET /channels`](/api/discovery) to see which is which — if `message_channels` contains `whatsapp` but `senders` is empty, you need to connect a number; if `message_channels` is empty, the channel is not on this deployment.

::: note 412, not 501
Capability failures use `412 Precondition Failed` rather than `501` or `503`. The distinction that matters to your retry logic: a 412 will keep failing until someone changes configuration, so do not retry it on a backoff — surface it to a human.
:::

## What this endpoint does not do

- **No media.** Text and approved templates only. There is no image, document, audio, video, sticker, or location send path, and no upload endpoint to put a file behind one.
- **No bulk send.** One recipient per request. There is no batch endpoint, no audience model, and no scheduling parameter — loop, and respect the 120 requests/minute [rate limit](/api/rate-limits).
- **No read-back.** No `GET /api/v1/messages`, no list endpoint. Read what was said through [Conversations](/api/conversations).
- **No delivery status query.** Delivery outcomes are pushed to your [webhook](/webhooks/events), not polled.

## Related

::: cards

::: card The 24-hour window
[When text works and when it does not](/channels/whatsapp-window) — the rule behind every `session_window_closed`.
:::

::: card Templates
[Create, submit, and structure templates](/channels/whatsapp-templates), including component limits and button types.
:::

::: card Order-shipped, end to end
[A complete recipe](/recipes/order-updates) with retries, idempotency, and the webhook that closes the loop.
:::

::: card Errors
[Every code and reason](/api/errors) in one place, with what to do about each.
:::

:::


----------------------------------------------------------------------------
## Calls
URL: https://docs.amomic.in/api/calls
----------------------------------------------------------------------------

```endpoint
POST /api/v1/calls
```

Your agent picks up the phone and calls someone. The request returns in well under a second; the conversation takes minutes. Everything about using this endpoint follows from that gap.

## When you use this

A call is the right tool when the answer needs a person's attention *now* and a message would sit unread — a failed payment on a delivery in progress, a high-value cart that stalled at checkout, an appointment that needs confirming today, a lead that filled a form ninety seconds ago. Your CRM or workflow engine already knows the moment; this endpoint is the trigger.

The whole surface is three endpoints:

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/v1/calls` | Place a call. Returns while the phone is still ringing. |
| `GET` | `/api/v1/calls/{call_id}` | Read the current state and, once it is over, the outcome. |
| `POST` | `/api/v1/calls/{call_id}/hangup` | End a call that is ringing or in progress. |

All three require the `calls:write` scope — including the read, since there is no separate read scope for calls. See [Scopes](/api/scopes).

There is no list endpoint. You cannot enumerate calls over the API; you track the `call_id` values you created, or you consume the `call.started` and `call.ended` [webhooks](/webhooks/events).

::: warning 201 means ringing, not connected
This is the single most important thing on the page. A `201` tells you the carrier accepted the call and the destination handset is ringing. It does not mean anyone answered, and it does not mean the conversation went well. `duration_seconds`, `outcome`, `started_at`, and `ended_at` are all `null` in the create response, by definition — the call has not happened yet.
:::

```mock
{"component": "CallSequenceDiagram", "props": {"caption": "Your request returns at the third step. Everything the customer actually experiences happens afterwards, and reaches you through GET /calls/{id} or the call.ended webhook."}}
```

## Parameters

```params
[
  {"name": "to", "type": "string", "required": true, "description": "The number to call. 6–20 characters, digits with an optional leading <code>+</code> — pattern <code>^\\+?\\d+$</code>. Must contain at least 8 digits once normalised."},
  {"name": "agent_id", "type": "string", "required": false, "default": "null", "description": "Maximum 64 characters. An <em>assertion</em>, not a selector — see below. Omit it and the agent deployed to the caller-ID number answers."},
  {"name": "from_number", "type": "string", "required": false, "default": "null", "description": "Maximum 20 characters. The caller-ID number the customer sees, which must be an active number owned by this workspace. Omit and the workspace's first active number is used."},
  {"name": "purpose", "type": "string", "required": false, "default": "null", "description": "Maximum 500 characters. Why you are calling, in plain language. Reaches the agent's opening line and system prompt."},
  {"name": "ring_seconds", "type": "integer", "required": false, "default": 30, "description": "How long to let the destination ring before giving up. Minimum 10, maximum 90."},
  {"name": "metadata", "type": "object", "required": false, "default": "{}", "description": "Free-form key/value object stored on the call record. Carry your own lead id or ticket reference here. Not spoken, not returned in the response."}
]
```

There is no `channel` field. Voice is the only dialable channel, and it is resolved for you.

### The agent comes from the number, not from `agent_id`

This trips up everyone once, so it is worth being blunt about.

A phone number in your workspace has exactly one agent deployed to it. When you place a call, the caller-ID number is resolved first — from `from_number` if you supplied one, otherwise the workspace's first active number — and **the agent deployed to that number is the agent that speaks**. `agent_id` does not choose anything.

What `agent_id` does is assert your expectation. If you pass one and it does not match the agent actually deployed to that number, the call is refused with `412 failed_precondition` and this `details` object:

```json title="error.details on a 412"
{
  "reason": "agent_number_mismatch",
  "deployed_agent_id": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4"
}
```

That is the point of the field. If your system cares which agent talks to a customer — and for anything money-adjacent it should — pass both `from_number` and `agent_id` together. Then a deployment change made in the console on a Tuesday afternoon turns into a loud 412 in your logs instead of the wrong agent quietly having the wrong conversation. `details.deployed_agent_id` tells you what is actually there.

To route to a different agent, call from a different number. One number, one agent.

### What `purpose` does

`purpose` is free text, up to 500 characters, and it reaches the agent as the reason for the call. It shapes the opening line and is added to the system prompt for the rest of the conversation. It is also stored on the call record.

Write it as an instruction to a colleague, not as a script:

```json
{ "purpose": "Confirm Asha's dental appointment on Tuesday 3 October at 4pm, and offer to reschedule if it does not suit." }
```

Two things it is not. It is not the greeting — the opening line is a fixed template that identifies your business, discloses that the caller is a virtual assistant, and asks whether now is a good time, in that order. And it is not the agent's knowledge; the agent still answers from the knowledge base bound to it. `purpose` sets the errand, nothing else.

::: note The inbound greeting is deliberately not used
Whatever greeting your number uses for inbound calls is discarded on an outbound call. "Thank you for calling" is wrong when you did the calling. [Outbound calls](/channels/outbound-calls) covers the opening in full, including the Hindi and Hinglish variants.
:::

### `ring_seconds`

Bounded to 10–90, default 30. Below 10 the destination often has not finished routing to the handset; above 90 you are burning a concurrency slot on someone who is not going to answer. A call that rings out never reaches the agent and finalises with a zero duration and a `no_answer`-family outcome.

## Example

Placing a call the moment a high-value cart is abandoned.

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/calls \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cart-88213-recovery" \
  -d '{
    "to": "+919876543210",
    "from_number": "+912269850800",
    "agent_id": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4",
    "purpose": "Rohit left a ₹42,000 order at checkout twenty minutes ago. Ask if he hit a payment problem and offer to complete the order over the phone.",
    "ring_seconds": 40,
    "metadata": { "cart_id": "88213", "value_inr": 42000 }
  }'
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";

async function callAboutCart(cart) {
  const response = await fetch(`${BASE}/calls`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `cart-${cart.id}-recovery`,
    },
    body: JSON.stringify({
      to: `+${cart.customerPhone.replace(/\D/g, "")}`,
      from_number: process.env.AMOMIC_CALLER_ID,
      agent_id: process.env.AMOMIC_SALES_AGENT_ID,
      purpose:
        `${cart.customerName} left a ₹${cart.value} order at checkout twenty minutes ago. ` +
        `Ask if they hit a payment problem and offer to complete the order over the phone.`,
      ring_seconds: 40,
      metadata: { cart_id: cart.id, value_inr: cart.value },
    }),
  });

  const payload = await response.json();
  if (!response.ok) {
    const { code, message, details } = payload.error;
    // 412 and 403 are configuration problems: alert, do not retry.
    throw new Error(`${code}/${details.reason ?? "-"}: ${message}`);
  }

  // payload.status is "ringing". The conversation has not happened yet.
  await db.carts.update(cart.id, { amomicCallId: payload.call_id });
  return payload.call_id;
}
```

```python Python
import os, re, httpx

BASE = "https://services.amomic.in/api/v1"


def call_about_cart(cart) -> str:
    response = httpx.post(
        f"{BASE}/calls",
        headers={
            "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
            "Idempotency-Key": f"cart-{cart.id}-recovery",
        },
        json={
            "to": "+" + re.sub(r"\D", "", cart.customer_phone),
            "from_number": os.environ["AMOMIC_CALLER_ID"],
            "agent_id": os.environ["AMOMIC_SALES_AGENT_ID"],
            "purpose": (
                f"{cart.customer_name} left a ₹{cart.value} order at checkout twenty "
                "minutes ago. Ask if they hit a payment problem and offer to complete "
                "the order over the phone."
            ),
            "ring_seconds": 40,
            "metadata": {"cart_id": cart.id, "value_inr": cart.value},
        },
        timeout=30.0,
    )
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{error['code']}/{error['details'].get('reason', '-')}: {error['message']}")

    call = response.json()          # call["status"] == "ringing"
    db.carts.update(cart.id, amomic_call_id=call["call_id"])
    return call["call_id"]
```

:::

`POST /calls` honours `Idempotency-Key`, and you should always send one. A retry after a timeout replays the stored 201 rather than dialling the customer twice — which, unlike a duplicate message, is a phone ringing in someone's pocket for a second time. See [Idempotency](/api/idempotency).

## Response

```json title="201 Created"
{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "ringing",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4",
  "duration_seconds": null,
  "outcome": null,
  "summary": null,
  "recording_uri": null,
  "started_at": null,
  "ended_at": null
}
```

Store `call_id`. It is the only handle you get, and there is no way to look a call up by phone number or by your own metadata.

---

```endpoint
GET /api/v1/calls/{call_id}
```

Read the current state of one call. Scope `calls:write`. No query parameters.

The same object shape is used for the create response and this one; on create only the first six fields are populated.

| Field | Type | Notes |
|---|---|---|
| `call_id` | string | `call_…`. The id you were given at create. |
| `status` | string | Where the call is in its lifecycle. Open vocabulary — see below. |
| `direction` | string | `outbound` for calls you placed. Falls back to `outbound` when unset. |
| `to` | string \| null | The number called. For an inbound call this is the caller's number. |
| `from_number` | string \| null | The caller-ID number the call went out on. |
| `agent_id` | string \| null | The agent that handled the call. |
| `duration_seconds` | integer \| null | Connected duration. `null` until the call finalises; `0` for a call that was never answered. |
| `outcome` | string \| null | Why the call ended. `null` while it is live. This is the field to branch on. |
| `summary` | string \| null | Present in the schema, but not populated today. Do not build on it. |
| `recording_uri` | string \| null | Set only when recording is enabled for that number's deployment. It is a storage reference, not a ready-to-play link — play recordings from the console. |
| `started_at` | string \| null | ISO 8601 with offset, for example `2026-08-01T10:00:00.123456+00:00`. |
| `ended_at` | string \| null | Same format. `null` while the call is live. |

```json title="200 OK — after the call finished"
{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "completed",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4",
  "duration_seconds": 96,
  "outcome": "caller_hangup",
  "summary": null,
  "recording_uri": null,
  "started_at": "2026-08-01T10:00:04.812311+00:00",
  "ended_at": "2026-08-01T10:01:40.930118+00:00"
}
```

A `call_id` that does not exist — or belongs to another workspace, which is answered identically on purpose — returns `404 not_found` with the message `Call not found.`

### Do not switch exhaustively on `status`

`status` is typed as a plain string. **No closed enum is declared, so no closed list is published.** New lifecycle states can appear without a version bump, and code that throws on an unrecognised value will eventually throw in production at 3 a.m.

The values you will commonly see on an API-placed call are `ringing`, `in_progress`, `completed`, and `failed`. Treat those as the known cases and give yourself a default branch:

```javascript
switch (call.status) {
  case "ringing":
  case "in_progress":
    return "live";
  case "completed":
    return "done";
  case "failed":
    return "failed";
  default:
    // Unknown state — log it, treat as live, poll again.
    log.warn({ call_id: call.call_id, status: call.status }, "unknown call status");
    return "live";
}
```

The field that actually tells you what happened is `outcome`, and it is only meaningful once the call has ended:

| `outcome` | What it means |
|---|---|
| `caller_hangup` | The person you called ended the call. The default for a normal conversation. |
| `agent_hangup` | The agent decided the conversation was finished and ended it. |
| `idle` | Silence on the line past the idle threshold; the agent said goodbye and hung up. |
| `max_duration` | The call hit the configured time cap. |
| `no_answer` | Rang out, or the destination could not be classified more precisely. |
| `busy` | The destination was busy. |
| `rejected` | The destination actively declined the call. |
| `invalid_number` | The number does not exist on the network. |
| `unreachable` | The destination could not be reached — out of coverage or unallocated. |
| `congestion` | The network refused the call for capacity reasons. |
| `suspended` | The workspace is billing-suspended; the call was answered only to say so. |
| `setup_error` | Media setup failed after the call was answered. |
| `originate_error` | The carrier refused to place the call at all. |

Unanswered calls finalise as `status: "completed"` with `duration_seconds: 0` and one of the network outcomes above. A `completed` status therefore does not mean the conversation happened — check `duration_seconds` and `outcome` together.

### Getting the outcome: poll, or subscribe

**Subscribe.** Register a webhook for `call.ended` and you get pushed `call_id`, `duration_seconds`, `outcome`, `direction`, and `to` the moment the call finalises. This is the right answer for anything that needs to react — updating a CRM, opening a ticket, scheduling a retry. There is a matching `call.started` event. See [Event reference](/webhooks/events) and remember that delivery is at-least-once, so dedupe on the event id.

**Poll.** If you cannot receive webhooks, `GET /calls/{call_id}` works, but poll like an adult: wait `ring_seconds` before your first read, then check every few seconds, and stop as soon as `ended_at` is non-null. Every poll spends one of your 120 requests per minute, and a tight loop across a batch of calls will hit the [rate limit](/api/rate-limits) long before the calls finish.

```python
import time, httpx

def wait_for_outcome(call_id: str, headers: dict, ring_seconds: int = 30, timeout_s: int = 900):
    time.sleep(ring_seconds)                       # nothing to see before this
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        call = httpx.get(f"{BASE}/calls/{call_id}", headers=headers).json()
        if call["ended_at"] is not None:
            return call
        time.sleep(5)
    raise TimeoutError(f"{call_id} did not finalise within {timeout_s}s")
```

---

```endpoint
POST /api/v1/calls/{call_id}/hangup
```

End a call you placed. Scope `calls:write`. No request body.

```bash
curl -X POST https://services.amomic.in/api/v1/calls/call_01JQRS4T8XZ0AB1CD2EF3GH4/hangup \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{ "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4", "ended": true }
```

`ended` is `true` when the call was ringing or in progress and has now been torn down. It is `false` when the call was already over — which is a normal, successful answer, not an error. Hangup is safe to call repeatedly; the second call simply reports `ended: false`.

An unknown `call_id` returns `404 not_found` with `Call not found.`

Use it when your own system learns the call is pointless mid-flight — the customer just completed the payment in another tab, the ticket was resolved by someone else, or your operator cancelled the campaign.

## Failures

Guards run in this order, and the first one that trips is the error you get. That order is why a suspended workspace reports suspension rather than a caller-ID problem it never got as far as checking.

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "The destination has fewer than 8 digits — message `That destination number is too short.` Also covers request-validation failures such as a bad `to` pattern or `ring_seconds` outside 10–90."},
  {"status": 400, "code": "invalid_argument", "reason": "self_dial", "description": "The destination is one of this workspace's own numbers. Calling yourself would connect the agent to the agent."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, invalid, revoked, expired after a roll, or used against the wrong host. `details.reason` distinguishes all six."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `calls:write`. Required for placing, reading, and hanging up."},
  {"status": 403, "code": "permission_denied", "reason": "unknown_from_number", "description": "The `from_number` you asked for is not an active number in this workspace."},
  {"status": 403, "code": "permission_denied", "reason": "", "description": "The number belongs to another workspace."},
  {"status": 404, "code": "not_found", "reason": "", "description": "`Call not found.` — from `GET /calls/{id}` and hangup, for an unknown id or a call owned by another workspace."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "The same `Idempotency-Key` was already used with a different request body."},
  {"status": 412, "code": "failed_precondition", "reason": "voice_not_configured", "description": "Voice is not configured on this deployment. Nothing you can fix in the request."},
  {"status": 412, "code": "failed_precondition", "reason": "workspace_suspended", "description": "The workspace is billing-suspended. Outbound calling stops before anything is dialled."},
  {"status": 412, "code": "failed_precondition", "reason": "no_phone_number", "description": "The workspace owns no phone number to call from. Request a number in the console first."},
  {"status": 412, "code": "failed_precondition", "reason": "no_agent_deployed", "description": "The caller-ID number exists but has no agent deployed to it. A number without a deployment cannot talk."},
  {"status": 412, "code": "failed_precondition", "reason": "agent_number_mismatch", "description": "Your `agent_id` is not the agent deployed to that number. `details.deployed_agent_id` names the one that is."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_channel", "description": "Outbound calling is not available on this deployment at all. `details.supported` lists what is."},
  {"status": 429, "code": "rate_limited", "reason": "call_concurrency", "description": "This workspace already has 10 calls in progress. `details.limit` is 10. Separate from the per-key request limit."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests per minute per API key exceeded."},
  {"status": 500, "code": "internal", "reason": "originate_failed", "description": "The carrier accepted the request and then failed to place the call. Retryable with a fresh `Idempotency-Key`."}
]
```

### Two different 429s

They mean opposite things and want opposite responses.

- `reason: "rate_limited"` — you are calling the *API* too fast. 120 requests per minute per key. Slow your loop down.
- `reason: "call_concurrency"` — you are calling *people* too fast. A workspace runs at most 10 live calls at once. Your loop is fine; your queue drain rate is not. Wait for calls to end, or spread the batch over time.

There is no `Retry-After` header on either. Neither is a bug in your request.

### The 412 family is configuration, not weather

`voice_not_configured`, `workspace_suspended`, `no_phone_number`, `no_agent_deployed`, `agent_number_mismatch`, and `unsupported_channel` will all return exactly the same result if you retry in ten seconds. Do not put them behind a backoff. Page someone, or fail the job with the reason attached — the fix is always in the console.

::: danger You own outbound compliance
Amomic-AI places the call you ask for. It does not check the destination against any do-not-call or preference registry, does not enforce calling hours, and does not cap calls per recipient per day. Those rules apply to you as the caller. Build the checks into the system that decides whom to call, before you reach this endpoint.
:::

## Related

::: cards

::: card Outbound calls, in depth
[How the agent opens the call](/channels/outbound-calls), what the customer hears first, and what changes versus an inbound call.
:::

::: card Trigger a call from your CRM
[The full recipe](/recipes/crm-call) — trigger, idempotency, webhook, and writing the outcome back.
:::

::: card Numbers and KYC
[Getting a number](/channels/phone-numbers) you can call from, and the compliance review that gates it.
:::

::: card Call events
[`call.started` and `call.ended`](/webhooks/events) — the push alternative to polling.
:::

:::


----------------------------------------------------------------------------
## Conversations
URL: https://docs.amomic.in/api/conversations
----------------------------------------------------------------------------

```endpoint
GET /api/v1/conversations
```

Every exchange between a customer and one of your agents — web chat, WhatsApp, a phone call — becomes a conversation. These three endpoints are how your own systems read them.

## When you use this

Three shapes of work send people here. You are **syncing** conversations into a warehouse or a CRM so support volume shows up next to revenue. You are **enriching** a record — a ticket, a lead, an account — with what was actually said. Or you are **auditing**, because someone asked what the agent told a customer on Tuesday and "check the inbox" is not an acceptable answer at scale.

The surface is read-only and deliberately small:

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/v1/conversations` | List conversations, newest activity first. |
| `GET` | `/api/v1/conversations/{conversation_id}` | Read one conversation's summary record. |
| `GET` | `/api/v1/conversations/{conversation_id}/messages` | Read the transcript, oldest turn first. |

All three require the `conversations:read` scope, which is one of the two scopes a new key gets by default. See [Scopes](/api/scopes).

There is no way to create a conversation, post into one, close one, or delete one over this API. Replying is what a deployed agent does; the API reads.

## Listing conversations

```params
[
  {"name": "limit", "type": "integer", "required": false, "default": 25, "description": "How many conversations to return. Minimum 1, maximum 100."},
  {"name": "cursor", "type": "string", "required": false, "default": "null", "description": "The <code>next_cursor</code> from the previous page. Omit for the first page."},
  {"name": "agent_id", "type": "string", "required": false, "default": "null", "description": "Return only conversations handled by this agent. Get ids from <a href=\"/api/discovery\">GET /agents</a>."}
]
```

Conversations come back ordered by **most recent activity first** — newest `updated_at` at the top. That ordering is what makes an incremental sync possible, and it is also what makes a naive full walk unstable: a conversation that receives a new message while you are paginating moves to the front, behind your cursor.

::: codegroup

```bash cURL
curl -G https://services.amomic.in/api/v1/conversations \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "agent_id=wgt_01JQRS4T8XZ0AB1CD2EF3GH4"
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";

const params = new URLSearchParams({ limit: "50", agent_id: agentId });
const response = await fetch(`${BASE}/conversations?${params}`, {
  headers: { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` },
});

const { items, next_cursor } = await response.json();
```

```python Python
import os, httpx

BASE = "https://services.amomic.in/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"}

page = httpx.get(
    f"{BASE}/conversations",
    headers=HEADERS,
    params={"limit": 50, "agent_id": agent_id},
).json()

items, next_cursor = page["items"], page["next_cursor"]
```

:::

```json title="200 OK"
{
  "items": [
    {
      "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
      "channel": "whatsapp",
      "agent_id": "wgt_01JQRS4T8XZ0AB1CD2EF3GH4",
      "status": "open",
      "customer": {
        "display_name": "Asha Menon",
        "email": "asha.menon@example.in"
      },
      "message_count": 12,
      "preview": "Thanks — that answers it. I'll wait for the courier update.",
      "created_at": "2026-08-01T09:41:18.220914+00:00",
      "updated_at": "2026-08-01T10:02:55.118307+00:00"
    }
  ],
  "next_cursor": "2026-08-01T10:02:55.118307+00:00"
}
```

### The conversation object

| Field | Type | Notes |
|---|---|---|
| `conversation_id` | string | `con_…`. The handle for the other two endpoints. |
| `channel` | string | Where the conversation happened — `web`, `whatsapp`, or `voice`. Falls back to `web` when unset. |
| `agent_id` | string \| null | The agent that handled it. |
| `status` | string | Lifecycle state, defaulting to `open`. Conversations stay open until a member closes them in the inbox — there is no session timeout that closes them for you. |
| `customer` | object | Free-form. Populated from whatever identity the channel gave you. Observed keys include `name`, `display_name`, `email`, and `external_id`. Treat every key as optional. |
| `message_count` | integer | Turns in the transcript, defaulting to `0`. Counts customer and agent turns only — see below. |
| `preview` | string \| null | The first 140 characters of the last real message. Enough to render a list row without a second request. |
| `created_at` | string \| null | ISO 8601 with offset, for example `2026-08-01T09:41:18.220914+00:00`. |
| `updated_at` | string \| null | Same format. Also, literally, the value used as the list cursor. |

Nothing else is returned. Internal routing fields exist on the record and are deliberately not projected — if you need to correlate a conversation with something in your own system, do it through `customer`, or through the `conversation.started` [webhook](/webhooks/events) at the moment the conversation begins.

::: note `customer` is as good as the channel it came from
On WhatsApp you get an identity from the platform. On web chat you get whatever the lead form collected — and nothing at all if the visitor never filled one in. On voice you get the caller's number. Write your code so an empty `customer` object is an ordinary case, not an exception.
:::

## Reading one conversation

```endpoint
GET /api/v1/conversations/{conversation_id}
```

Returns exactly one conversation object, same shape as a list item. No query parameters.

```bash
curl https://services.amomic.in/api/v1/conversations/con_01JQRS4T8XZ0AB1CD2EF3GH4 \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

An id that does not exist, or one that belongs to a different workspace, returns the same `404` with the message `Conversation not found.` The two cases are indistinguishable on purpose: telling you that an id exists but is not yours would leak the existence of other workspaces' data.

## Reading the transcript

```endpoint
GET /api/v1/conversations/{conversation_id}/messages
```

```params
[
  {"name": "limit", "type": "integer", "required": false, "default": 100, "description": "How many messages to return. Minimum 1, maximum 200."},
  {"name": "cursor", "type": "string", "required": false, "default": "null", "description": "The <code>next_cursor</code> from the previous page — a <code>message_id</code>. Omit for the first page."}
]
```

Messages come back **oldest first**, which is reading order. Paginating forward walks the conversation from its beginning to its end.

```json title="200 OK"
{
  "items": [
    {
      "message_id": "msg_01JQRS4T8XZ0AB1CD2EF3GH4",
      "role": "user",
      "text": "My order AM-4821 hasn't arrived and the tracking hasn't moved since Tuesday.",
      "created_at": "2026-08-01T09:41:18.220914+00:00"
    },
    {
      "message_id": "msg_01JQRS4T8XZ0AB1CD2EF3GH5",
      "role": "model",
      "text": "I can see AM-4821 left our Pune warehouse on Tuesday evening. Let me check the courier status for you.",
      "created_at": "2026-08-01T09:41:23.884120+00:00"
    }
  ],
  "next_cursor": null
}
```

| Field | Type | Notes |
|---|---|---|
| `message_id` | string | `msg_…`. Time-ordered, so sorting by it is sorting chronologically. Also the pagination cursor. |
| `role` | string | `user` or `model`. Nothing else — see below. Defaults to `user` when unset. |
| `text` | string \| null | The turn's text. `null` for a turn with no text representation. |
| `created_at` | string \| null | ISO 8601 with offset. |

Message `metadata` is not exposed. Neither are the knowledge sources behind an answer.

### Only two roles, and why

Internally a conversation carries a third kind of entry: an operational trail of what the agent was doing between turns — looking something up, running a tool, playing a hold line on a call. Your staff see it in the inbox as a dashed rail, because when an answer looks wrong that trail is how you find out why.

The public transcript filters those rows out. What you get is `user` and `model` turns: what the customer said and what the agent said back. `message_count` on the conversation object excludes them too, so the count matches the number of items you can page through.

That is the right default for a transcript you are storing, showing to a customer, or feeding to your own analytics — the trail is diagnostic detail, not conversation. It also means you should not expect the API transcript to be character-identical to the inbox view.

### A bad id is a 404, not an empty page

The messages endpoint loads the conversation before it loads any messages. A `conversation_id` that does not exist, or belongs to another workspace, returns `404 not_found` with `Conversation not found.` — never `200` with an empty `items` array.

This matters more than it looks. An empty page from a mistyped id is the kind of bug that silently produces an empty report for three weeks. Here, a typo fails on the first call.

An empty `items` array therefore means exactly one thing: this conversation genuinely has no messages yet.

## Pagination

Both list endpoints use the same envelope:

```json
{ "items": [ … ], "next_cursor": "…" }
```

The rule is short and worth internalising: **`next_cursor` is non-null only when the page came back full.** A page with fewer items than your `limit` ends the walk. There is no total count, no `has_more`, no page numbers, and no cursor for going backwards.

```python
def walk(path: str, params: dict | None = None):
    params = dict(params or {})
    while True:
        page = httpx.get(f"{BASE}{path}", headers=HEADERS, params=params).json()
        yield from page["items"]
        if not page["next_cursor"]:
            return
        params["cursor"] = page["next_cursor"]
```

Treat the cursor as opaque and pass it back unmodified. Do not construct one, do not parse one, and do not persist one as a long-lived bookmark — persist a timestamp from the data instead, which is what the sync below does. [Pagination](/api/pagination) covers the envelope in full.

## Worked example: sync new conversations since the last run

The job you will actually write. It runs on a schedule, pulls only what changed, and is safe to run twice.

The mechanism: conversations are ordered by `updated_at` descending, so a fresh walk from page one gives you the most recently active first. Keep a **watermark** — the highest `updated_at` you have processed — and stop walking the moment you reach a conversation at or below it. Everything after that point you have already seen.

::: codegroup

```python Python
import os, httpx

BASE = "https://services.amomic.in/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"}


def sync_since(watermark: str | None) -> str | None:
    """Pull conversations updated since `watermark`. Returns the new watermark."""
    cursor, newest, done = None, watermark, False

    while not done:
        page = httpx.get(
            f"{BASE}/conversations",
            headers=HEADERS,
            params={"limit": 100, **({"cursor": cursor} if cursor else {})},
            timeout=30.0,
        )
        page.raise_for_status()
        body = page.json()

        for conversation in body["items"]:
            updated = conversation["updated_at"]
            if watermark and updated is not None and updated <= watermark:
                done = True          # ordered desc — everything after this is old
                break

            store_conversation(conversation)
            store_transcript(conversation["conversation_id"])

            if updated is not None and (newest is None or updated > newest):
                newest = updated

        if not body["next_cursor"]:
            break
        cursor = body["next_cursor"]

    return newest


def store_transcript(conversation_id: str) -> None:
    cursor = None
    while True:
        page = httpx.get(
            f"{BASE}/conversations/{conversation_id}/messages",
            headers=HEADERS,
            params={"limit": 200, **({"cursor": cursor} if cursor else {})},
            timeout=30.0,
        ).json()
        upsert_messages(conversation_id, page["items"])   # keyed on message_id
        if not page["next_cursor"]:
            return
        cursor = page["next_cursor"]
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };

async function syncSince(watermark) {
  let cursor = null;
  let newest = watermark;
  let done = false;

  while (!done) {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(`${BASE}/conversations?${params}`, { headers: HEADERS });
    if (!response.ok) throw new Error((await response.json()).error.message);
    const { items, next_cursor } = await response.json();

    for (const conversation of items) {
      const updated = conversation.updated_at;
      if (watermark && updated && updated <= watermark) {
        done = true; // ordered desc — the rest is already synced
        break;
      }
      await storeConversation(conversation);
      await storeTranscript(conversation.conversation_id);
      if (updated && (!newest || updated > newest)) newest = updated;
    }

    if (!next_cursor) break;
    cursor = next_cursor;
  }

  return newest;
}
```

:::

Four details that make it correct rather than nearly correct:

- **Upsert on `message_id`, do not append.** A conversation you synced yesterday can gain turns today and will come back again. The message ids are stable, so an upsert makes the whole job idempotent.
- **Re-read the transcript for any conversation that moved.** `updated_at` changed because something was said; you do not know which turn without reading.
- **Keep the watermark strictly from the data**, not from your own clock. Timestamps here are server-side; your clock is not.
- **Compare timestamps as strings only if they are the same shape.** These are ISO 8601 with an offset and microseconds, all in `+00:00`, so lexical comparison works. If you touch them at all, parse them properly.

If you need conversations the moment they happen rather than on a schedule, `conversation.started` and `conversation.ended` [webhooks](/webhooks/events) push instead. The usual production shape is both: webhooks for reaction, this sync for completeness.

## Failures

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Request validation failed — a `limit` outside its bounds is the usual cause. `details.errors` names the parameter."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, invalid, revoked, expired after a roll, or used against the wrong host. `details.reason` distinguishes all six."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `conversations:read`. `details.required_scope` names it."},
  {"status": 404, "code": "not_found", "reason": "", "description": "`Conversation not found.` — the id does not exist or belongs to another workspace. Returned by both the single-conversation and messages endpoints."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_resource", "description": "Conversations are not available on this deployment. A configuration state, not a transient one — do not retry."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests per minute per API key exceeded. A full-history backfill will hit this; pace the walk."}
]
```

::: tip Backfills need pacing
A first-run backfill of a busy workspace makes one request per page of conversations plus one per page of transcript. At 120 requests per minute per key that is the constraint you will meet first. Sleep between pages, or give the backfill its own API key so it cannot starve your production traffic. See [Rate limits](/api/rate-limits).
:::

## Related

::: cards

::: card Pagination
[The cursor contract](/api/pagination) in full — when `next_cursor` is set and why a short page ends the walk.
:::

::: card Sync conversations
[The complete recipe](/recipes/sync-conversations), including scheduling, retries, and where webhooks fit.
:::

::: card Conversations and contacts
[The model behind the data](/concepts/conversations) — what a conversation is, and how customers are identified across channels.
:::

::: card Webhook events
[`conversation.started` and `conversation.ended`](/webhooks/events) for reacting in real time instead of polling.
:::

:::


----------------------------------------------------------------------------
## Tickets
URL: https://docs.amomic.in/api/tickets
----------------------------------------------------------------------------

```endpoint
POST /api/v1/tickets
```

A ticket is work for a human. This endpoint creates one from your side of the wall, and gives you back a reference you can quote to the customer.

## When you use this

Two situations, mostly. Something in **your** system failed in a way that needs a person — a payment reconciliation mismatch, a fulfilment exception, a KYC document that will not validate. Or your own product has a "contact support" form and you want it to land in the same queue your agents feed, rather than in a shared mailbox nobody owns.

Note what does *not* need this endpoint: your agent opening a ticket mid-conversation. That already happens on its own when a customer asks for a human or hits something the agent cannot resolve. Use the API for tickets that originate in your systems.

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/api/v1/tickets` | Create a ticket. |
| `GET` | `/api/v1/tickets/{ticket_id}` | Read one back. |

::: warning Reading a ticket needs `tickets:write`
There is no `tickets:read` scope. `GET /tickets/{ticket_id}` is gated by `tickets:write`, the same scope that creates them. A key that only needs to look tickets up still has to be able to create them — size your keys accordingly and see [Scopes](/api/scopes).
:::

There is no list endpoint, no update endpoint, and no way to add a comment or change status over the API. Once a ticket exists it belongs to your team in the console.

## Parameters

```params
[
  {"name": "subject", "type": "string", "required": true, "description": "One-line summary. 1–240 characters. This is what your team sees in the queue — make it specific enough to triage without opening."},
  {"name": "description", "type": "string", "required": true, "description": "The full detail. 1–8000 characters. Include the identifiers your team will need: order ids, transaction references, error codes."},
  {"name": "priority", "type": "string", "required": false, "default": "normal", "enum": ["low", "normal", "high", "urgent"], "description": "Sets the response clock. See the SLA table below."},
  {"name": "requester_name", "type": "string", "required": false, "default": "null", "description": "Maximum 120 characters. At least one of name, email, or phone is required."},
  {"name": "requester_email", "type": "string", "required": false, "default": "null", "description": "Maximum 200 characters."},
  {"name": "requester_phone", "type": "string", "required": false, "default": "null", "description": "Maximum 32 characters."},
  {"name": "tags", "type": "string[]", "required": false, "default": "[]", "description": "Up to 10 tags for filtering in the console. The tag <code>api</code> is added by the server on top of whatever you send."}
]
```

### At least one requester detail

A ticket with no requester is a ticket nobody can answer. The route enforces this before anything is written:

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Provide at least one requester detail (name, email, or phone).",
    "details": {},
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Any one of the three satisfies the rule. In practice send everything you have — a name alone tells your team who to look up, an email or phone tells them how to reach them.

Note this error carries no `details.reason`. Branch on `error.code` and the message here, not on a reason string.

### Priority sets a clock

`priority` is not decoration. `sla_due_at` is computed from it at creation:

| `priority` | `sla_due_at` |
|---|---|
| `urgent` | 2 hours after creation |
| `high` | 8 hours after creation |
| `normal` | 24 hours after creation |
| `low` | 72 hours after creation |

The clock is set **once, at creation**. A later priority change in the console does not recompute `sla_due_at` — so pass the right priority from your system, where you actually know how bad the failure is, rather than planning to fix it up afterwards.

Send only the four documented values. Anything else fails request validation with a `400`.

### Tags, and the one you did not send

Your tags come back with `api` appended:

```json
{ "tags": ["payments", "reconciliation"] }
```

```json title="on the created ticket"
{ "tags": ["payments", "reconciliation", "api"] }
```

That tag is how your team tells machine-created tickets from ones an agent or a member opened — useful the first time your integration misfires and files forty tickets at 2 a.m. It counts as one of the tags on the ticket, so plan for eleven where you sent ten.

## Example

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/tickets \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recon-2026-08-01-TXN88213" \
  -d '{
    "subject": "Payment captured but order not created — TXN88213",
    "description": "Reconciliation found a captured payment of ₹42,000 (TXN88213) at 09:14 IST with no matching order. Customer has been charged. Needs a manual order creation or a refund within the day.\n\nCustomer: Rohit Sharma\nCart: 88213\nGateway reference: pay_QK2mF9dV1xLp",
    "priority": "urgent",
    "requester_name": "Rohit Sharma",
    "requester_email": "rohit.sharma@example.in",
    "requester_phone": "+919876543210",
    "tags": ["payments", "reconciliation"]
  }'
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";

async function openReconciliationTicket(mismatch) {
  const response = await fetch(`${BASE}/tickets`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `recon-${mismatch.date}-${mismatch.txnId}`,
    },
    body: JSON.stringify({
      subject: `Payment captured but order not created — ${mismatch.txnId}`,
      description: mismatch.detail,
      priority: "urgent",
      requester_name: mismatch.customerName,
      requester_email: mismatch.customerEmail,
      requester_phone: mismatch.customerPhone,
      tags: ["payments", "reconciliation"],
    }),
  });

  const payload = await response.json();
  if (!response.ok) throw new Error(`${payload.error.code}: ${payload.error.message}`);

  // Quote public_ref to the customer; keep ticket_id for your own lookups.
  return { ref: payload.public_ref, id: payload.ticket_id };
}
```

```python Python
import os, httpx

BASE = "https://services.amomic.in/api/v1"


def open_reconciliation_ticket(mismatch) -> dict:
    response = httpx.post(
        f"{BASE}/tickets",
        headers={
            "Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}",
            "Idempotency-Key": f"recon-{mismatch.date}-{mismatch.txn_id}",
        },
        json={
            "subject": f"Payment captured but order not created — {mismatch.txn_id}",
            "description": mismatch.detail,
            "priority": "urgent",
            "requester_name": mismatch.customer_name,
            "requester_email": mismatch.customer_email,
            "requester_phone": mismatch.customer_phone,
            "tags": ["payments", "reconciliation"],
        },
        timeout=30.0,
    )
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{error['code']}: {error['message']}")

    ticket = response.json()
    return {"ref": ticket["public_ref"], "id": ticket["ticket_id"]}
```

:::

## Response

```json title="201 Created"
{
  "ticket_id": "tkt_4f9b21c7de03a85610bb47e2",
  "public_ref": "AM-20AB7B43",
  "subject": "Payment captured but order not created — TXN88213",
  "status": "new",
  "priority": "urgent",
  "tags": ["payments", "reconciliation", "api"],
  "requester": {
    "name": "Rohit Sharma",
    "email": "rohit.sharma@example.in",
    "phone": "+919876543210"
  },
  "sla_due_at": "2026-08-01T12:47:03.551204+00:00",
  "created_at": "2026-08-01T10:47:03.551204+00:00",
  "updated_at": "2026-08-01T10:47:03.551204+00:00"
}
```

The documented fields:

| Field | Type | Notes |
|---|---|---|
| `ticket_id` | string | `tkt_` followed by 24 hex characters. The id for `GET /tickets/{ticket_id}`. |
| `public_ref` | string | `AM-` followed by 8 uppercase hex characters, for example `AM-20AB7B43`. The reference to quote to a customer. |
| `subject` | string | As you sent it. |
| `status` | string | `new` on creation. Your team moves it through `open`, `pending`, `waiting_customer`, `resolved`, and `closed`. |
| `priority` | string | One of `low`, `normal`, `high`, `urgent`. |
| `tags` | string[] | Your tags plus `api`. |
| `requester` | object | The requester details you supplied — `name`, `email`, `phone`, each present only if you sent it. |
| `sla_due_at` | string \| null | ISO 8601 with offset. Derived from `priority` at creation and never recomputed. |
| `created_at` | string \| null | ISO 8601 with offset, for example `2026-08-01T10:47:03.551204+00:00`. |
| `updated_at` | string \| null | Same format. |

::: note Additional fields may be present
The response carries the ticket record, and that record holds more than the fields above — assignment, escalation bookkeeping, and internal bookkeeping among them. Those are not part of the documented API surface. They can change shape or disappear without notice, so read the fields in the table and ignore the rest. Do not write a strict schema validator that rejects unknown keys, and do not build logic on a field that is not listed here.
:::

### Two identifiers, two audiences

`ticket_id` (`tkt_…`) is the machine handle. It is what `GET /tickets/{ticket_id}` takes, and it is what you store next to your own record.

`public_ref` (`AM-XXXXXXXX`) is the human handle. Eight uppercase hex characters, short enough to read out over the phone and distinctive enough to search for. Put this one in your confirmation email, your status page, and your own UI. `AM-20AB7B43` in a support thread finds the ticket immediately; a 24-character hex string does not.

Both are stable for the life of the ticket, and both appear on the `ticket.created` and `ticket.updated` [webhooks](/webhooks/events).

## Reading a ticket back

```endpoint
GET /api/v1/tickets/{ticket_id}
```

Scope `tickets:write`. No query parameters. Returns the same object as the create response, with the current `status`, `priority`, `tags`, and `updated_at`.

```bash
curl https://services.amomic.in/api/v1/tickets/tkt_4f9b21c7de03a85610bb47e2 \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

The conversation on the ticket — staff replies, customer messages, internal notes — is **not** included. This endpoint returns the ticket record only; the thread lives in the console.

An unknown id, or one belonging to another workspace, returns `404 not_found` with `Ticket not found.`

For reacting to progress, prefer the `ticket.updated` webhook over polling. It carries `ticket_id`, `public_ref`, `subject`, `status`, `priority`, and `channel`, which is usually the whole of what a status-sync needs.

## Deduplication

This endpoint deduplicates twice over, and understanding which mechanism is doing the work saves you a confusing afternoon.

**With an `Idempotency-Key` header.** Standard behaviour: the stored 201 is replayed for 24 hours, scoped to your workspace, your API key, and this endpoint. Reusing a key with a different body is a `409 idempotency_key_reuse`. See [Idempotency](/api/idempotency).

**Without one.** Tickets still deduplicate — on a hash of the raw request body. An identical body sent twice converges on the same ticket instead of opening a second one. The ticket id is derived from that hash, which is why `tkt_…` is a hash rather than a time-ordered id.

The consequence, stated plainly:

```javascript
// Retried three times by your job runner after a timeout.
// Byte-identical body each time → one ticket, returned three times.
await createTicket({ subject, description, priority: "urgent", requester_email: email });

// Same incident, description regenerated with a new timestamp inside it.
// Different bytes → THREE tickets.
await createTicket({ subject, description: `${detail} (checked ${new Date()})`, ... });
```

The hash covers the raw bytes. Whitespace, key order, and a timestamp buried in the description all make a body different. That is why the `Idempotency-Key` header is still the right tool: it lets *you* declare what "the same request" means — one key per incident, per order, per reconciliation run — instead of relying on your serialiser producing identical bytes.

::: tip Key on the event, not on the moment
`recon-2026-08-01-TXN88213` is a good key: it names the thing that went wrong, so every retry and every re-run of the day's reconciliation converges on one ticket. `ticket-${Date.now()}` is not a key at all.
:::

## Failures

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "`Provide at least one requester detail (name, email, or phone).` — no name, email, or phone was supplied."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Request validation failed — an empty `subject` or `description`, a `subject` over 240 or `description` over 8000 characters, more than 10 tags, or a `priority` outside the four values. `details.errors` names the field."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, invalid, revoked, expired after a roll, or used against the wrong host. `details.reason` distinguishes all six."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `tickets:write` — required for creating *and* reading."},
  {"status": 404, "code": "not_found", "reason": "", "description": "`Ticket not found.` — unknown id, or a ticket belonging to another workspace."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "The same `Idempotency-Key` was already used with a different request body."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_resource", "description": "Tickets are not available on this deployment. Configuration, not a transient failure — do not retry."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests per minute per API key exceeded."}
]
```

## Related

::: cards

::: card Escalate to a ticket
[The complete recipe](/recipes/support-escalation) — deciding when to open one, and closing the loop with the `ticket.updated` webhook.
:::

::: card Ticket events
[`ticket.created` and `ticket.updated`](/webhooks/events) push status changes to you instead of you polling.
:::

::: card Idempotency
[How keys are scoped](/api/idempotency), how long they live, and what a replayed response looks like.
:::

::: card Errors
[Every code and reason](/api/errors) in one place.
:::

:::


----------------------------------------------------------------------------
## Contacts
URL: https://docs.amomic.in/api/contacts
----------------------------------------------------------------------------

```endpoint
POST /api/v1/contacts
```

Your CRM has a customer. Our inbox has a person who messaged on WhatsApp. This endpoint is how you assert that they are the same human, so that when a conversation opens your team sees a name rather than a phone number.

It requires the `contacts:write` scope and returns `201`.

## What it does

It is an **upsert**, not a create. Every request is resolved against the existing directory before anything is written:

1. If the `email` you sent matches an existing contact, that contact is updated with whatever else you sent.
2. Otherwise, if the `phone` you sent matches an existing contact, that one is updated.
3. If neither matches, a new contact is created.

There is exactly one way for that to fail on identity, and it is the case where your two identifiers disagree with each other. That is [`identity_conflict`](#when-your-identifiers-disagree) below.

The practical consequence: **sending the same body twice is safe and produces one contact.** You do not need to check whether a contact exists before calling, and you do not need to remember what you sent last time.

## Parameters

```params
[
  {"name": "name", "type": "string", "required": false, "description": "The person's name, up to 120 characters. Never used for matching — a request carrying only a name is rejected. Sent alone with an identifier, it fills in or updates the display name."},
  {"name": "email", "type": "string", "required": false, "description": "Up to 200 characters. <strong>Normalised before matching</strong>: trimmed and case-folded, so <code>Asha.Menon@Example.IN</code> and <code>asha.menon@example.in</code> resolve to the same contact. The first identifier tried."},
  {"name": "phone", "type": "string", "required": false, "description": "Up to 32 characters. The second identifier tried, used only when <code>email</code> matched nothing. No format is enforced here — see the note below."}
]
```

::: warning At least one of `email` or `phone` is required
A request with only a `name` — or with no fields at all — is rejected before any lookup happens:

```json
{
  "error": {
    "code": "invalid_argument",
    "message": "Provide an email or a phone number.",
    "details": {},
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Note the empty `details` — this rejection carries no `reason`, so read `details.reason` defensively as always. The reasoning is straightforward: a name is not an identity. "Asha Menon" matches nothing, so a name-only upsert could only ever create rows, and creating an unreachable contact on every call is worse than an error.
:::

### `phone` is not validated like `to`

`POST /messages` enforces `^\+?\d+$` on `to` and rejects anything with a space or a dash. `POST /contacts` does not: `phone` is a string of at most 32 characters and that is the whole rule.

That is a convenience — a directory has to hold numbers that arrived from a CSV import or a lead form — but it puts the burden on you. Matching happens on what you send, so `+919876543210` and `+91 98765 43210` are your problem, not ours. `email` gets normalised; `phone` does not.

Normalise to E.164 in your own code before you call, use the same form everywhere, and you will never see a duplicate caused by formatting.

## Sending one

::: codegroup

```bash cURL
curl -X POST https://services.amomic.in/api/v1/contacts \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Asha Menon",
        "email": "asha.menon@example.in",
        "phone": "+919876543210"
      }'
```

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";

async function upsertContact({ name, email, phone }) {
  const response = await fetch(`${BASE}/contacts`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.AMOMIC_API_KEY}`,
      "Content-Type": "application/json",
    },
    // Normalise on our side: email lower-cased, phone reduced to E.164.
    body: JSON.stringify({
      name,
      email: email ? email.trim().toLowerCase() : undefined,
      phone: phone ? toE164(phone) : undefined,
    }),
  });

  if (response.ok) return response.json();

  const { error } = await response.json();

  if (error.details?.reason === "identity_conflict") {
    // The email and the phone already belong to two different people.
    // Retrying cannot fix it — a human has to decide which record is right.
    await flagForReview({ name, email, phone, requestId: error.request_id });
    return null;
  }

  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
```

```python Python
import os

import httpx

BASE = "https://services.amomic.in/api/v1"


def upsert_contact(client: httpx.Client, name=None, email=None, phone=None) -> dict | None:
    payload = {"name": name}
    # Normalise on our side: email lower-cased, phone reduced to E.164.
    if email:
        payload["email"] = email.strip().lower()
    if phone:
        payload["phone"] = to_e164(phone)

    response = client.post(
        f"{BASE}/contacts",
        headers={"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"},
        json={k: v for k, v in payload.items() if v is not None},
        timeout=15.0,
    )

    if response.is_success:
        return response.json()

    error = response.json()["error"]

    if (error.get("details") or {}).get("reason") == "identity_conflict":
        # The email and the phone already belong to two different people.
        # Retrying cannot fix it — a human has to decide which record is right.
        flag_for_review(name, email, phone, error.get("request_id"))
        return None

    raise RuntimeError(f"{error['code']}: {error['message']} ({error.get('request_id')})")
```

:::

## What comes back

`201 Created`, with the resolved contact record as the body — the same record whether it was created or updated.

::: warning Read the response defensively
This endpoint does not project the contact through a fixed public schema the way [conversations](/api/conversations) and [calls](/api/calls) do. The record is returned as the directory holds it, so the exact field set is not part of this API's contract and can gain fields.

Do not write code that requires a particular key to be present, and do not build your data model around the response shape. Treat the `201` as confirmation that the upsert succeeded, read only the fields you actually need, and default anything missing.

Your own identifiers are the durable join key here. `email` and `phone` are values you already control and can look the contact up by later; a field in this response is not something you can query back.
:::

## When your identifiers disagree

The one genuine failure of the model. You send an `email` that already belongs to contact A and a `phone` that already belongs to contact B:

```json title="409 Conflict"
{
  "error": {
    "code": "conflict",
    "message": "Those details belong to two different contacts.",
    "details": { "reason": "identity_conflict" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Nothing is written. The request is refused whole.

### Why we refuse instead of merging

Every other option is worse, and the reason is worth understanding because it tells you what to do about it.

- **Merging A and B** is destructive and irreversible. It would fold two customers' conversation histories, channel permissions, and tags into one record on the strength of a single API call from an automated job. If they were genuinely two people — a shared family phone, a colleague's email typed into a form — you cannot undo it.
- **Picking the email match and ignoring the phone** silently moves a phone number from one person to another. The next WhatsApp message from that number lands under the wrong name and nobody finds out.
- **Creating a third contact** turns one confusing state into a worse one.

A conflict means your systems hold information ours does not. So the request stops and comes back to you.

### Resolving one

::: steps

::: step Decide which identifier is authoritative

Send only that one. `{"email": "asha.menon@example.in", "name": "Asha Menon"}` updates contact A and leaves B alone. This is the fix for the common case where the phone number was stale.
:::

::: step Or fix the duplicate in the console

Open **Contacts**, search for either identifier, and edit or delete the record that should not exist. Then retry the upsert. The directory has an admin-only edit and delete on every contact.
:::

::: step Route the conflict to a human, not a retry queue

`identity_conflict` is a `409`. It will return `409` forever until someone changes data. A job that retries it on a schedule produces nothing but log volume — flag it for review with the `request_id` attached and move on to the next record.
:::

:::

::: note The same guard exists inside the product
Agents that resolve a contact as part of a tool call follow the same rule — conflicting identities stop the action for manual review rather than guessing. This endpoint is not stricter than the rest of the platform; it is consistent with it.
:::

## Idempotency

`POST /contacts` **ignores the `Idempotency-Key` header.** It is the one `POST` on the API that does. Sending the header is harmless and does nothing.

That is safe rather than an oversight, and the difference is worth being precise about.

On `POST /messages`, executing twice produces two effects in the world — two notifications on a customer's phone. The idempotency record exists to collapse them, because there is no other way to undo the second one.

On `POST /contacts` there is no second effect to collapse. Executing twice resolves the same identifiers, finds the same contact, and writes the same values. The operation converges by construction; the second run is a no-op with a `201` attached. Storing a response to replay would add a 24-hour window in which a genuine update — a corrected name, a new phone number — would be silently swallowed and replayed as the old answer. The header is ignored to prevent exactly that.

The practical rule: **retry `POST /contacts` freely.** A timeout, a `500`, a connection reset — send it again. There is no duplicate to create.

The exception is not idempotency-shaped: a retry that arrives *after* someone else changed the directory can newly hit `identity_conflict`. That is a real state change, not a retry artefact.

See [Idempotency](/api/idempotency) for the three endpoints that do honour the header.

## There is no way to read a contact back

No `GET /api/v1/contacts/{id}`, no contact list endpoint, no search, no delete. This endpoint is the entire contacts surface of the API — one route, write-only.

That shapes how you use it:

- **Your CRM stays the source of truth.** This is a projection of your data into the workspace so that humans and agents see a name, not a replacement for the system that owns the customer record.
- **Keep your own mapping.** If you need to know what we hold for a person, keep the `email` and `phone` you sent, keyed to your own customer id. Those are the values that will still resolve tomorrow.
- **The console is the read side.** **Contacts** in the console is a searchable directory — name, phone, channel, permissions, tags, date added — with a detail view per contact. That is where a human looks something up.
- **Tags and channel permissions are console-only.** The upsert takes `name`, `email`, and `phone` and nothing else. Whether a contact may be called, messaged on WhatsApp, or emailed is set in the console, as are tags. The API cannot change them.

For reading what a customer actually *said*, you want [conversations](/api/conversations), not contacts.

## Failures

```responses
[
  {"status": 201, "code": "", "reason": "", "description": "Contact created or updated. The body is the resolved record."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "`Provide an email or a phone number.` — neither identifier was present. `details` is empty."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "`Request validation failed.` — a field exceeded its length. `details.errors` names it."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "`The contact could not be resolved from those details.` — the directory accepted the request but produced no contact. Rare; check that the identifiers are not empty strings after trimming."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, unknown, revoked, expired after a roll, or used against the wrong host. `details.reason` distinguishes all six."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `contacts:write`. `details.required_scope` names it."},
  {"status": 409, "code": "conflict", "reason": "identity_conflict", "description": "The email and the phone already belong to two different contacts. Nothing was written. Send one identifier, or resolve the duplicate in the console."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests per minute per API key. A bulk directory import will meet this — pace it."},
  {"status": 500, "code": "internal", "reason": "", "description": "`Internal server error.` — includes the case where the directory service is unreachable. Retryable with backoff; log the `request_id`."}
]
```

Two notes on that list.

**The `500` is genuinely retryable here.** On most endpoints a `500` leaves you wondering whether the side effect happened. On an upsert it does not matter: retry, and either it works or it fails the same way. Back off, try a few times, then alert.

**There is no `412` on this endpoint.** Conversations and tickets can answer `failed_precondition` with `unsupported_resource` when a deployment does not carry that capability. Contacts has no such path — the directory is always present.

## Related

::: cards

::: card Conversations
[The read side](/api/conversations) — what the customer actually said, and the `customer` object that carries their identity.
:::

::: card Tickets
[POST /tickets](/api/tickets) — takes requester name, email, and phone inline, so a support ticket does not need a contact upsert first.
:::

::: card Errors
[The `identity_conflict` entry](/api/errors) in context, alongside every other `details.reason`.
:::

::: card Conversations & contacts
[The model behind the data](/concepts/conversations) — how one person is recognised across WhatsApp, web chat, and a phone call.
:::

:::


----------------------------------------------------------------------------
## Agents & channels
URL: https://docs.amomic.in/api/discovery
----------------------------------------------------------------------------

Four endpoints on this API do not do anything — they tell you about the workspace you are pointed at. They exist because of a gap the console cannot fill.

Everything else on this API takes an identifier you have to have got from somewhere. `POST /messages` takes a `sender_id`. `GET /conversations` takes an `agent_id` filter. `POST /calls` takes an `agent_id` to assert against. In the console those are things you click. In a deployment script running at 3 a.m. against a customer's workspace, there is no console open and nobody to copy a value out of one.

| Endpoint | Needs | Tells you |
|---|---|---|
| `GET /api/v1/agents` | `agents:read` | Which agents exist and which are published |
| `GET /api/v1/channels` | Any valid key | Which channels this deployment carries, and which senders are connected |
| `GET /api/v1/ping` | Any valid key | Which workspace, key, environment, and scopes you are holding |
| `GET /api/v1/openapi.json` | **Nothing** | The machine-readable contract for every route |

None of them has a side effect. All four are safe to call on every process start.

## Listing agents

```endpoint
GET /api/v1/agents
```

Requires the `agents:read` scope — one of the two a new key gets by default. No query parameters.

```json title="200 OK"
{
  "items": [
    {
      "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
      "name": "Support Assistant",
      "status": "live",
      "channels": ["web"]
    },
    {
      "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH5",
      "name": "Renewals Outbound",
      "status": "draft",
      "channels": []
    }
  ],
  "next_cursor": null
}
```

| Field | Type | Notes |
|---|---|---|
| `agent_id` | string | The handle you pass everywhere else. Treat it as an opaque string — copy it from here, do not construct it and do not parse it. |
| `name` | string | What the agent is called in the console. Falls back to `Assistant` when unset. |
| `status` | string | `draft` or `live`. `live` means the agent has been published; `draft` means it exists but has not. |
| `channels` | string[] | See the warning below before you use this. |

Nothing else is returned. There is no persona, no model configuration, no knowledge base list, no version history, and no deployment detail — those live in the console and have no public REST equivalent. This endpoint answers "which agents exist and what are they called", and that is its whole job.

::: warning `channels` is a coarse indicator, not a channel list
A published agent reports `["web"]`. A draft agent reports `[]`. That is the entire behaviour, and it is derived from `status` rather than from where the agent is actually deployed.

So an agent that answers WhatsApp and takes phone calls still reports `["web"]`, and the presence of `web` in that array does not prove a web deployment exists. Read it as a boolean in disguise — "published" or "not published" — which is information `status` already gave you.

For what the workspace can actually send on, call [`GET /channels`](#what-this-deployment-can-do). For where a specific agent is deployed, the console's deployments view is the authority.
:::

```mock
{"component": "AgentsScreen", "props": {"caption": "The console view of the same list. `status` here is the `live` or `draft` you get from the API."}}
```

### The envelope, and why it never paginates

The response uses the same `{items, next_cursor}` shape as [conversations](/api/conversations), but `next_cursor` is always `null` and there is no `limit` or `cursor` parameter. You get every agent in the workspace in one response.

That is deliberate — a workspace has agents in the tens, not the thousands — and it means a generic pagination helper works here without a special case: one page, a `null` cursor, done. [Pagination](/api/pagination) has that helper written out.

### What you use `agent_id` for

Two places, and they behave very differently:

- **`GET /conversations?agent_id=…`** filters the list to one agent's conversations. A straightforward filter.
- **`POST /calls` with `agent_id`** is an **assertion, not a selection**. The agent that speaks on an outbound call is resolved from the caller-ID number, not from this field. Sending an `agent_id` that is not the one deployed to that number returns `412 agent_number_mismatch`, and `details.deployed_agent_id` names the agent that actually is. See [Calls](/api/calls).

::: tip Resolve names to ids once, at startup
If your configuration names agents by their human name — `"Support Assistant"` — resolve it to an `agent_id` when your process starts, and cache it. Doing it per request spends a rate-limit slot on a value that changes about once a quarter. Doing it never means someone renames the agent in the console and your integration keeps working, which is the point.
:::

## What this deployment can do

```endpoint
GET /api/v1/channels
```

Requires a valid key and no particular scope. No query parameters.

```json title="200 OK"
{
  "message_channels": ["whatsapp"],
  "call_channels": ["voice"],
  "senders": [
    {
      "channel": "whatsapp",
      "sender_id": "was_9f2c41ab77de1063c8a4b512",
      "display_number": "+919461093306",
      "verified_name": "Amomic Retail",
      "is_default": true,
      "status": "live"
    }
  ]
}
```

| Field | Type | Notes |
|---|---|---|
| `message_channels` | string[] | The channels this deployment can send messages on. |
| `call_channels` | string[] | The channels it can place calls on. |
| `senders` | object[] | Every connected sender we could enumerate. Empty when nothing is connected. |
| `senders[].channel` | string | Which channel this sender belongs to. |
| `senders[].sender_id` | string | The value you pass as `sender_id` on [`POST /messages`](/api/messages). Opaque — copy it. |
| `senders[].display_number` | string | The number customers see. |
| `senders[].verified_name` | string | The business name approved for this sender. |
| `senders[].is_default` | boolean | `true` on the sender used when you omit `sender_id`. Exactly one per workspace. |
| `senders[].status` | string | `configuring`, `live`, or `disabled`. Only a `live` sender sends. |

### Two different questions

The two arrays and the sender list answer different things, and conflating them is a real source of confusion:

- **`message_channels` and `call_channels` are about the deployment.** They tell you which capabilities this service carries at all. Asking for a channel that is not in these lists returns `412 failed_precondition` with `details.reason` of `unsupported_channel` and `details.supported` naming what is available.
- **`senders` is about the workspace.** `whatsapp` can be in `message_channels` while `senders` is empty, which means the capability exists and this workspace has not connected a number to it. A send in that state returns `412` with `channel_not_connected`.

Both are configuration states, not transient ones. Retrying either is pointless — see [Errors](/api/errors).

::: warning Sender enumeration is best-effort
Building the `senders` array means asking each channel provider what it has. If one of those lookups fails, the failure is logged and that channel is **skipped** — the endpoint still returns `200` with whatever else it found.

A sender you expected and did not get is therefore ambiguous: it might not be connected, or its provider might have been unreachable for that one second. Never treat an absent sender as proof of an absent configuration, and never write a startup check that hard-fails on it. The channel arrays are the more stable signal; the sender list is a convenience.
:::

## Checking your key

```endpoint
GET /api/v1/ping
```

Requires a valid key and no particular scope. No parameters, no body, no side effects.

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order notifications",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

| Field | Type | Notes |
|---|---|---|
| `ok` | boolean | Always `true`. If the key were bad you would have a `401` instead. |
| `workspace_id` | string | The workspace this key belongs to. The same value arrives as `tenant_id` on every webhook. |
| `key_name` | string | The name the key was given in the console. Useful when three keys look identical in a secret store. |
| `environment` | string | `live` or `test`. |
| `scopes` | string[] | Sorted. Exactly what this key may do. |

This is the first call every integration should make, and it is worth wiring into more than a one-off:

- **On deploy.** A `200` here proves the secret reached the process, the host matches the environment, and the key is not revoked — three of the most common launch failures, ruled out before any customer-visible request.
- **When a `403` surprises you.** `scopes` is the authoritative list. Comparing it against the scope named in `details.required_scope` turns "permission denied" from a mystery into a one-line diff. See [Scopes](/api/scopes).
- **When `wrong_environment` bites.** A `test` key against `services.amomic.in`, or a `live` key against the dev host, is a `401` with `details.reason` of `wrong_environment` and nothing else. Ping against the *other* host and the `environment` field tells you which key you are actually holding.

::: note Ping costs a request
It is cheap but not free — it spends one of your [120 per minute](/api/rate-limits), and its response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining` like any other success. That makes it a fine way to check your remaining budget, and a bad thing to put in a one-second health-check loop.
:::

## The machine-readable contract

```endpoint
GET /api/v1/openapi.json
```

**No key required.** This is the only route on `/api/v1` that answers an unauthenticated request, because a contract is not a secret and needing a credential to read one makes tooling harder for no security benefit.

```bash
curl https://services.amomic.in/api/v1/openapi.json -o amomic-openapi.json
```

It returns an OpenAPI 3.1 document containing:

- **`info`** — title `Amomic-AI API`, and a description that repeats the two auth header forms and the no-CORS rule.
- **`servers`** — the base URL of the host you fetched it from, so the document you pull from the dev host points at the dev host.
- **`paths`** — every `/api/v1` route and nothing else. Console-only routes are filtered out of the document entirely, so what you see is exactly the public surface.
- **`components.schemas`** — the request and response models.
- **`securitySchemes`** — `ApiKeyBearer` (HTTP bearer) and `ApiKeyHeader` (`X-Api-Key`), with both offered at the document level.

Two things to do with it:

**Generate a client.** There are no official SDKs in any language — deliberately, since the API is plain HTTP and JSON. If you want a typed client, generate one from this document rather than hand-rolling models that drift.

**Give it to a coding agent.** An agent that has the OpenAPI document plus these docs writes a working integration on the first attempt instead of inventing endpoints from a model's memory of "some WhatsApp API". [Use with coding agents](/agents-setup) has the setup for Claude Code, Codex, Cursor, and anything that speaks MCP — including a documentation MCP endpoint and a single-file corpus.

::: note The document describes shapes, not behaviour
An OpenAPI document can tell a generator that `POST /messages` takes a `to` and a `text`. It cannot tell it that a free-form `text` outside the 24-hour window fails, that `Idempotency-Key` must be derived rather than generated, or that `agent_id` on a call is an assertion. Those are the things that break integrations, and they are in these pages. Use both.
:::

## A startup check worth having

Fifteen lines that turn every configuration failure into one clear log line at boot instead of a confusing `412` during a customer's checkout.

::: codegroup

```javascript Node.js
const BASE = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };

async function get(path) {
  const response = await fetch(`${BASE}${path}`, { headers: HEADERS });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

export async function preflight({ requiredScopes = ["messages:send"] } = {}) {
  // 1. Is the credential live, and is it the one we think it is?
  const ping = await get("/ping");
  console.info("amomic_ready", {
    workspace: ping.workspace_id,
    key: ping.key_name,
    environment: ping.environment,
  });

  const missing = requiredScopes.filter((s) => !ping.scopes.includes(s));
  if (missing.length) {
    throw new Error(`API key "${ping.key_name}" is missing scopes: ${missing.join(", ")}`);
  }

  // 2. Can this deployment send at all, and is a sender connected?
  const channels = await get("/channels");
  if (!channels.message_channels.includes("whatsapp")) {
    throw new Error("This deployment cannot send WhatsApp messages.");
  }

  const sender = channels.senders.find((s) => s.channel === "whatsapp" && s.is_default);
  if (!sender) {
    // Enumeration is best-effort — warn, do not crash the process.
    console.warn("amomic_no_default_sender", { senders: channels.senders.length });
  } else if (sender.status !== "live") {
    console.warn("amomic_sender_not_live", { sender_id: sender.sender_id, status: sender.status });
  }

  return { workspaceId: ping.workspace_id, senderId: sender?.sender_id ?? null };
}
```

```python Python
import logging
import os

import httpx

BASE = "https://services.amomic.in/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['AMOMIC_API_KEY']}"}
log = logging.getLogger(__name__)


def _get(client: httpx.Client, path: str) -> dict:
    response = client.get(f"{BASE}{path}", headers=HEADERS, timeout=15.0)
    body = response.json()
    if not response.is_success:
        error = body["error"]
        raise RuntimeError(f"{error['code']}: {error['message']}")
    return body


def preflight(client: httpx.Client, required_scopes=("messages:send",)) -> dict:
    # 1. Is the credential live, and is it the one we think it is?
    ping = _get(client, "/ping")
    log.info(
        "amomic_ready",
        extra={
            "workspace": ping["workspace_id"],
            "key": ping["key_name"],
            "environment": ping["environment"],
        },
    )

    missing = [s for s in required_scopes if s not in ping["scopes"]]
    if missing:
        raise RuntimeError(
            f"API key {ping['key_name']!r} is missing scopes: {', '.join(missing)}"
        )

    # 2. Can this deployment send at all, and is a sender connected?
    channels = _get(client, "/channels")
    if "whatsapp" not in channels["message_channels"]:
        raise RuntimeError("This deployment cannot send WhatsApp messages.")

    sender = next(
        (s for s in channels["senders"] if s["channel"] == "whatsapp" and s["is_default"]),
        None,
    )
    if sender is None:
        # Enumeration is best-effort — warn, do not crash the process.
        log.warning("amomic_no_default_sender", extra={"senders": len(channels["senders"])})
    elif sender["status"] != "live":
        log.warning(
            "amomic_sender_not_live",
            extra={"sender_id": sender["sender_id"], "status": sender["status"]},
        )

    return {
        "workspace_id": ping["workspace_id"],
        "sender_id": sender["sender_id"] if sender else None,
    }
```

:::

Note what it does and does not treat as fatal. A missing scope is fatal — it will fail every send, loudly, forever. A missing sender is a warning, because enumeration is best-effort and refusing to start over a transient provider lookup is worse than starting.

## Failures

```responses
[
  {"status": 200, "code": "", "reason": "", "description": "All four endpoints return 200 on success. `/agents` and `/channels` return an empty list rather than a 404 when there is nothing to list."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Applies to `/agents`, `/channels`, and `/ping`. Key missing, malformed, unknown, revoked, expired after a roll, or from the wrong environment — `details.reason` distinguishes all six. `/openapi.json` never returns this."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "`/agents` only. The key lacks `agents:read`. `/channels` and `/ping` need no scope beyond a valid key."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "These endpoints count against the same 120 per minute as everything else. Cache their answers; they change on the timescale of console edits, not requests."}
]
```

There is no `412` on any of them. `GET /channels` in particular is designed to be the thing you call *instead of* discovering a missing capability through a `412` on a real send.

## Related

::: cards

::: card Messages
[POST /messages](/api/messages) — where the `sender_id` from `/channels` gets used, and what happens when you omit it.
:::

::: card Calls
[POST /calls](/api/calls) — where `agent_id` is an assertion rather than a selection, and why that matters.
:::

::: card Scopes
[The six scopes](/api/scopes) — what `/ping` is showing you, and how to narrow a key safely.
:::

::: card Use with coding agents
[Point your agent at the contract](/agents-setup) — the OpenAPI document, the docs MCP endpoint, and the full-corpus file.
:::

:::


============================================================================
# SECTION: Webhooks
============================================================================



----------------------------------------------------------------------------
## Getting events
URL: https://docs.amomic.in/webhooks/overview
----------------------------------------------------------------------------

A webhook is an HTTPS endpoint you own. When something happens in your workspace — a customer replies on WhatsApp, a call finishes, a visitor leaves their phone number — we POST a signed JSON body to that URL. Your server does the rest.

This page covers the delivery contract: what arrives, in what shape, with what headers, and the rules your endpoint has to follow to stay subscribed. [Verifying signatures](/webhooks/signatures) covers the security half, [Event reference](/webhooks/events) lists every payload field, and [Retries and failures](/webhooks/reliability) covers what happens when your server has a bad day.

## Why not just poll

Polling is the obvious alternative and it does not work well here, for two reasons that are structural rather than aesthetic.

**Most of what you want has no list endpoint.** There is no `GET /api/v1/messages` and no `GET /api/v1/calls`. An inbound WhatsApp message and a finished call are not things you can enumerate. To notice an inbound message by polling you would have to list conversations, spot a changed `updated_at`, then fetch that conversation's messages and diff them against what you already stored — three round trips to learn one fact you could have been told.

**Your budget is 120 requests per minute per key** ([rate limits](/api/rate-limits)). Polling conversations every five seconds burns 12 of those every minute doing nothing, forever, and still leaves you up to five seconds behind. Webhooks arrive in the low hundreds of milliseconds and cost you nothing when the workspace is quiet.

Polling is still the right tool for reconciliation — catching up after your endpoint was down. [Retries and failures](/webhooks/reliability) has that pattern.

## Create an endpoint

Webhook endpoints are managed in the console, by an admin. There is no public API for creating, updating, or listing them — [scopes](/api/scopes) has no webhook scope because there is nothing to scope.

::: steps

::: step Have a URL ready

It must be `https://`. Plain `http://` is rejected when you save, with a 400 and the message `Webhook URLs must use https.` — we do not send workspace events over an unencrypted connection, not even to `localhost` through a tunnel.

For local development, use a tunnel that terminates TLS for you and gives you an `https://` hostname.
:::

::: step Add it in the console

Open **Developers → Webhooks** and choose **Add endpoint**. Paste the URL and pick the events you want.

Leaving every checkbox unticked is meaningful: an endpoint with an empty event list receives **all** events, including event types added later. That is usually what you want for a first integration, and it is the only configuration that does not need revisiting when the catalogue grows. Tick specific events when you have a receiver that would be confused by anything else.

You can describe the endpoint in one line. Do it — six months from now `https://api.acme.in/hooks/amomic` tells you nothing about which service owns it.
:::

::: step Copy the signing secret

Creating the endpoint returns a signing secret that starts with `whsec_`, once, in a dialog. It is not stored anywhere you can read it back — not in the console, not by support.

Put it in your secret manager before you close that dialog. If you lose it, the only way to get a new one is to delete the endpoint and create it again; there is no rotation endpoint.
:::

::: step Send a test event

The endpoint row has a **Test** action. It sends a `ping` event through the real delivery path — same headers, same signature — and tells you what your server replied. Use it to prove your receiver is reachable and your verification works before you wait on a real customer.

The console reports back either `Your endpoint replied {code}.` or `Your endpoint didn't respond.`
:::

:::

```mock
{"component": "WebhookDeliveriesScreen", "props": {"caption": "The deliveries view for one endpoint. Attempt 3 on a 500 is the retry ladder doing its job."}}
```

## The delivery

Every event is a single `POST` with a JSON body.

### Envelope

```json
{
  "id": "evt_9f2c4a17b03e5d8194ca2f60",
  "type": "message.received",
  "created_at": "2026-08-01T10:00:00Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
    "from": "+919876543210",
    "text": "Where is my order?",
    "type": "text",
    "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
    "deployment_id": "dep_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

```params
[
  {"name": "id", "type": "string", "required": true, "description": "<code>evt_</code> followed by 24 hex characters. Unique per delivery fan-out and the value you deduplicate on. Also sent as the <code>Amomic-Event-Id</code> header."},
  {"name": "type", "type": "string", "required": true, "description": "One of the nine event types, or <code>ping</code>. See <a href=\"/webhooks/events\">Event reference</a>."},
  {"name": "created_at", "type": "string", "required": true, "description": "UTC, second precision, literal <code>Z</code> suffix — <code>2026-08-01T10:00:00Z</code>. Note this is <em>not</em> the same shape as timestamps on REST resources, which carry microseconds and a <code>+00:00</code> offset."},
  {"name": "tenant_id", "type": "string", "required": true, "description": "Your workspace id, <code>ten_</code>-prefixed. Useful if one receiver serves several workspaces."},
  {"name": "data", "type": "object", "required": true, "description": "The event payload. Field set depends on <code>type</code>; every field list is an allow-list, and null-valued fields are omitted entirely rather than sent as <code>null</code>."},
  {"name": "data.event_id", "type": "string", "required": true, "description": "An internal envelope id, present on every event. It is <strong>not</strong> the same value as the top-level <code>id</code>. Deduplicate on the top-level <code>id</code>, not on this."}
]
```

::: warning `data.event_id` is not the delivery id
Two different ids ship in every event and they are not interchangeable. `id` at the top level is the delivery identity — it matches `Amomic-Event-Id` and it is the correct dedupe key. `data.event_id` is an internal identifier that rides along inside the payload. Keying your dedupe table on the wrong one is a bug you will not notice until the first redelivery.
:::

### Headers

```
Content-Type: application/json
User-Agent: Amomic-AI-Webhooks/<version>
Amomic-Signature: t=1754049600,v1=8f3a...c1
Amomic-Event-Id: evt_9f2c4a17b03e5d8194ca2f60
Amomic-Event-Type: message.received
Amomic-Delivery-Attempt: 1
```

| Header | Meaning |
|---|---|
| `Amomic-Signature` | Timestamped HMAC-SHA256 over the raw body. Format `t=<unix seconds>,v1=<lowercase hex>`. Verify it on every request — see [Verifying signatures](/webhooks/signatures). |
| `Amomic-Event-Id` | The same value as the envelope's `id`. Lets you deduplicate before you parse the body. |
| `Amomic-Event-Type` | The same value as the envelope's `type`. Lets you route before you parse the body. |
| `Amomic-Delivery-Attempt` | `1` through `4`. Anything above `1` means an earlier attempt failed, so you are looking at a retry — see [Retries and failures](/webhooks/reliability). |
| `User-Agent` | Always begins `Amomic-AI-Webhooks/`. Convenient for filtering your access logs; useless as an authentication signal, since anyone can send it. |

The `Amomic-Event-Id` and `Amomic-Event-Type` headers duplicate envelope fields on purpose. A receiver that has already seen an event id can return `200` from the middleware layer without ever deserialising the body.

::: danger Headers are not proof of anything
The signature is the only thing that establishes an event came from us. Every other header can be forged by anyone who guesses your URL. Do not branch on `Amomic-Event-Type` before you have verified `Amomic-Signature`.
:::

## Rules your endpoint has to follow

### Return 2xx immediately, then work

The delivery has a **10-second total timeout** (5 seconds to connect). If your handler is still thinking at 10 seconds, the connection is cut and the delivery counts as failed — even if your code goes on to complete successfully. You then get a retry of the same event, and now you are processing it twice.

The pattern that survives is:

1. Verify the signature.
2. Write the event somewhere durable — a queue, a table, a log.
3. Return `200`.
4. Do the real work in a worker.

Anything that talks to a third party, sends an email, or writes to a slow database belongs in step 4. The 10-second window is not a work budget, it is an acknowledgement budget.

### Deliveries are at-least-once

The same `id` can arrive more than once. This is not a rare edge case caused by our bugs — it is the guarantee. A delivery that times out at 10 seconds but succeeds on your side at 11 seconds will be retried, and both copies are real.

Keep a table of processed event ids and check it first:

```sql
-- the whole mechanism
INSERT INTO amomic_events (event_id, received_at) VALUES ($1, now())
ON CONFLICT (event_id) DO NOTHING;
-- zero rows affected means you have seen this event; ack and stop.
```

[Retries and failures](/webhooks/reliability) goes deeper on idempotent handler design.

### Redirects are not followed

A `301`, `302`, or `307` is treated as a failed delivery, not as an instruction. We do not follow redirects, by design — following one would mean signing a payload for a host we never agreed to talk to.

If your platform silently redirects `http` to `https`, or `/hooks/amomic` to `/hooks/amomic/`, register the final URL. A trailing slash mismatch is a surprisingly common cause of an endpoint that auto-disables in its first hour.

### One event, one POST

There is no batching. Ten inbound messages are ten separate requests, each with its own signature and its own id.

## A minimal receiver

Both examples do the same four things: read the raw bytes, verify, enqueue, acknowledge. The verification function is the short form; [Verifying signatures](/webhooks/signatures) has the fully commented version for four languages, plus the failure modes.

::: codegroup

```javascript Node.js
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.AMOMIC_WEBHOOK_SECRET; // the whsec_… string

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  if (!header) return false;

  const fields = {};
  for (const piece of header.split(",")) {
    const i = piece.indexOf("=");
    if (i > 0) fields[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
  }
  if (!fields.t || !fields.v1) return false;

  const timestamp = Number.parseInt(fields.t, 10);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(fields.t + ".")
    .update(rawBody)          // Buffer — the bytes exactly as received
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(fields.v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw gives you a Buffer. Do NOT register express.json() ahead of this
// route — if it runs first, the stream is consumed and the bytes are gone.
app.post("/hooks/amomic", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verify(req.body, req.get("Amomic-Signature"), SECRET)) {
    return res.status(400).send("bad signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));

  try {
    await queue.enqueue(event.id, event); // durable and fast — no business logic here
  } catch (err) {
    return res.status(500).send("could not enqueue"); // a 500 gets retried
  }

  return res.status(200).send("ok");
});

app.listen(8080);
```

```python Python
import hashlib
import hmac
import json
import os
import time

from fastapi import FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["AMOMIC_WEBHOOK_SECRET"]  # the whsec_… string


def verify(raw_body: bytes, header: str | None, secret: str, tolerance_s: int = 300) -> bool:
    if not header:
        return False

    fields = {}
    for piece in header.split(","):
        key, sep, value = piece.partition("=")
        if sep:
            fields[key.strip()] = value.strip()

    raw_t, received = fields.get("t"), fields.get("v1")
    if not raw_t or not received:
        return False

    try:
        timestamp = int(raw_t)
    except ValueError:
        return False
    if abs(int(time.time()) - timestamp) > tolerance_s:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        raw_t.encode("utf-8") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, received)


# Take the Request, not a Pydantic model. A typed body parameter makes FastAPI
# parse the JSON for you, and the bytes you need for verification are lost.
@app.post("/hooks/amomic")
async def amomic_webhook(request: Request) -> Response:
    raw = await request.body()

    if not verify(raw, request.headers.get("Amomic-Signature"), SECRET):
        return Response(status_code=400)

    event = json.loads(raw)

    try:
        await queue.enqueue(event["id"], event)  # durable and fast
    except Exception:
        return Response(status_code=500)  # a 500 gets retried

    return Response(status_code=200)
```

:::

::: warning The single most common integration bug
Verify against the **raw request bytes**. The body we sign is serialised compactly — no spaces after `:` or `,` — so parsing it into a dict and serialising it again produces different bytes and a signature that will never match, no matter how correct your HMAC code is. [Verifying signatures](/webhooks/signatures) explains exactly why and how to avoid it in each framework.
:::

## Next

::: cards

::: card Verify a delivery
[Verifying signatures](/webhooks/signatures) — the header format, the tolerance window, and copy-pasteable verifiers in four languages.
:::

::: card What each event contains
[Event reference](/webhooks/events) — all nine event types with exact field lists and realistic payloads.
:::

::: card When your endpoint fails
[Retries and failures](/webhooks/reliability) — the retry ladder, auto-disable, and how to catch up after an outage.
:::

::: card Send something back
[Messages](/api/messages) — replying to what you just received, and the 24-hour window that governs how.
:::

:::


----------------------------------------------------------------------------
## Verifying signatures
URL: https://docs.amomic.in/webhooks/signatures
----------------------------------------------------------------------------

Your webhook URL is a public HTTP endpoint. Anyone who learns it can POST to it, and a forged `ticket.created` that your system trusts is a real problem. The signature is what separates an event we sent from one somebody else made up.

Verify every request. Reject anything that does not verify, without parsing it.

## The header

```
Amomic-Signature: t=1754049600,v1=8f3ac91b0d7e4f2a6c5b8e1d0a9f3c72e4b6d8a1c3e5f7091b2d4a6c8e0f2a4b6
```

Two comma-separated `key=value` pairs:

| Field | Meaning |
|---|---|
| `t` | The Unix timestamp, in **seconds**, at which the signature was generated. |
| `v1` | HMAC-SHA256 of the signed string, as **lowercase hexadecimal**. Version 1 of the scheme. |

Parse it by splitting on `,` and then each piece on the **first** `=`. Do not split on every `=` — the value is hex today, but a scheme that survives contact with base64 later should not break on padding.

## What is signed

Exactly this string:

```
{t}.{body}
```

The timestamp from the header, a literal `.` (full stop), and the raw request body. Nothing else — not the URL, not the method, not the other headers.

The HMAC key is your endpoint's signing secret: the `whsec_…` string, **used as raw UTF-8 bytes**.

::: danger Do not transform the secret
Two things people do to the secret, both of which produce a signature that never matches:

- **Base64-decoding it.** The characters after `whsec_` look like base64 because they are — the secret was generated as base64url of 32 random bytes. It is still used as a string. Do not decode it.
- **Stripping the `whsec_` prefix.** The prefix is part of the key. `whsec_abc123` and `abc123` are different keys.

Pass the secret to your HMAC function exactly as the console gave it to you, prefix and all.
:::

So the reference computation, in Python, is:

```python
hmac.new(
    secret.encode("utf-8"),                             # "whsec_…", verbatim
    f"{timestamp}.".encode("utf-8") + raw_body,         # raw_body is bytes
    hashlib.sha256,
).hexdigest()                                            # lowercase hex
```

Use the timestamp **as it appeared in the header**, as a string. Parse it to an integer for the tolerance check, but feed the original characters into the HMAC. They are the same today; using the original string means they stay the same if the format ever grows leading zeroes or a different width.

## Verify against the raw bytes

This is the part that costs people an afternoon, so it gets its own section.

The body we send is serialised compactly. There is no space after `:` and no space after `,`:

```
{"id":"evt_9f2c4a17b03e5d8194ca2f60","type":"message.received","created_at":"2026-08-01T10:00:00Z",...}
```

Those exact bytes are the `{body}` in the signed string. Byte-for-byte.

If your framework parsed the JSON into a map and you serialise it again to verify, you get a different byte sequence — most standard libraries insert `", "` and `": "` — and the HMAC over that sequence has nothing to do with ours. Your verification code can be flawlessly correct and still fail every request.

Re-serialising also breaks in ways that are harder to see than whitespace:

- **Key order.** Most JSON parsers preserve insertion order, some do not. One reordered key is a completely different signature.
- **Unicode escaping.** We emit UTF-8 directly, so a customer named `प्रिया` arrives as UTF-8 bytes. A serialiser configured with `ensure_ascii=True` rewrites that as `प्…` and changes the length of the body.
- **Number formatting.** `duration_seconds: 0` re-serialised by a language that decoded it as a float becomes `0.0`.
- **Trailing newline.** Some frameworks append one when they hand you the "body".

The rule: capture the bytes off the wire, verify those bytes, and only then parse them.

::: warning Verify before you parse, not after
Parsing untrusted input is itself an operation you are choosing to perform on data from an unauthenticated stranger. Order matters: read bytes, verify, parse. Never parse, verify, act.
:::

### Getting raw bytes in each framework

| Stack | How | Trap |
|---|---|---|
| Express | `express.raw({ type: "application/json" })` on the route | A global `app.use(express.json())` registered before the route consumes the stream first. `req.body` is then an object and the bytes are gone. |
| Fastify | `addContentTypeParser("application/json", { parseAs: "buffer" }, …)` or a raw-body plugin | The default JSON parser runs before your handler. |
| FastAPI / Starlette | `raw = await request.body()` | Declaring a Pydantic model or `dict` body parameter makes the framework parse it for you. Take `Request`. |
| Flask | `request.get_data()` | `request.get_json()` and `request.json` both parse. `get_data()` after a parse still returns the cached bytes, but do not rely on ordering — call it first. |
| Django | `request.body` | Only if nothing has read the stream. Accessing `request.POST` on a non-form request can consume it. |
| PHP | `file_get_contents("php://input")` | Readable once on some SAPI configurations. Read it into a variable at the top of the handler. |
| Laravel | `$request->getContent()` | Middleware that mutates the request can rebuild the body. Exclude the webhook route from anything that does. |
| Go | `io.ReadAll(r.Body)` | `json.NewDecoder(r.Body).Decode(...)` consumes it. Read to `[]byte` first, then `json.Unmarshal`. |
| Rails | `request.raw_post` | `params` is already parsed; do not rebuild the body from it. |
| Next.js (pages router) | `export const config = { api: { bodyParser: false } }`, then read the stream | Body parsing is on by default and silently produces a parsed object. |
| AWS API Gateway / Lambda | `event.body` | If `isBase64Encoded` is true you must base64-decode to get the original bytes. Binary media type settings on the gateway change this behaviour. |

## The timestamp tolerance

Reject the request if `t` differs from your current time by more than **300 seconds** in either direction.

The reason is replay. Without the timestamp check, an attacker who captures one valid delivery — from a log file, a misconfigured proxy, a screenshot in a support ticket — can POST that exact request, signature and all, forever. The signature stays valid because nothing about it expires. A `ticket.created` replayed a thousand times is a thousand tickets.

The timestamp is inside the signed string, so an attacker cannot advance it without breaking the HMAC. Five minutes of validity is what an attacker gets instead of eternity.

Check in **both** directions. A signature from ten minutes in the future is as suspicious as one from ten minutes in the past, and it usually means your own server clock is wrong.

::: note 300 seconds is generous on purpose
The window has to absorb the full retry ladder — the fourth attempt of an event is sent roughly 57 seconds after the first, plus however long your failed attempts took to time out. Each attempt is signed with its own fresh timestamp, so this is headroom rather than a requirement, but do not tighten the tolerance to 30 seconds and expect retries to survive a slow network.

If you widen it instead, understand what you are buying: a 24-hour tolerance is a 24-hour replay window.
:::

Run NTP on the machine that verifies. Clock drift is the failure mode that looks like a signature bug, and it is the one that appears out of nowhere on a host that worked yesterday.

## Compare in constant time

Use `hmac.compare_digest`, `crypto.timingSafeEqual`, `hash_equals`, or `hmac.Equal`. Never `==`.

This is not a theoretical concern that security checklists include out of habit. `==` on strings in every mainstream language short-circuits at the first differing byte, so comparing an attacker's guess against the real digest takes measurably longer when more leading characters are right. An attacker who can send requests and time the responses recovers the correct digest one hex character at a time — 64 characters, 16 guesses each, about a thousand requests. Your endpoint is on the public internet and answers as fast as you can make it. That is the whole attack.

Two details the constant-time function will not save you from:

- **Compare lengths first, carefully.** `crypto.timingSafeEqual` in Node *throws* if the two buffers differ in length. Check `a.length === b.length` before calling it, and return false rather than letting an exception become a 500 — a 500 is a retryable status, so a malformed signature would get sent to you four times.
- **Do not lowercase, trim, or normalise the received digest before comparing.** We emit lowercase hex. Anything else is not our signature.

## Complete verifiers

Each of these does the same five steps: parse the header, check the tolerance, recompute the HMAC over `t` + `.` + raw bytes, compare in constant time, and only then hand the bytes to a parser.

::: codegroup

```javascript Node.js
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.AMOMIC_WEBHOOK_SECRET; // "whsec_…", verbatim
const TOLERANCE_SECONDS = 300;

function parseSignatureHeader(header) {
  // "t=1754049600,v1=8f3a…" → { t: "1754049600", v1: "8f3a…" }
  const fields = {};
  for (const piece of header.split(",")) {
    const i = piece.indexOf("=");          // first "=" only
    if (i > 0) fields[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
  }
  return fields;
}

export function verifyAmomicSignature(rawBody, header, secret = SECRET) {
  if (!header || !Buffer.isBuffer(rawBody)) return false;

  const fields = parseSignatureHeader(header);
  const rawTimestamp = fields.t;
  const received = fields.v1;
  if (!rawTimestamp || !received) return false;

  // 1. Tolerance. Parse for the comparison only; sign with the original string.
  const timestamp = Number.parseInt(rawTimestamp, 10);
  if (!Number.isFinite(timestamp)) return false;
  const skew = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (skew > TOLERANCE_SECONDS) return false;

  // 2. Recompute over "{t}." + the exact bytes received.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawTimestamp + ".")
    .update(rawBody)
    .digest("hex");

  // 3. Constant-time compare. timingSafeEqual throws on a length mismatch.
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(received, "utf8");
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

const app = express();

app.post("/hooks/amomic", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyAmomicSignature(req.body, req.get("Amomic-Signature"))) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  handleAsync(event);            // never awaited inline — ack fast
  return res.status(200).send("ok");
});
```

```python Python
import hashlib
import hmac
import json
import os
import time

from fastapi import FastAPI, Request, Response

SECRET = os.environ["AMOMIC_WEBHOOK_SECRET"]  # "whsec_…", verbatim
TOLERANCE_S = 300

app = FastAPI()


def _parse_header(header: str) -> dict[str, str]:
    fields: dict[str, str] = {}
    for piece in header.split(","):
        key, sep, value = piece.partition("=")   # first "=" only
        if sep:
            fields[key.strip()] = value.strip()
    return fields


def verify_amomic_signature(
    raw_body: bytes,
    header: str | None,
    secret: str = SECRET,
    tolerance_s: int = TOLERANCE_S,
) -> bool:
    if not header:
        return False

    fields = _parse_header(header)
    raw_timestamp = fields.get("t")
    received = fields.get("v1")
    if not raw_timestamp or not received:
        return False

    # 1. Tolerance, both directions.
    try:
        timestamp = int(raw_timestamp)
    except ValueError:
        return False
    if abs(int(time.time()) - timestamp) > tolerance_s:
        return False

    # 2. Recompute over "{t}." + the exact bytes received.
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_timestamp.encode("utf-8") + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()

    # 3. Constant-time compare.
    return hmac.compare_digest(expected, received)


# Request, not a Pydantic model — a typed body parameter parses the JSON and the
# bytes you need are gone before your code runs.
@app.post("/hooks/amomic")
async def amomic_webhook(request: Request) -> Response:
    raw = await request.body()

    if not verify_amomic_signature(raw, request.headers.get("Amomic-Signature")):
        return Response(status_code=400)

    event = json.loads(raw)
    await enqueue(event["id"], event)
    return Response(status_code=200)
```

```php PHP
<?php

const AMOMIC_TOLERANCE_S = 300;

function amomic_verify_signature(
    string $rawBody,
    ?string $header,
    string $secret,
    int $toleranceS = AMOMIC_TOLERANCE_S
): bool {
    if ($header === null || $header === '') {
        return false;
    }

    // Parse "t=…,v1=…" splitting each piece on the first "=" only.
    $fields = [];
    foreach (explode(',', $header) as $piece) {
        $bits = explode('=', $piece, 2);
        if (count($bits) === 2) {
            $fields[trim($bits[0])] = trim($bits[1]);
        }
    }

    if (!isset($fields['t'], $fields['v1'])) {
        return false;
    }

    $rawTimestamp = $fields['t'];
    $received     = $fields['v1'];

    // 1. Tolerance, both directions.
    if (!ctype_digit($rawTimestamp)) {
        return false;
    }
    if (abs(time() - (int) $rawTimestamp) > $toleranceS) {
        return false;
    }

    // 2. Recompute over "{t}." + the exact bytes received.
    //    $secret is the whsec_… string as-is: no base64_decode, no prefix stripping.
    $expected = hash_hmac('sha256', $rawTimestamp . '.' . $rawBody, $secret);

    // 3. Constant-time compare.
    return hash_equals($expected, $received);
}

// --- handler ---------------------------------------------------------------

$rawBody = file_get_contents('php://input');           // read once, keep it
$header  = $_SERVER['HTTP_AMOMIC_SIGNATURE'] ?? null;  // Amomic-Signature
$secret  = getenv('AMOMIC_WEBHOOK_SECRET');

if (!amomic_verify_signature($rawBody, $header, $secret)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);

enqueue($event['id'], $event);   // durable and fast

http_response_code(200);
echo 'ok';
```

```go Go
package amomic

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

const toleranceSeconds int64 = 300

// VerifySignature checks an Amomic-Signature header against the raw request body.
// secret is the whsec_… string exactly as issued.
func VerifySignature(rawBody []byte, header, secret string) bool {
	if header == "" {
		return false
	}

	var rawTimestamp, received string
	for _, piece := range strings.Split(header, ",") {
		key, value, found := strings.Cut(piece, "=") // first "=" only
		if !found {
			continue
		}
		switch strings.TrimSpace(key) {
		case "t":
			rawTimestamp = strings.TrimSpace(value)
		case "v1":
			received = strings.TrimSpace(value)
		}
	}
	if rawTimestamp == "" || received == "" {
		return false
	}

	// 1. Tolerance, both directions.
	timestamp, err := strconv.ParseInt(rawTimestamp, 10, 64)
	if err != nil {
		return false
	}
	skew := time.Now().Unix() - timestamp
	if skew < 0 {
		skew = -skew
	}
	if skew > toleranceSeconds {
		return false
	}

	// 2. Recompute over "{t}." + the exact bytes received.
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(rawTimestamp))
	mac.Write([]byte("."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))

	// 3. Constant-time compare.
	return hmac.Equal([]byte(expected), []byte(received))
}

// --- handler ---------------------------------------------------------------

func Handler(secret string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		// Read the body to []byte first. A json.Decoder on r.Body consumes it.
		rawBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
		if err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		if !VerifySignature(rawBody, r.Header.Get("Amomic-Signature"), secret) {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		var event struct {
			ID   string          `json:"id"`
			Type string          `json:"type"`
			Data json.RawMessage `json:"data"`
		}
		if err := json.Unmarshal(rawBody, &event); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			return
		}

		if err := Enqueue(event.ID, rawBody); err != nil {
			w.WriteHeader(http.StatusInternalServerError) // retryable
			return
		}

		w.WriteHeader(http.StatusOK)
	}
}
```

:::

## Which status code to return when verification fails

Return **`400`**.

A `400` stops the retry ladder immediately — any 4xx other than `429` tells us the request itself is wrong and repeating it will not help. That is exactly right for a signature failure: the same bytes will fail the same way four times, and burning four attempts on it only delays the events queued behind it.

Do **not** return `500` for a bad signature. A `500` is retryable, so a stream of forged requests would turn into four times as many forged requests, and genuine failures would take a minute longer to surface.

Do not return `200` either — you lose the ability to see the problem in the delivery log, and the console will show a healthy endpoint that is silently discarding everything.

## Troubleshooting: "signature does not match"

In descending order of how often each one is the actual cause.

::: details 1. You verified a re-serialised body
By far the most common. Your framework handed you a parsed object, you called `JSON.stringify` / `json.dumps` / `json_encode` on it, and hashed the result.

The body we sign has no spaces after `:` or `,`. Almost every standard serialiser adds them. Unicode escaping, key order, and float formatting can all differ too.

**Check:** log `rawBody.length` (or `len(raw_body)`) alongside the `Content-Length` header we sent. If they differ, you are not looking at our bytes. Log the first 80 characters of what you are hashing — if you see `{"id": "evt_` with a space after the colon, that is the bug.

**Fix:** capture bytes before anything parses them. See the framework table above.
:::

::: details 2. A body-parser middleware ran first
Same outcome as (1) but harder to spot, because your code never explicitly re-serialises anything — the framework did it for you and handed you an object that looks like the truth.

The classic is `app.use(express.json())` at the top of an Express app. By the time your route's `express.raw` runs, the stream has been drained; `req.body` is an object, `Buffer.isBuffer(req.body)` is false, and hashing it produces nonsense. Django's `request.POST`, Laravel middleware that rebuilds the request, and Next.js's default `bodyParser` all do the same thing in their own dialect.

**Check:** assert the type of what you received. In Node, `Buffer.isBuffer(req.body)` must be `true`. In Python, `type(raw)` must be `bytes`.

**Fix:** exclude the webhook route from global body parsing, or mount the raw parser before the JSON one.
:::

::: details 3. Wrong secret
Every endpoint has its own signing secret. If you have a dev endpoint and a production endpoint, or you deleted and recreated an endpoint while debugging, the secret in your environment may belong to a different one.

Also check that you have not transformed it: no base64 decode, no stripping of the `whsec_` prefix, no trailing newline picked up from a file, no shell quoting that swallowed a character.

**Check:** print `len(secret)` and its first eight characters. It must start `whsec_`. Compare against the endpoint you are actually receiving from — the delivery log in the console tells you which endpoint got the request.

**Fix:** the secret is shown once and cannot be recovered. If you no longer have it, delete the endpoint and create a new one. There is no rotation endpoint.
:::

::: details 4. Clock skew
Your HMAC is right and you are rejecting on the tolerance check instead. This one appears suddenly on a host that was fine yesterday, and it affects every request equally.

**Check:** log the computed skew, not just the boolean result — `int(time.time()) - timestamp`. If it is a consistent number of seconds (or a suspiciously round number of hours, which means a timezone bug rather than drift), that is your answer. Distinguishing this from a real HMAC mismatch takes one log line and is worth adding permanently.

**Fix:** run NTP. If you are inside a container on a host with correct time, check that the container is not frozen or suspended between deliveries.
:::

::: details 5. Wrong hash input
Ordinary mistakes in constructing the signed string:

- Hashing the body alone, without `{t}.` in front.
- Hashing the whole header value instead of just the `v1` portion's input.
- Using `.` where you meant to join with something else, or forgetting the separator entirely.
- Base64-encoding the digest instead of hex-encoding it. We send lowercase hex.
- Using SHA-1 or SHA-512.
- Uppercasing the hex digest before comparing. Ours is lowercase.

**Check:** hard-code a known delivery from the console's delivery log — the log stores the full envelope for bodies up to 2000 characters — and unit-test your verifier against it. A test that pins one real payload, one real timestamp, and one real signature catches all of these in one run and keeps catching them.
:::

::: details 6. A proxy rewrote the body
Rarer, but real, and maddening because your code is correct.

- **AWS API Gateway** may hand your Lambda a base64-encoded body. Check `isBase64Encoded` and decode before verifying.
- **Gateways that re-encode or pretty-print JSON** change the bytes. Anything that "normalises" a payload in transit invalidates the signature.
- **Character-set conversion.** If something between us and you transcodes UTF-8, a payload containing Devanagari or an emoji breaks while ASCII-only payloads verify fine. That pattern — some events verify, some do not — points straight here.
- **Compression or chunked-transfer handling** that appends a newline.

**Check:** if ASCII payloads pass and non-ASCII ones fail, it is an encoding problem in the path, not in your HMAC.
:::

## Rotation, and multiple `v1` values

A delivery today carries exactly one `v1` value. If you are writing a verifier from scratch, accepting a header that contains several `v1=` pairs and returning true if **any** of them matches costs you three lines and means a future rotation scheme would not require a code change on your side. That is forward-compatible advice, not current behaviour — do not write a verifier that *requires* more than one.

Note that a naive parse-into-a-map implementation, like the ones above, keeps only the last `v1`. That is fine today.

There is no secret-rotation endpoint. To change a signing secret you delete the endpoint and create a new one, which means a gap unless you add the new endpoint first, run both in parallel while your receiver accepts either secret, and then remove the old one.

## Next

::: cards

::: card What arrives in `data`
[Event reference](/webhooks/events) — the exact field list for each of the nine event types.
:::

::: card When verification is not the problem
[Retries and failures](/webhooks/reliability) — reading the delivery log, and why an endpoint got disabled.
:::

::: card The delivery contract
[Getting events](/webhooks/overview) — headers, envelope, and the rules your endpoint has to follow.
:::

::: card Securing the rest of it
[Security and data](/operate/security) — key handling, retention, and what we store.
:::

:::


----------------------------------------------------------------------------
## Event reference
URL: https://docs.amomic.in/webhooks/events
----------------------------------------------------------------------------

Nine event types exist. Not eight, not ten — the list is closed, and subscribing an endpoint to a name that is not on it is rejected when you save with `Unknown event types: <names>`.

This page is the field-level contract for each one. [Getting events](/webhooks/overview) covers the envelope and headers those fields arrive inside; [Verifying signatures](/webhooks/signatures) covers proving they came from us.

| Type | Fires when |
|---|---|
| `message.received` | A customer sends an inbound WhatsApp message |
| `message.status` | WhatsApp reports a delivery state change for a message you sent |
| `conversation.started` | A new conversation opens on any channel |
| `conversation.ended` | A conversation is closed |
| `call.started` | A call begins |
| `call.ended` | A call finishes |
| `ticket.created` | A ticket is opened |
| `ticket.updated` | An existing ticket changes |
| `lead.created` | A visitor leaves contact details |

Plus one that is not on the list and that your endpoint will still receive: [`ping`](#the-ping-test-event).

## Two rules that apply to every event

Read these before the tables. They explain most of what looks surprising below.

### Null fields are omitted, not sent as null

Every payload is built by copying an allow-list of fields and **dropping any whose value is null**. A field with no value is not `"text": null` — it is not in the JSON at all.

So a WhatsApp message with no text body produces this:

```json
{
  "channel": "whatsapp",
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
  "from": "+919876543210",
  "type": "image",
  "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
  "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
}
```

No `text` key. Not an empty string, not a null — absent.

::: danger This is the field-level bug that gets past testing
Your first three test messages all have text, so `event.data.text.trim()` works. The first customer who sends a photo takes the handler down with a `TypeError`, and because your endpoint now returns a `500`, the delivery is retried four times over the next minute and then keeps failing on every subsequent event. Fifteen consecutive failed events later the endpoint is [disabled](/webhooks/reliability).

Treat **every** field in every table below as optional. Read with `?.` and `??` in JavaScript, `.get()` in Python, `Optional[...]` in your typed model. The field lists tell you what *can* arrive, never what *will*.

```javascript
// Wrong — assumes the key is there
if (event.data.text.startsWith("STOP")) { … }

// Right
const text = event.data.text ?? "";
if (text.startsWith("STOP")) { … }
```

```python
# Wrong
if event["data"]["text"].startswith("STOP"): ...

# Right
if (event["data"].get("text") or "").startswith("STOP"): ...
```
:::

Two fields break the pattern in the other direction: `message_id` on `message.received` and `message.status` is always present and **can be `null`**. Handle both shapes — absent and present-but-null — with the same code, and the distinction stops mattering.

### The field lists are allow-lists

Payloads are not internal records with a few things stripped out. Each event copies a named set of fields and nothing else, so a field we add internally does not appear here by accident. Internal routing identifiers are specifically excluded.

The practical guarantee: **what is in the table is what you get.** If you need something that is not listed, fetch it from the REST API using the id in the event.

---

## `message.received`

Fires when a customer sends a message to one of your connected WhatsApp senders.

::: warning WhatsApp only
`channel` is always the literal string `"whatsapp"` because this event has exactly one source. Inbound web chat and inbound voice do **not** produce a `message.received`. For those, `conversation.started` is the arrival signal, and the turns themselves are read through [`GET /conversations/{id}/messages`](/api/conversations).

Do not write a router keyed on `data.channel` here expecting to branch — there is nothing to branch on.
:::

| Field | Type | Presence | Notes |
|---|---|---|---|
| `channel` | string | Always | Always `"whatsapp"`. |
| `message_id` | string \| null | Always, may be `null` | WhatsApp's own `wamid.…`. The id of the inbound message, not of anything you sent. |
| `from` | string \| null | Always, may be `null` | The customer's number as `+` followed by digits — `+919876543210`. |
| `text` | string | When the message had text | Absent for a message with no text body. |
| `type` | string | When known | WhatsApp's message type, for example `text` or `image`. WhatsApp owns this vocabulary; write a default branch. |
| `conversation_id` | string | When known | `con_…`. Use it with [`GET /conversations/{id}`](/api/conversations) to get the customer object and history. |
| `deployment_id` | string | When known | An opaque identifier for the deployment that handled the message. Safe to log, not useful to parse. |
| `event_id` | string | Always | Internal envelope id. **Not** the dedupe key — the top-level `id` is. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4a17b03e5d8194ca2f60",
  "type": "message.received",
  "created_at": "2026-08-01T10:00:00Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
    "from": "+919876543210",
    "text": "Where is my order AM-4821?",
    "type": "text",
    "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
    "deployment_id": "dep_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

::: note This fires whether or not an agent replies
The event is the inbound message arriving, not a request for you to answer it. A deployed agent handles the reply on its own and you do not need to do anything. Use this event to mirror inbound traffic into your own systems, to detect keywords like an opt-out, or to reset your own 24-hour-window clock — [the window](/channels/whatsapp-window) opens on exactly this message.
:::

---

## `message.status`

Fires when WhatsApp reports a state change for a message **you** sent. One event per state change, so a normally delivered and read message produces several.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `channel` | string | Always | Always `"whatsapp"`. |
| `message_id` | string \| null | Always, may be `null` | The `wamid.…` returned by [`POST /messages`](/api/messages). Your join key — store it when you send. |
| `status` | string | When known | The expected set is `sent`, `delivered`, `read`, `failed`. WhatsApp owns the vocabulary, so a value you have not seen is not an error condition. |
| `recipient` | string | When known | The customer's number as WhatsApp reports it — typically digits with no leading `+`, unlike `from` on `message.received`. Normalise before comparing. |
| `error` | string | On failure | WhatsApp's reason for a `failed` status. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4b1e7a3d5c8f0b2e6d41",
  "type": "message.status",
  "created_at": "2026-08-01T10:04:12Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
    "status": "delivered",
    "recipient": "919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

```json title="A failure"
{
  "id": "evt_9f2c4b1e7a3d5c8f0b2e6d42",
  "type": "message.status",
  "created_at": "2026-08-01T10:04:19Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
    "status": "failed",
    "recipient": "919876543210",
    "error": "Message failed to deliver.",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH5"
  }
}
```

::: warning Status events can arrive out of order
Delivery is at-least-once and unordered. A `read` can land before the `delivered` that logically preceded it, especially when one of them was retried.

Do not implement a state machine that only moves forward from what it last saw. Store the status against the `message_id` with the envelope's `created_at`, and let a later timestamp win — or keep them all as an append-only log and derive the current state on read.
:::

There is no equivalent event for the moment the API accepts your send. `POST /messages` answers that synchronously with `status: "sent"`, which means accepted for delivery and nothing more.

---

## `conversation.started`

Fires when a new conversation opens, on any channel.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `conversation_id` | string | When known | `con_…`. The handle for [`GET /conversations/{id}`](/api/conversations). |
| `channel` | string | When known | Where it happened — `web`, `whatsapp`, or `voice`. |
| `customer` | object | When known | Free-form identity from the channel. Observed keys include `name`, `display_name`, `email`, `external_id`. Every key is optional, and the whole object can be absent. |
| `deployment_id` | string | When known | Opaque identifier for the deployment handling it. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4c8d012e6a37f5b90c14",
  "type": "conversation.started",
  "created_at": "2026-08-01T09:41:18Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
    "channel": "web",
    "customer": {
      "display_name": "Rohit Sharma",
      "email": "rohit.sharma@example.in"
    },
    "deployment_id": "dep_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH6"
  }
}
```

`customer` is as good as the channel it came from. WhatsApp gives you a platform identity, voice gives you the caller's number, and web chat gives you whatever a lead form collected — which is nothing at all if the visitor never filled one in. An empty or missing `customer` is an ordinary case, not an exception.

---

## `conversation.ended`

Fires when a conversation is closed.

::: warning Identical payload to `conversation.started`
`conversation.ended` uses the same projection. The same four fields, the same rules, nothing added.

That means it does **not** carry a duration, a message count, a resolution, a summary, a satisfaction score, or a reason for ending. If you want any of that, take the `conversation_id` and call [`GET /conversations/{id}`](/api/conversations) — `message_count`, `status`, `preview`, and both timestamps are there.

The only thing distinguishing the two events is `type` at the envelope level. A handler that dispatches on `data` alone cannot tell them apart.
:::

| Field | Type | Presence | Notes |
|---|---|---|---|
| `conversation_id` | string | When known | `con_…`. |
| `channel` | string | When known | `web`, `whatsapp`, or `voice`. |
| `customer` | object | When known | Same free-form object as above. |
| `deployment_id` | string | When known | Opaque. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4d02b1e7f38a06c25d99",
  "type": "conversation.ended",
  "created_at": "2026-08-01T10:12:44Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
    "channel": "web",
    "customer": {
      "display_name": "Rohit Sharma",
      "email": "rohit.sharma@example.in"
    },
    "deployment_id": "dep_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH7"
  }
}
```

Conversations stay open until a team member closes them in the inbox — there is no session timeout that closes them for you, so this event is a human action far more often than an automatic one.

---

## `call.started`

Fires when a call begins. For an outbound call this is the same moment [`POST /calls`](/api/calls) returns its `201`, so if you placed the call you already know; the event matters most for inbound.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `call_id` | string | When known | `call_…`. The handle for [`GET /calls/{id}`](/api/calls). |
| `number` | string | When known | Your workspace's number on this call — the same value that appears as `from_number` on the REST call object. |
| `direction` | string | When known | `outbound` for a call you placed, `inbound` for a call to one of your numbers. |
| `to` | string | When known | The number dialled. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4e91c3a05f27d8b16e03",
  "type": "call.started",
  "created_at": "2026-08-01T11:02:07Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
    "number": "+919461093306",
    "direction": "outbound",
    "to": "+919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH8"
  }
}
```

Note what is not here: no `agent_id`, no `purpose`, and no `status`. Started means the call exists, not that anybody answered — there is no separate "answered" event, so the first thing you learn after this is `call.ended`.

---

## `call.ended`

Fires when a call finishes, for any reason — answered and completed, unanswered, failed.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `call_id` | string | When known | `call_…`. Matches the `call_id` from `call.started` and from `POST /calls`. |
| `duration_seconds` | integer | When known | Absent on a call that never connected. |
| `outcome` | string | When known | How the call finished. A plain string with no closed set declared — log unknown values, do not reject them. |
| `direction` | string | When known | `inbound` or `outbound`. |
| `to` | string | When known | The number dialled. |
| `summary` | string | When one was produced | An AI summary of the call. Frequently absent — never make your flow depend on it. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4f3a7b28d05e91c4a760",
  "type": "call.ended",
  "created_at": "2026-08-01T11:04:51Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
    "duration_seconds": 164,
    "outcome": "completed",
    "direction": "outbound",
    "to": "+919876543210",
    "summary": "Customer confirmed the delivery address and asked for the courier to call before arriving.",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH9"
  }
}
```

```json title="A call nobody answered"
{
  "id": "evt_9f2c500b4d19e63af07b2c85",
  "type": "call.ended",
  "created_at": "2026-08-01T11:31:12Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH5",
    "outcome": "no_answer",
    "direction": "outbound",
    "to": "+919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GHA"
  }
}
```

Note the second example: no `duration_seconds`, no `summary`. Nothing connected, so neither value exists, so neither key is in the JSON.

::: warning `call.ended` carries no recording and no status
Two things people reach for and do not find:

- **There is no `recording_uri` in this event**, and there is no `call.recording_ready` event either. If a recording exists, it appears as `recording_uri` on [`GET /calls/{call_id}`](/api/calls). Fetch it when you need it rather than waiting for a notification that will not come.
- **There is no `status` field.** The REST call object has both `status` and `outcome`; this event carries only `outcome`. If your data model needs the final status, read it back from `GET /calls/{call_id}`.

The general pattern for calls: react to the event, then fetch the record if you need more than these six fields.
:::

---

## `ticket.created`

Fires when a ticket is opened — through [`POST /tickets`](/api/tickets), by an agent during a conversation, or by a person in the console.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `ticket_id` | string | When known | `tkt_…`. The handle for [`GET /tickets/{id}`](/api/tickets). |
| `public_ref` | string | When known | `AM-XXXXXXXX`. The reference you quote to a customer. |
| `subject` | string | When known | The ticket subject. |
| `status` | string | When known | `new` at creation. |
| `priority` | string | When known | `low`, `normal`, `high`, or `urgent`. |
| `channel` | string | When known | Where the ticket came from. `api` for tickets you opened through `POST /tickets`. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c5119ae03c72f6d8b4051",
  "type": "ticket.created",
  "created_at": "2026-08-01T12:15:03Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "ticket_id": "tkt_4a17b03e5d8194ca2f60c918",
    "public_ref": "AM-3F9C21B7",
    "subject": "Payment captured twice for order AM-4821",
    "status": "new",
    "priority": "high",
    "channel": "api",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GHB"
  }
}
```

The payload deliberately excludes the ticket body. No `description`, no requester details, no tags, no SLA timestamp — those are on the ticket record, one `GET /tickets/{ticket_id}` away, and keeping them out of the event means a customer's problem description is not sitting in your webhook access logs.

---

## `ticket.updated`

Fires when an existing ticket changes. **Same six fields as `ticket.created`.**

| Field | Type | Presence | Notes |
|---|---|---|---|
| `ticket_id` | string | When known | `tkt_…`. |
| `public_ref` | string | When known | `AM-XXXXXXXX`. |
| `subject` | string | When known | Current subject. |
| `status` | string | When known | Current status. |
| `priority` | string | When known | Current priority. |
| `channel` | string | When known | Origin channel — unchanged from creation. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c5204bd71e38c05a9f612",
  "type": "ticket.updated",
  "created_at": "2026-08-01T14:48:30Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "ticket_id": "tkt_4a17b03e5d8194ca2f60c918",
    "public_ref": "AM-3F9C21B7",
    "subject": "Payment captured twice for order AM-4821",
    "status": "pending",
    "priority": "urgent",
    "channel": "api",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GHC"
  }
}
```

::: warning No diff, no previous values
The event tells you the ticket's state **now**. It does not tell you what changed, what it changed from, or who changed it. There is no `changes` object, no `previous`, no `updated_fields`.

If you care about transitions — alerting when something reaches `urgent`, stopping a clock when it resolves — compute the diff yourself by comparing against your stored copy. Since delivery is at-least-once and unordered, guard that comparison: an event you have already applied must be a no-op, and a stale event must not overwrite a newer state. The envelope's `created_at` is your ordering signal.
:::

---

## `lead.created`

Fires when a visitor leaves contact details — the web chat lead-capture form is the usual source.

| Field | Type | Presence | Notes |
|---|---|---|---|
| `contact_id` | string | When known | The contact record this lead resolved to. Opaque — treat it as a string, do not assume a format. It can be absent when contact resolution had a bad second, and the lead is still real. |
| `name` | string | When given | Absent if the form did not ask, or the visitor skipped it. |
| `email` | string | When given | Same. |
| `phone` | string | When given | Same. |
| `deployment_id` | string | When known | Opaque identifier for the deployment that captured it. |
| `event_id` | string | Always | Internal envelope id. |

```json title="POST to your endpoint"
{
  "id": "evt_9f2c53a8e1b40d69c2705f38",
  "type": "lead.created",
  "created_at": "2026-08-01T15:07:44Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "contact_id": "cnt_01JQRS4T8XZ0AB1CD2EF3GH4",
    "name": "Priya Nair",
    "phone": "+919876543210",
    "deployment_id": "dep_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GHD"
  }
}
```

Note that example: the visitor gave a name and a phone number and no email, so there is no `email` key. A lead form can be configured to ask for one, two, or all three fields, and a visitor can leave any of them blank — so a consumer that requires `email` will drop real leads on the floor.

This is the highest-value event to wire into a CRM, and also the one most likely to arrive partially filled. Route on whichever identifier is present.

---

## The `ping` test event

The **Test** action on a webhook endpoint in the console sends this, through the real delivery path with a real signature:

```json title="The literal test body"
{"id":"evt_test","type":"ping","data":{"message":"Amomic-AI webhook test"}}
```

Three things about it will break a strict consumer, and all three are worth designing for:

**`ping` is not a subscribable event type.** It is not in the list of nine, so you cannot tick a box for it and you cannot tick a box to avoid it. An endpoint subscribed to exactly `call.ended` still receives a `ping` when someone presses Test. Your router needs a default branch that returns `200` for an unrecognised `type` rather than erroring — which is also what protects you if the catalogue ever grows.

**It has no `created_at` and no `tenant_id`.** The body above is complete. A receiver that deserialises into a strict model with those fields required will reject the one delivery whose whole purpose is proving your receiver works.

**The id is the literal string `evt_test`, every time.** It arrives in the `Amomic-Event-Id` header too. That means a correctly built receiver — one that deduplicates on event id — will process the first test and silently acknowledge every test after it. That is your dedupe working, not your endpoint failing. Judge a test by what the console reports (`Your endpoint replied 200.` or `Your endpoint didn't respond.`), not by whether your logs show new work.

---

## What does not exist

None of the following is a gap waiting on a release. The catalogue is nine types and these are not among them.

| You might expect | Reality |
|---|---|
| `call.recording_ready` | Does not exist. `call.ended` has no recording URI either. Poll [`GET /calls/{call_id}`](/api/calls) for `recording_uri`. |
| A transcript in `call.ended` | No. Six fields, and the transcript is not one of them. |
| `conversation.ended` with a summary or duration | No — the payload is identical to `conversation.started`. Fetch the conversation. |
| `message.received` for web chat or voice | No. That event is WhatsApp-only. Use `conversation.started`. |
| An event for a message an agent sent | No outbound-message event exists. `message.status` reports WhatsApp's delivery state for messages **you** sent through the API. |
| A "call answered" event | No. `call.started` then `call.ended`, nothing between. |
| Ticket comment or reply events | No. `ticket.created` and `ticket.updated` are the only two. |
| `contact.created` or `contact.updated` | No. `lead.created` fires on lead capture; an upsert through [`POST /contacts`](/api/contacts) emits nothing. |
| Agent, deployment, knowledge base, or template events | No. Console configuration changes do not emit webhooks. |
| API key or webhook lifecycle events | No. |
| Batched deliveries | No. One event, one `POST`, one signature. |

## Routing safely

The `Amomic-Event-Type` header carries the same value as `type` in the envelope, so you can route before deserialising the body. Verify the signature first — a header is not evidence of anything until the HMAC checks out.

```javascript
// After verification, and after the event id has passed your dedupe check.
switch (event.type) {
  case "message.received":
    await mirrorInbound(event.data.conversation_id, event.data.text ?? "");
    break;

  case "message.status":
    await recordDelivery(event.data.message_id, event.data.status, event.created_at);
    break;

  case "call.ended":
    // duration_seconds and summary may both be absent.
    await closeCallRecord(event.data.call_id, {
      outcome: event.data.outcome ?? "unknown",
      durationSeconds: event.data.duration_seconds ?? null,
      summary: event.data.summary ?? null,
    });
    break;

  case "lead.created":
    await upsertCrmLead({
      name: event.data.name ?? null,
      email: event.data.email ?? null,
      phone: event.data.phone ?? null,
    });
    break;

  default:
    // `ping`, and anything added to the catalogue later.
    // Acknowledge, do not throw — a 500 here starts the retry ladder.
    break;
}
```

Three rules that snippet encodes:

- **Every read is defensive.** No field access assumes presence.
- **The default branch acknowledges.** An unknown `type` is a `200`.
- **Ordering comes from `created_at`**, not from arrival order.

## Related

::: cards

::: card Getting events
[The envelope and headers](/webhooks/overview) — what wraps every payload on this page, and the rules your endpoint has to follow.
:::

::: card Verifying signatures
[Prove it came from us](/webhooks/signatures) — the HMAC format, the tolerance window, and the raw-bytes rule.
:::

::: card Retries & failures
[When your endpoint has a bad day](/webhooks/reliability) — the retry ladder, auto-disable, and reconciling after an outage.
:::

::: card Order updates recipe
[A full loop](/recipes/order-updates) — send, `message.status`, `message.received`, and the handler that ties them together.
:::

:::


----------------------------------------------------------------------------
## Retries & failures
URL: https://docs.amomic.in/webhooks/reliability
----------------------------------------------------------------------------

Your endpoint will fail. A deploy will restart it mid-request, a database will lock, a certificate will expire on a Sunday. What matters is what happens next, and that is entirely determined by the status code you return and how many events in a row go wrong.

This page is the delivery contract from the failure side: the ladder, the rules that stop it, the counter that switches your endpoint off, and — the part people find too late — what you can and cannot recover once an outage is over.

## The retry ladder

Each event gets up to **four attempts**, with a fixed backoff between them.

```mock
{"component": "RetryDiagram", "props": {"caption": "Four attempts, 2s then 10s then 45s apart. About 57 seconds of backoff in total, and then the event is abandoned."}}
```

| Attempt | Sent after | `Amomic-Delivery-Attempt` |
|---|---|---|
| 1 | Immediately | `1` |
| 2 | 2 seconds | `2` |
| 3 | 10 more seconds | `3` |
| 4 | 45 more seconds | `4` |

Roughly **57 seconds of backoff** from the first attempt to the last. Attempts are sequential — attempt 2 never starts until attempt 1 has answered or timed out — so on an endpoint that hangs, the wall-clock span is longer: each attempt has a **10-second total timeout** with **5 seconds to connect**, which puts the worst case near a minute and a half.

After the fourth attempt the event is abandoned. It is not queued, not parked, and not redeliverable later. That is the entire budget, and it is why the [fast-ack pattern](#build-a-receiver-that-survives) matters more than any amount of retry logic on your side.

Read `Amomic-Delivery-Attempt` and log it. Anything above `1` means you already failed this event once, which is information you will want when a duplicate turns up in your database.

## What retries, and what stops

The rule is short: **any 4xx other than 429 stops the ladder immediately.** Everything else that is not a success is retried.

| Your response | Retried | Why |
|---|---|---|
| `200`–`299` | **No** — success | Delivered. The failure counter for your endpoint resets to zero. |
| `429 Too Many Requests` | **Yes** | You are asking us to slow down, not telling us the request is wrong. |
| `500`, `502`, `503`, `504` | **Yes** | Your server broke. The same request may well work in ten seconds. |
| Connection refused, DNS failure, TLS error | **Yes** | Nothing reached your application. Almost always transient or a config problem being fixed. |
| Timeout — no answer within 10 seconds | **Yes** | We do not know whether you processed it, so we assume you did not. |
| `301`, `302`, `307` and other redirects | **Yes**, but pointlessly | Redirects are **not followed**. Every attempt gets the same redirect and the event is lost after four. |
| `400`, `401`, `403`, `404`, `410`, `422` | **No** — abandoned at once | A 4xx is your endpoint saying "this request is wrong". Repeating an identical request cannot make it right. |

The reasoning behind the 4xx rule is worth internalising because it cuts both ways. A `404` means the route does not exist; retrying it for a minute produces four identical misses and no useful outcome. A `401` means your endpoint rejected our credentials, which will not change in 45 seconds. Abandoning immediately is the honest response to "you have the wrong idea about my server", and it keeps a misconfigured endpoint from being hammered.

::: danger Never return a 4xx for a problem you could recover from
This is the single most expensive mistake on this page. A `400` returned because your JSON parser choked, your queue was full, or a downstream service was briefly unavailable **permanently discards that event**. No retry, no replay, no way to ask for it again.

The discipline is one line:

- Return **`400`** for exactly one thing: signature verification failed. That is genuinely unfixable by retry, and refusing it is correct.
- Return **`500`** for everything else that went wrong — a parse failure, a full queue, a dead database, an unexpected exception. A `500` buys you three more attempts across the next minute, which is usually enough for a restarting process to come back.

If you are unsure which one to return, return `500`. The cost of an extra retry is a duplicate you already deduplicate; the cost of a wrong `400` is a lost event.
:::

Redirects deserve their own warning because they fail silently. We do not follow them — signing a payload for a host we never agreed to talk to is not something a webhook sender should do — so a platform that quietly redirects `/hooks/amomic` to `/hooks/amomic/` turns every delivery into four wasted attempts. Register the exact final URL, including the trailing slash if your framework wants one.

## Fifteen failed events disables the endpoint

Every endpoint carries a `consecutive_failures` counter.

- A delivery that ends in success sets it to **0**.
- A delivery that exhausts all four attempts increments it by **1**.

At **15** the endpoint is switched off: `enabled` becomes `false` and a reason is recorded —

> Disabled automatically after 15 consecutive failed deliveries.

::: warning The counter is per event, not per attempt
Fifteen failed **events**, each of which may have burned four HTTP attempts. That is up to sixty requests to your server before anything is disabled.

It also means the wall-clock warning you get is longer than the number suggests. At roughly a minute per failed event, a completely dead endpoint takes on the order of fifteen minutes of sustained failure to trip — and a low-traffic workspace can take days, because the counter measures events, not time.
:::

The counter is consecutive, so a single success anywhere in the sequence resets it. An endpoint that fails fourteen events, succeeds once, and then fails fourteen more will never auto-disable — which is the desired behaviour for a flaky dependency, and a reason not to rely on auto-disable as your monitoring.

### A disabled endpoint receives nothing

It is not paused, not buffered, not queued. Events that occur while an endpoint is disabled are simply never delivered to it, and there is no way to get them afterwards. Other endpoints on the same workspace are unaffected — each has its own counter and its own fate.

### Re-enabling

Open **Developers → Webhooks** in the console. A disabled endpoint shows its `disabled_reason`; switch `enabled` back on and two things happen at once: `consecutive_failures` resets to `0`, and the reason is cleared. Deliveries resume with the next event that occurs.

::: steps

::: step Fix the endpoint first

Re-enabling a still-broken endpoint just spends another fifteen events. Use the **Test** action to send a `ping` through the real delivery path and confirm your server answers `200` before you turn it back on.
:::

::: step Re-enable it

The toggle resets the counter. Nothing else about the endpoint changes — same URL, same signing secret, same event subscriptions.
:::

::: step Reconcile the gap

Everything that happened while it was off is gone from the delivery path. Work out what you missed from [the reconciliation table below](#after-an-outage-there-is-no-replay) and pull it from the REST API.
:::

:::

## The delivery log

Every event, for every endpoint, writes one delivery record. You read them in the console at **Developers → Webhooks**, on the endpoint's deliveries view.

| Field | Type | Meaning |
|---|---|---|
| `delivery_id` | string | This delivery record. |
| `endpoint_id` | string | Which endpoint it went to. One event to three endpoints writes three records. |
| `event_type` | string | The event type, for example `call.ended`. |
| `event_id` | string | The `evt_…` from the envelope — the same value you deduplicate on. This is how you match a record here against a line in your own logs. |
| `attempt` | integer | The attempt number the run **ended on**, `1`–`4`. `1` means it worked first time; `4` means the ladder was exhausted. |
| `status_code` | integer \| null | What your endpoint returned on the final attempt. **`null` means no HTTP response at all** — a timeout, a refused connection, a TLS failure. |
| `error` | string \| null | Your response body, or the exception type and message for a transport failure. Truncated to 200 characters. |
| `duration_ms` | integer \| null | How long the **last** attempt took. Not a total across attempts. |
| `succeeded` | boolean | Whether the event was ultimately delivered. |
| `payload` | object | The full envelope we sent — but only when the body was 2000 characters or smaller. Larger payloads are recorded as `{}`. |
| `created_at` | string \| null | When the record was written, which is after all attempts finished. |

Two things about this log surprise people:

**One record per event, not per attempt.** Despite the `attempt` field, the record is written once, after the whole ladder completes. You cannot see attempt 2's status code separately from attempt 4's — you see where it ended.

**Records live for 7 days.** Delivery records and the API request log share the same 7-day retention. A delivery from last month is not there and cannot be recovered. If you need a permanent audit trail of what arrived, that is your own logs' job — which is another reason to log the event id on receipt.

The endpoint itself also carries live bookkeeping you can read at a glance: `last_delivery_at`, `last_status`, `consecutive_failures`, and `disabled_reason`. `consecutive_failures` climbing above zero is the earliest warning you get.

## Build a receiver that survives

### 1. Deduplicate on the event id

Delivery is at-least-once. That is the guarantee, not an apology — a delivery that times out at 10 seconds and succeeds on your side at 11 seconds gets retried, and both copies are real.

Make the check the first thing your worker does, and make it atomic:

```sql
-- The whole mechanism. Zero rows affected means you have seen this event.
INSERT INTO amomic_events (event_id, event_type, created_at, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;
```

Three details that make it correct:

- **Key on the envelope's top-level `id`**, which is the same value as the `Amomic-Event-Id` header. Do **not** key on `data.event_id` — that is a different, internal identifier that rides along inside the payload and is not the delivery identity. Keying on the wrong one is a bug you will not notice until the first redelivery.
- **Insert before you do the work, not after.** If you process first and record second, a crash in between gives you a duplicate on the retry.
- **Prune the table on a schedule.** The ladder finishes inside two minutes, so a retention of a day or two is generous. An unbounded dedupe table becomes its own outage eventually.

Deduplication is not a substitute for idempotent business logic. `ticket.updated` events arrive unordered, so "apply the change" has to be safe to apply twice and safe to apply late — compare the envelope's `created_at` against what you have stored and let the newer one win. [Event reference](/webhooks/events) covers the ordering rules per type.

### 2. Acknowledge fast, work later

The 10-second timeout is an **acknowledgement budget, not a work budget**. Inside the request handler, do only what cannot be deferred:

1. Read the raw bytes.
2. Verify the signature. Fail → `400`.
3. Insert the event id. Already present → `200`, stop.
4. Write the event to a durable queue. Fail → `500`.
5. Return `200`.

Everything else — the CRM write, the email, the third-party call, the report refresh — happens in a worker that can take as long as it needs and retry on its own terms.

This is not a performance nicety. A handler that does real work inline will, on its slowest day, cross 10 seconds while succeeding. We cut the connection, count the delivery as failed, retry it, and your worker processes it a second time. You have paid for a duplicate and moved a step closer to auto-disable, for a request that actually worked.

### 3. Return the right status code

Restating the earlier rule, because it belongs in your handler's structure:

```javascript
app.post("/hooks/amomic", express.raw({ type: "application/json" }), async (req, res) => {
  // Unfixable by retry — and the ONLY case that deserves a 4xx.
  if (!verify(req.body, req.get("Amomic-Signature"), SECRET)) {
    return res.status(400).send("bad signature");
  }

  let event;
  try {
    event = JSON.parse(req.body.toString("utf8"));
  } catch (err) {
    // Tempting to return 400 here. Do not — that discards the event forever.
    // If our body is unparseable, something is wrong that a retry might survive.
    return res.status(500).send("parse failed");
  }

  try {
    const isNew = await recordEventId(event.id); // INSERT … ON CONFLICT DO NOTHING
    if (isNew) await queue.enqueue(event.id, event);
  } catch (err) {
    return res.status(500).send("could not enqueue"); // buys three more attempts
  }

  return res.status(200).send("ok");
});
```

### 4. Monitor your own endpoint

Auto-disable is a circuit breaker, not an alert. By the time it trips you have lost fifteen events, and on a quiet workspace it may not trip for days while you silently receive nothing.

Watch four things:

- **Deliveries received per hour.** The most valuable alert you can build is on *absence*: zero events in a window where you normally see traffic. This catches a disabled endpoint, a DNS change, and an expired certificate — none of which produce an error in your logs, because nothing reaches your logs.
- **`Amomic-Delivery-Attempt` above 1.** A rising rate means you are failing first attempts, which is the leading indicator of everything on this page. Count it as a metric.
- **Your handler's p99 latency against the 10-second budget.** Alert at 3 seconds. If your acknowledgement path is anywhere near the timeout, you are one slow dependency away from duplicates.
- **`consecutive_failures` in the console.** Any non-zero value is worth a look. It only reaches 15 if nobody looked for a long time.

The two silent killers that produce no errors on your side: a **TLS certificate expiring** (we cannot connect, you see nothing), and a **platform-level redirect** appearing after a framework upgrade (every delivery becomes four wasted attempts). Both look identical from your seat — traffic simply stops.

## After an outage: there is no replay

Once you have fixed your endpoint, the honest position:

::: danger There is no replay or redelivery endpoint
You cannot ask for missed events. There is no "resend from timestamp", no redeliver button on a delivery record, no dead-letter queue you can drain, and support cannot replay them for you. Events abandoned after four attempts, or generated while your endpoint was disabled, are gone from the delivery path permanently.

Catching up means **reconciling through the REST API**. What that costs — and whether it is even possible — depends on which events you missed.
:::

### What you can recover

| Missed event | Recoverable? | How |
|---|---|---|
| `conversation.started`, `conversation.ended` | **Yes** | Walk [`GET /conversations`](/api/conversations). Ordered newest-activity-first, so stop when you reach your watermark. |
| `message.received` | **Yes**, indirectly | The turns are in the transcript. For every conversation that moved, re-read [`GET /conversations/{id}/messages`](/api/conversations) and upsert on `message_id`. |
| `call.started`, `call.ended` for calls **you placed** | **Yes** | You stored the `call_id` from the `201` on [`POST /calls`](/api/calls). Poll [`GET /calls/{call_id}`](/api/calls) for each one that has no outcome yet. |
| `ticket.created` for tickets **you opened** | **Yes** | You have the `ticket_id` from the `201`. Read it back with [`GET /tickets/{ticket_id}`](/api/tickets). |
| `call.started`, `call.ended` for **inbound** calls | **No** | There is no call list endpoint, so there is no id to fetch. The voice conversation may still surface in `GET /conversations` with `channel: "voice"` — that is your only trace through the API. |
| `ticket.created` / `ticket.updated` from agents or staff | **No** | There is no ticket list endpoint. Tickets are enumerable only in the console. |
| `message.status` | **No** | Delivery receipts have no read side at all. A `delivered` or `read` you missed is not retrievable. |
| `lead.created` | **No** | There is no contact read endpoint. The console's Contacts directory is the only place to see them. |

The pattern is consistent and worth naming: **anything with a list endpoint is recoverable, anything without one is not.** [Overview](/api/overview) has the route table, which doubles as a map of what you can catch up on.

### Designing so the gaps do not hurt

Three habits make the unrecoverable rows tolerable:

**Store the id at the moment you create something.** The `call_id` from `POST /calls` and the `ticket_id` from `POST /tickets` are the only handles you will ever get for those records. Write them to your own database in the same transaction that decided to make the call. An integration that discards the `201` body has permanently lost the ability to reconcile.

**Treat `message.status` as an enrichment, not a source of truth.** The durable fact is the `201` from `POST /messages`, which means accepted for delivery. Build your reporting so a missing `delivered` reads as "unknown", not as "failed" — otherwise an hour of downtime looks like an hour of failed messages.

**Run the conversation sync anyway.** The usual production shape is both mechanisms: webhooks for reaction, a scheduled walk of `GET /conversations` for completeness. If that job already exists and keeps a watermark, most of an outage repairs itself on the next run with no special code. [Conversations](/api/conversations) has the watermark pattern, and [Sync conversations](/recipes/sync-conversations) has the scheduled version.

### The runbook

::: steps

::: step Confirm what actually broke

Console → **Developers → Webhooks**. Check `enabled`, `disabled_reason`, `last_status`, and `consecutive_failures`. Then open the deliveries view: a `status_code` of `null` means we never got a response, a `500` means your app answered and failed, a `301` means a redirect you did not know about.
:::

::: step Fix it, then prove it with Test

The **Test** action sends a `ping` through the real path with a real signature. The console tells you what your server replied. Do not skip this — re-enabling a broken endpoint spends another fifteen events.
:::

::: step Re-enable

The toggle resets `consecutive_failures` and clears `disabled_reason`.
:::

::: step Establish the window

`last_delivery_at` on the endpoint, plus the last event id in your own database, bound the gap. You need the start time for the reconciliation query.
:::

::: step Reconcile forward

Walk `GET /conversations` from page one until you reach conversations older than the start of the gap. Re-read transcripts for anything that moved. Poll `GET /calls/{id}` for calls you placed and never closed. Accept the rows in the table above that cannot be recovered, and log the gap so a confused analyst three weeks from now finds an explanation.
:::

:::

## Related

::: cards

::: card Getting events
[The delivery contract](/webhooks/overview) — envelope, headers, and the rules your endpoint has to follow.
:::

::: card Event reference
[All nine event types](/webhooks/events) — exact fields, the omission rule, and the `ping` your endpoint must tolerate.
:::

::: card Verifying signatures
[The one 4xx worth returning](/webhooks/signatures) — HMAC format, the tolerance window, and the raw-bytes rule.
:::

::: card Sync conversations
[The reconciliation job](/recipes/sync-conversations) — the scheduled walk that repairs most of an outage for free.
:::

:::


============================================================================
# SECTION: Recipes
============================================================================



----------------------------------------------------------------------------
## Send an order update on WhatsApp
URL: https://docs.amomic.in/recipes/order-updates
----------------------------------------------------------------------------

This is the integration most workspaces build first: your order system marks a shipment dispatched, the customer gets a WhatsApp message about it, and when they reply with "where is it exactly?" your agent answers without a human touching it.

It is a small amount of code. Almost all of the work is in the four things around the send — picking a template instead of text, making the retry safe, branching on the failure, and closing the loop with webhooks. This page builds the whole thing.

## What you need before you start

- **An approved template.** Meta approves templates, not us, and only an approved one can be sent. Create it in **Channels → WhatsApp → Templates** and wait for `approved`. See [Templates](/channels/whatsapp-templates).
- **A connected WhatsApp sender.** `GET /channels` tells you what your workspace has. See [Set up WhatsApp](/channels/whatsapp).
- **An API key with `messages:send`.** New keys are read-only by default — widen it in the console. See [Scopes](/api/scopes).
- **A webhook endpoint** subscribed to `message.status` and `message.received`. See [Getting events](/webhooks/overview).

## The flow end to end

1. Your order system transitions an order to `shipped` and enqueues a job.
2. The job sends an approved template through `POST /messages` with an `Idempotency-Key` derived from the order.
3. `message.status` webhooks arrive as WhatsApp moves the message through `sent` → `delivered` → `read`.
4. The customer replies. That inbound message opens a 24-hour window and fires `message.received`.
5. Your deployed agent answers inside that window, in the same thread. Nothing further is required from your backend.

## Why a template and not text

WhatsApp only lets a business send free-form text inside a **24-hour customer service window**, which opens when the customer messages you and closes 24 hours after their last message. An order shipping is a business event, not a reply — the window is almost never open when it happens.

Send free-form text with the window closed and you get:

```json title="409 Conflict"
{
  "error": {
    "code": "conflict",
    "message": "The 24-hour session window is closed; only approved template messages can be sent.",
    "details": { "reason": "session_window_closed" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Templates bypass the window. That is the entire reason they exist. [The 24-hour window](/channels/whatsapp-window) covers the rule in full.

::: warning Do not "try text first, fall back to a template"
It looks clever and it is a bug. You spend a round trip to discover a state you already know, and if the window happens to be open you send a differently-worded message to some customers and not others. Notification flows send a template every time. Reply flows send text.
:::

The template you send here has two body variables:

```mock
{"component": "WhatsAppMock", "props": {"body": "Hi Asha, your order AM-4821 has shipped and should arrive in 2-3 days. Reply here if you need anything.", "time": "10:04", "caption": "The approved template with variables 1 and 2 substituted. The customer's reply to this message opens the 24-hour window."}}
```

## Deriving the Idempotency-Key

`POST /messages` honours `Idempotency-Key`. Within 24 hours, a repeat of the same key with the same body replays the stored response instead of sending a second message. That is what makes a retry after a timeout safe.

Derive the key from something your own system already treats as unique. The rule that matters: **one key per real-world event**, not per attempt and not per order.

| Key | Verdict |
|---|---|
| `order-4821-shipped` | Correct. One shipment event, retried as many times as needed. |
| `order-4821` | Wrong. The "delivered" message later reuses it, hits a different body, and 409s. |
| `crypto.randomUUID()` | Wrong. Every retry is a new key, so every retry sends another message. |
| `2026-08-01T10:04:00Z-4821` | Wrong if the timestamp is generated at attempt time — the retry gets a different key. |

Two more properties to code against:

- **The key is scoped to your workspace, that API key, and that endpoint.** `order-4821-shipped` on `POST /messages` and on `POST /tickets` do not collide.
- **The body must be byte-identical on the retry.** The match is a hash of the raw request bytes. Re-serialising a dictionary with a different key order counts as a different body and returns `409` with `idempotency_key_reuse`. Serialise the JSON **once** and resend the same string.

After 24 hours the record expires and the same key sends a fresh message — which is the correct behaviour for a retry queue that only just drained, and the wrong behaviour for a job you replayed from an archive.

[Idempotency](/api/idempotency) has the full contract.

## The send

Build the body once, POST it, branch on the outcome. Both versions below are complete and runnable.

::: codegroup

```javascript Node.js
// send-order-update.js
const BASE_URL = "https://services.amomic.in/api/v1";
const API_KEY = process.env.AMOMIC_API_KEY;

// 429 and 5xx are worth retrying. Everything else is a decision, not a blip.
const RETRYABLE = (status) => status === 429 || status >= 500;
const BACKOFF_MS = [1_000, 5_000, 20_000];

class AmomicError extends Error {
  constructor(status, error) {
    super(`${error.code}: ${error.message}`);
    this.status = status;
    this.code = error.code;
    this.reason = error.details?.reason ?? null;
    this.details = error.details ?? {};
    this.requestId = error.request_id;
  }
}

async function sendOrderShipped(order) {
  // Serialise once. The idempotency match is on raw bytes, so every retry
  // must send this exact string.
  const body = JSON.stringify({
    to: order.customerPhone,               // "+919876543210" — digits and an optional +
    template: {
      name: "order_shipped",
      language: "en_US",
      variables: [order.customerName, order.reference],
    },
    metadata: { order_id: order.id },      // echoed back to you, never shown to the customer
  });

  const headers = {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `order-${order.id}-shipped`,
    "X-Correlation-Id": order.traceId,     // joins your logs to ours
  };

  for (let attempt = 0; ; attempt += 1) {
    let response;
    try {
      response = await fetch(`${BASE_URL}/messages`, { method: "POST", headers, body });
    } catch (networkError) {
      // No response at all. The send may or may not have happened — the
      // idempotency key is what makes retrying this safe.
      if (attempt < BACKOFF_MS.length) {
        await sleep(BACKOFF_MS[attempt]);
        continue;
      }
      throw networkError;
    }

    if (response.ok) {
      const sent = await response.json();
      // status: "sent" means accepted by WhatsApp, not delivered to the handset.
      // Delivery arrives later, on the message.status webhook.
      await recordOutboundMessage(order.id, sent.message_id);
      return sent;
    }

    const { error } = await response.json();

    if (RETRYABLE(response.status) && attempt < BACKOFF_MS.length) {
      await sleep(BACKOFF_MS[attempt]);
      continue;
    }

    throw new AmomicError(response.status, error);
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
```

```python Python
# send_order_update.py
import os
import json
import time
import httpx

BASE_URL = "https://services.amomic.in/api/v1"
API_KEY = os.environ["AMOMIC_API_KEY"]

BACKOFF_S = [1, 5, 20]


class AmomicError(Exception):
    def __init__(self, status: int, error: dict):
        super().__init__(f"{error['code']}: {error['message']}")
        self.status = status
        self.code = error["code"]
        self.details = error.get("details") or {}
        self.reason = self.details.get("reason")
        self.request_id = error.get("request_id")


def send_order_shipped(order) -> dict:
    # Serialise once. The idempotency match is on raw bytes, so every retry
    # must send this exact payload.
    body = json.dumps(
        {
            "to": order.customer_phone,          # "+919876543210"
            "template": {
                "name": "order_shipped",
                "language": "en_US",
                "variables": [order.customer_name, order.reference],
            },
            "metadata": {"order_id": order.id},  # echoed back, never shown to the customer
        }
    )

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"order-{order.id}-shipped",
        "X-Correlation-Id": order.trace_id,
    }

    with httpx.Client(timeout=30.0) as client:
        for attempt in range(len(BACKOFF_S) + 1):
            try:
                response = client.post(f"{BASE_URL}/messages", headers=headers, content=body)
            except httpx.RequestError:
                # No response at all. The idempotency key makes the retry safe.
                if attempt < len(BACKOFF_S):
                    time.sleep(BACKOFF_S[attempt])
                    continue
                raise

            if response.is_success:
                sent = response.json()
                # status "sent" is acceptance by WhatsApp, not delivery.
                record_outbound_message(order.id, sent["message_id"])
                return sent

            error = response.json()["error"]
            retryable = response.status_code == 429 or response.status_code >= 500
            if retryable and attempt < len(BACKOFF_S):
                time.sleep(BACKOFF_S[attempt])
                continue

            raise AmomicError(response.status_code, error)
```

:::

```json title="201 Created"
{
  "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
  "channel": "whatsapp",
  "to": "+919876543210",
  "status": "sent"
}
```

Store `message_id` against your order. It is the join key for every `message.status` webhook that follows.

::: note `status: "sent"` is an acceptance, not a receipt
It means WhatsApp took the message. Whether a handset ever displayed it is a separate fact that arrives asynchronously on `message.status`. Code that treats the 201 as proof of delivery will report a switched-off phone as a success.
:::

## Handling the failures that actually happen

Branch on `error.code` for the class of problem and `error.details.reason` for the specific cause. Five failures cover almost every real incident.

```responses
[
  {"status": 404, "code": "not_found", "reason": "template_not_found", "description": "No approved template by that name exists in this workspace."},
  {"status": 400, "code": "invalid_argument", "reason": "template_variables", "description": "Wrong number or shape of variables for that template's components."},
  {"status": 412, "code": "failed_precondition", "reason": "channel_not_connected", "description": "This workspace has no WhatsApp sender connected."},
  {"status": 409, "code": "conflict", "reason": "session_window_closed", "description": "Free-form text was sent with the 24-hour window closed."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "The same Idempotency-Key arrived with a different request body."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "More than 120 requests in one minute on this key."}
]
```

### `template_not_found` — 404

`"No approved WhatsApp template named 'order_shipped'."`

Three causes, in the order they occur in practice:

1. **The template is not approved yet.** Only `approved` templates send. `pending` and `rejected` both produce this 404 — the API does not distinguish them, so check the status in the console.
2. **The name is spelled differently.** Template names are `^[a-z0-9_]+$`, and `order_shipped` is not `Order_Shipped`.
3. **It was approved in a different workspace.** Templates belong to the WhatsApp Business Account connected to *this* workspace.

This is not retryable. Fail the job, alert, and fix the template. A retry loop against a 404 will run until your queue gives up and will not have sent anything.

### `template_variables` — 400

The template's body has two `{{n}}` placeholders and you sent one, or three. Header and button variables are separate fields — a template with a variable in its header needs `header_variables`, not a third entry in `variables`:

```json
{
  "to": "+919876543210",
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "header_variables": ["Asha"],
    "variables": ["AM-4821", "2-3 days"],
    "button_variables": ["4821"]
  }
}
```

`variables` accepts a positional array or a numbered object — `["Asha", "AM-4821"]` and `{"1": "Asha", "2": "AM-4821"}` are the same request. Not retryable; it is a code defect.

### `channel_not_connected` — 412

`"This workspace has no WhatsApp sender connected."` Nothing your integration sends will work until someone connects a number in the console. Treat it as a configuration alarm rather than a message failure — every message you attempt will fail identically until it is fixed.

If your workspace has several senders and you want a specific one, pass `sender_id` from `GET /channels`. Omit it and the workspace default is used.

### `idempotency_key_reuse` — 409

You reused a key with a different body. Almost always one of:

- The body is rebuilt per attempt and a timestamp, trace id, or dictionary ordering changed inside it.
- One key is being used for two different messages about the same order.

Fix the key derivation. Do not retry with a fresh key to "get past it" — that is exactly the double-send the header exists to prevent.

### `rate_limited` — 429

120 requests per minute per key, counted in a fixed one-minute window. There is no `Retry-After` header. Back off to the next minute boundary and resume; if you are sending in bulk, pace at roughly two per second rather than bursting and absorbing 429s. See [Rate limits](/api/rate-limits).

## The retry story, in one place

```mock
{"component": "RetryDiagram", "props": {"caption": "Network errors and 429/5xx retry with the same key and the same bytes. 4xx is a decision to make, not a blip to wait out."}}
```

| Outcome | Retry? | Why |
|---|---|---|
| Connection error, timeout, no response | Yes, same key, same bytes | The send may have happened. The idempotency key resolves it either way. |
| `429 rate_limited` | Yes, after backing off past the minute boundary | Transient by definition. |
| `500` / `502 provider_error` | Yes, with backoff | Ours or WhatsApp's, and usually brief. |
| `400`, `401`, `403`, `404`, `409`, `412` | No | Retrying cannot change the answer. Alert a human. |

One caveat worth designing around: the stored idempotency response is written **just after** the response is returned, so two retries fired milliseconds apart can both execute. Space your retries by at least a second — the backoff above already does.

And one boundary: idempotency records live for **24 hours**. A job replayed from a dead-letter queue three days later will send the message again. If your queue can do that, check your own "already notified" flag before calling the API.

## Closing the loop with `message.status`

Delivery is asynchronous. Subscribe to `message.status` and you get one event per state change:

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4b1e7a3d5c8f0b2e6d41",
  "type": "message.status",
  "created_at": "2026-08-01T10:04:12Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMkI5RUE4...",
    "status": "delivered",
    "recipient": "919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

The statuses you will see are `sent`, `delivered`, `read`, and `failed`. WhatsApp owns that vocabulary and we pass it through unchanged, so **write a default branch** — a status string you have never seen is not an error condition. On `failed`, `data.error` carries WhatsApp's reason.

Fields whose value is null are omitted from `data` entirely rather than sent as `null`. Read defensively.

Two rules for the handler itself:

- **Verify the signature against the raw request body.** Parsing and re-serialising changes the bytes and the HMAC will not match. This is the single most common webhook bug.
- **Deduplicate on the envelope `id`.** Delivery is at-least-once; the same event can arrive twice.

::: codegroup

```javascript Node.js
// webhook.js
import express from "express";
import crypto from "node:crypto";

const app = express();
const SIGNING_SECRET = process.env.AMOMIC_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_S = 300;

function verify(rawBody, header) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i), p.slice(i + 1)];
    }),
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_S) return false;

  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw, not express.json — the signature covers the exact bytes.
app.post("/hooks/amomic", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("Amomic-Signature") ?? "")) {
    return res.status(401).end(); // a non-429 4xx stops retries — correct here
  }

  const event = JSON.parse(raw);

  // Acknowledge first, work afterwards. Ten seconds is the whole budget.
  res.status(200).end();

  if (await alreadyProcessed(event.id)) return;   // at-least-once delivery
  await markProcessed(event.id);

  switch (event.type) {
    case "message.status": {
      const { message_id, status } = event.data;
      await updateOrderNotification(message_id, status); // sent | delivered | read | failed
      break;
    }
    case "message.received": {
      await handleCustomerReply(event.data);
      break;
    }
    default:
      break; // includes the console's "ping" test event
  }
});

app.listen(3000);
```

```python Python
# webhook.py
import os
import time
import hmac
import hashlib
import json
from fastapi import FastAPI, Request, Response

app = FastAPI()
SIGNING_SECRET = os.environ["AMOMIC_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE_S = 300


def verify(raw_body: bytes, header: str) -> bool:
    parts = {}
    for piece in header.split(","):
        key, _, value = piece.partition("=")
        parts[key] = value

    try:
        timestamp = int(parts.get("t", ""))
    except ValueError:
        return False
    if abs(time.time() - timestamp) > TOLERANCE_S:
        return False

    expected = hmac.new(
        SIGNING_SECRET.encode(),
        f"{timestamp}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))


@app.post("/hooks/amomic")
async def receive(request: Request) -> Response:
    raw = await request.body()  # raw bytes, never a re-serialised parse
    if not verify(raw, request.headers.get("Amomic-Signature", "")):
        return Response(status_code=401)  # a non-429 4xx stops retries

    event = json.loads(raw)

    if await already_processed(event["id"]):  # at-least-once delivery
        return Response(status_code=200)
    await mark_processed(event["id"])

    if event["type"] == "message.status":
        data = event["data"]
        await update_order_notification(data["message_id"], data.get("status"))
    elif event["type"] == "message.received":
        await handle_customer_reply(event["data"])

    return Response(status_code=200)
```

:::

::: warning Return 2xx quickly, then work
The delivery times out at 10 seconds. A slow handler burns four attempts over roughly a minute and, after 15 consecutive failed events, the endpoint is disabled automatically and receives nothing until an admin re-enables it. Acknowledge, enqueue, process. [Retries and failures](/webhooks/reliability) explains the ladder.
:::

## When the customer replies

The reply is the interesting half, and it mostly happens without you.

The customer taps your order update and types "it says out for delivery but nothing arrived". Three things follow:

1. **The 24-hour window opens.** From this moment you may send free-form text to this number, until 24 hours after their most recent message.
2. **`message.received` fires** with the text, the sender, and the `conversation_id`.
3. **Your deployed agent answers**, if an agent is deployed to that WhatsApp sender. It has your knowledge base and the conversation history; it does not need your backend involved.

```json title="message.received"
{
  "id": "evt_3d8a1f5c9b2e7a4d6c0f8b13",
  "type": "message.received",
  "created_at": "2026-08-01T10:31:44Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNEE3RjMx...",
    "from": "+919876543210",
    "text": "it says out for delivery but nothing arrived",
    "type": "text",
    "conversation_id": "con_01JQRS4T8XZ0AB1CD2EF3GH4",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

So what should your backend do with it? Usually one of three things:

**Nothing.** The agent handles it. This is the default and the right answer for "where is my order" — the agent can answer it from your knowledge base better and faster than a webhook round trip.

**Enrich your own records.** Match `from` to a customer, attach `conversation_id` to the order, and read the transcript later through `GET /conversations/{id}/messages` when you need it. See [Sync conversations into your warehouse](/recipes/sync-conversations).

**Send free-form text yourself,** now that the window is open. Same endpoint, `text` instead of `template`:

```bash
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821-tracking-detail" \
  -d '{
    "to": "+919876543210",
    "text": "Your parcel scanned at the Andheri hub at 09:12 and is out with the courier today."
  }'
```

Free-form text is capped at 4096 characters. Anything longer is split across several messages at paragraph and word boundaries rather than being truncated.

::: note The window is per customer, not per order
It opens on *their* message and closes 24 hours after their *last* one. A second reply extends it. Do not model it as a fixed 24 hours from your notification — that clock is not the one WhatsApp is counting.
:::

If the customer needs a human, open a ticket from the same handler: [Escalate a conversation to a ticket](/recipes/support-escalation).

## Opt-outs

A customer who replies `STOP` (also `unsubscribe`, `cancel`, `opt out`, `band karo`, `बंद करो`) is suppressed for your workspace. Subsequent sends to that number return:

```json title="403 Forbidden"
{
  "error": {
    "code": "permission_denied",
    "message": "Recipient has opted out.",
    "details": { "reason": "suppressed" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

This applies to templates too — an opt-out is not a window problem and cannot be worked around by switching message type. Record the suppression against your customer record so you stop trying. `START` resubscribes them.

## Going to production

- Send to a **real number you control** before launch, and read the whole thread on the handset. A template that reads fine in the console can read oddly with real variable values.
- Alert on `channel_not_connected` and `template_not_found` **separately** from generic failures. They are configuration incidents, and a generic "message failed" alert buries them.
- Log `error.request_id` on every failure. Quoting it to support turns a thread into a lookup.
- Check the **request log** in **Developers → Logs** when something looks wrong from your side. Every call your keys made is there for 7 days with its status, error code, and timing.

## Next

::: cards

::: card The endpoint reference
[POST /messages](/api/messages) — every field, every constraint, every error.
:::

::: card The window rule in full
[The 24-hour window](/channels/whatsapp-window) — when text works, when only a template does, and how the clock actually runs.
:::

::: card Call them instead
[Trigger an AI call from your CRM](/recipes/crm-call) — for the updates a message cannot carry.
:::

::: card Before you launch
[Going live](/operate/going-live) — the pre-launch checklist this recipe assumes you have worked through.
:::

:::


----------------------------------------------------------------------------
## Trigger an AI call from your CRM
URL: https://docs.amomic.in/recipes/crm-call
----------------------------------------------------------------------------

A deal moves to **Qualified**, or a renewal falls due, and someone should phone the customer. This recipe has your agent make that call — placed from your CRM's automation, with the outcome written back onto the record without anyone listening to a recording.

The call itself is asynchronous and that shapes the whole design. `POST /calls` returns as soon as the number rings. Everything you care about — whether they answered, how long they talked, what happened — arrives afterwards.

## What you need before you start

- **A phone number with an agent deployed to it.** Numbers are requested and KYC-verified in the console; the answering agent is set by activating a deployment on that number. See [Numbers and KYC](/channels/phone-numbers) and [Deployments](/build/deployments).
- **An API key with `calls:write`.** The same scope covers placing, reading, and hanging up.
- **A webhook endpoint** subscribed to `call.ended` — this is how you get the outcome. `call.started` is optional and useful for live dashboards.

::: danger Outbound calling compliance is yours
We place the call you ask for. There is no consent registry, no DND or DNC check, no calling-hours window, and no per-day cap in the platform. Whether a number may lawfully be called, at that hour, for that purpose, is a decision your system has to make before it calls `POST /calls`. Build the check into the CRM trigger, not into a policy document.
:::

## The sequence

```mock
{"component": "CallSequenceDiagram", "props": {"caption": "POST /calls returns at ringing. The outcome arrives later on call.ended — the 201 tells you almost nothing about how the call went."}}
```

1. Your CRM automation fires on a stage change and enqueues a job.
2. The job checks your own guards — do not call, quiet hours, already called today — then POSTs to `/calls`.
3. `201` comes back with `status: "ringing"` and a `call_id`. Store it on the CRM record.
4. If the call connects, the agent opens the conversation, states who it is calling for, and asks whether now is a good time.
5. `call.ended` fires with the outcome and duration. Your handler maps it to a disposition and writes it back.

## Choosing the caller-ID number

`from_number` is the number the customer sees, and it does more than that: **the agent that speaks is resolved from the caller-ID number, not from `agent_id`.**

That is the single most surprising thing about this endpoint, and it follows from how the platform works — an agent is bound to a number by activating a deployment, so the number already answers the question of who is calling. Passing `agent_id` does not choose an agent; it *asserts* which one you expect, and fails loudly if you are wrong:

```json title="412 Precondition Failed"
{
  "error": {
    "code": "failed_precondition",
    "message": "The agent deployed to this number is different from the one requested.",
    "details": {
      "reason": "agent_number_mismatch",
      "deployed_agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4"
    },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Send `agent_id` anyway. It converts "we silently called 400 customers with the renewals agent instead of the onboarding one" into a 412 on the first call.

The rules:

- `from_number` must be an **active number owned by your workspace**, matched on digits. A number belonging to another workspace is a `403`.
- **Omit it** and the first active number is used. That is fine for a workspace with one number and a latent bug for a workspace that adds a second.
- Your numbers are listed in the console under **Channels → Phone / Voice**. Pin the one you want in configuration rather than discovering it at call time.
- The destination cannot be one of your own numbers — that returns `400` with `self_dial`.

## Telling the agent why it is calling

`purpose` is up to 500 characters and it is not a label. It reaches the agent's opening line and its instructions for the whole call, so it is the difference between an agent that knows why it phoned and one that improvises.

Write it as a brief to a colleague, with the facts the agent will need:

```json
{
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
  "purpose": "Rohit's annual maintenance plan for AC unit AM-4821 renews on 15 August at ₹4,500. Confirm whether he wants to renew, and if he does, tell him a payment link follows on WhatsApp. If he wants to cancel, ask why and thank him.",
  "ring_seconds": 30,
  "metadata": { "crm_record_id": "opp_88213", "owner": "priya@acme.in" }
}
```

Good purposes name the customer's situation, the specific outcome you want, and what to do in the obvious branches. Bad ones — `"renewal call"` — leave the agent to guess, and it will.

The opening line is fixed by us, not generated from `purpose`: the agent identifies the business, discloses that it is a virtual assistant, and asks whether now is a good time — in that order, before anything else happens. You cannot replace that with a sales opener, and it is deliberate.

`metadata` is free-form, stored on the call, and never spoken. Put your CRM record id there so the `call.ended` handler does not need a lookup table.

## Placing the call

::: codegroup

```javascript Node.js
// place-call.js
const BASE_URL = "https://services.amomic.in/api/v1";
const API_KEY = process.env.AMOMIC_API_KEY;
const CALLER_ID = process.env.AMOMIC_CALLER_ID;   // "+912269850800"
const AGENT_ID = process.env.AMOMIC_AGENT_ID;     // asserts the deployed agent

async function placeRenewalCall(opportunity) {
  // Your compliance guards run here, before anything is dialled.
  if (opportunity.doNotCall) return { skipped: "do_not_call" };
  if (!withinCallingHours()) return { skipped: "outside_hours" };

  const body = JSON.stringify({
    to: opportunity.contactPhone,       // "+919876543210" — digits, optional +, nothing else
    from_number: CALLER_ID,
    agent_id: AGENT_ID,
    purpose: renewalBrief(opportunity),
    ring_seconds: 30,                   // 10-90
    metadata: { crm_record_id: opportunity.id },
  });

  const response = await fetch(`${BASE_URL}/calls`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      // One key per attempt-to-call, derived from the CRM event.
      "Idempotency-Key": `renewal-${opportunity.id}-${opportunity.stageChangedAt}`,
      "X-Correlation-Id": opportunity.traceId,
    },
    body,
  });

  if (response.ok) {
    const call = await response.json();
    // status is "ringing". Nobody has answered anything yet.
    await crm.update(opportunity.id, { amomicCallId: call.call_id, callState: "ringing" });
    return call;
  }

  const { error } = await response.json();
  const reason = error.details?.reason;

  if (response.status === 429 && reason === "call_concurrency") {
    // All 10 outbound slots are busy. Requeue; do not spin.
    await queue.retryIn(opportunity.id, 60_000);
    return { deferred: true };
  }

  if (response.status === 429) {
    await queue.retryIn(opportunity.id, 60_000);   // 120 requests/minute per key
    return { deferred: true };
  }

  // Everything else is a configuration or data problem. Surface it.
  await crm.update(opportunity.id, { callState: "failed", callError: reason ?? error.code });
  throw new Error(`${error.code}/${reason ?? "-"}: ${error.message} (${error.request_id})`);
}
```

```python Python
# place_call.py
import os
import json
import httpx

BASE_URL = "https://services.amomic.in/api/v1"
API_KEY = os.environ["AMOMIC_API_KEY"]
CALLER_ID = os.environ["AMOMIC_CALLER_ID"]   # "+912269850800"
AGENT_ID = os.environ["AMOMIC_AGENT_ID"]     # asserts the deployed agent


def place_renewal_call(opportunity) -> dict:
    # Your compliance guards run here, before anything is dialled.
    if opportunity.do_not_call:
        return {"skipped": "do_not_call"}
    if not within_calling_hours():
        return {"skipped": "outside_hours"}

    body = json.dumps(
        {
            "to": opportunity.contact_phone,   # "+919876543210"
            "from_number": CALLER_ID,
            "agent_id": AGENT_ID,
            "purpose": renewal_brief(opportunity),
            "ring_seconds": 30,                # 10-90
            "metadata": {"crm_record_id": opportunity.id},
        }
    )

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
        # One key per attempt-to-call, derived from the CRM event.
        "Idempotency-Key": f"renewal-{opportunity.id}-{opportunity.stage_changed_at}",
        "X-Correlation-Id": opportunity.trace_id,
    }

    with httpx.Client(timeout=30.0) as client:
        response = client.post(f"{BASE_URL}/calls", headers=headers, content=body)

    if response.is_success:
        call = response.json()
        # status is "ringing". Nobody has answered anything yet.
        crm.update(opportunity.id, amomic_call_id=call["call_id"], call_state="ringing")
        return call

    error = response.json()["error"]
    reason = (error.get("details") or {}).get("reason")

    if response.status_code == 429:
        # call_concurrency: all 10 outbound slots busy. rate_limited: 120/min on the key.
        queue.retry_in(opportunity.id, seconds=60)
        return {"deferred": True}

    crm.update(opportunity.id, call_state="failed", call_error=reason or error["code"])
    raise RuntimeError(f"{error['code']}/{reason or '-'}: {error['message']} ({error['request_id']})")
```

:::

```json title="201 Created"
{
  "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
  "status": "ringing",
  "direction": "outbound",
  "to": "+919876543210",
  "from_number": "+912269850800",
  "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
  "duration_seconds": null,
  "outcome": null,
  "summary": null,
  "recording_uri": null,
  "started_at": null,
  "ended_at": null
}
```

::: warning 201 means ringing
Every field that describes how the call went is `null`, because none of it has happened. A pipeline that marks the opportunity "contacted" on the 201 will report every unanswered phone as a successful conversation.
:::

## Errors worth handling by name

```responses
[
  {"status": 429, "code": "rate_limited", "reason": "call_concurrency", "description": "This workspace already has 10 calls in progress. `details.limit` is 10. Requeue."},
  {"status": 412, "code": "failed_precondition", "reason": "no_agent_deployed", "description": "No agent is deployed to the caller-ID number, so nobody would speak."},
  {"status": 412, "code": "failed_precondition", "reason": "agent_number_mismatch", "description": "`agent_id` is not the agent on that number. `details.deployed_agent_id` names the real one."},
  {"status": 412, "code": "failed_precondition", "reason": "no_phone_number", "description": "The workspace owns no phone number at all."},
  {"status": 412, "code": "failed_precondition", "reason": "workspace_suspended", "description": "Billing suspension. Outbound calling stops until it is resolved."},
  {"status": 403, "code": "permission_denied", "reason": "unknown_from_number", "description": "`from_number` is not one of this workspace's numbers."},
  {"status": 400, "code": "invalid_argument", "reason": "self_dial", "description": "The destination is one of your own numbers."},
  {"status": 500, "code": "internal", "reason": "originate_failed", "description": "The call could not be placed downstream. Retry with a new idempotency key."}
]
```

Only two of those are worth an automatic retry: `call_concurrency` and `originate_failed`. The rest are configuration, and a retry loop against them just burns your rate limit.

## The concurrency limit

**Ten outbound calls per workspace at once.** The eleventh returns `429` with `details.reason` of `call_concurrency` and `details.limit` of `10`. This is separate from the 120-requests-per-minute key limit and is not affected by it.

For a CRM trigger firing a handful of calls a day, you will never see it. For a batch — 200 renewals on the first of the month — you must pace, because the limit counts *live calls*, not requests, and a three-minute conversation holds its slot for three minutes.

The shape that works:

- Keep a worker pool of at most 8 or 9 concurrent calls, leaving headroom for anything else in the workspace that dials.
- Release a slot when `call.ended` arrives, not when the 201 does.
- On `call_concurrency`, requeue with a delay of about a minute. Do not retry immediately; the slot is busy for as long as the conversation lasts.

## Waiting for the outcome

Subscribe to `call.ended`. It is the event the whole recipe exists for.

```json title="POST to your endpoint"
{
  "id": "evt_7b1e9a3c5d2f8e6a0c4b7d92",
  "type": "call.ended",
  "created_at": "2026-08-01T11:07:31Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4",
    "duration_seconds": 96,
    "outcome": "caller_hangup",
    "direction": "outbound",
    "to": "+919876543210",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Fields with no value are omitted rather than sent as `null`, so read with defaults. Delivery is at-least-once — deduplicate on the envelope `id`.

::: warning Do not poll in a loop
`GET /calls/{call_id}` exists and it is tempting to call it every two seconds until `status` changes. Don't. A three-minute call at that rate is 90 requests out of your 120-per-minute budget, for one call, to learn something that would have been pushed to you for free.

Use `call.ended` as the primary path. Keep polling as a **reconciliation sweep**: every 15 minutes, list your own records that have been `ringing` for longer than `ring_seconds` plus your maximum call length, and read those specific calls. That is a handful of requests an hour instead of thousands.
:::

The reconciliation sweep:

::: codegroup

```javascript Node.js
// reconcile-stuck-calls.js — run on a 15-minute schedule
async function reconcileStuckCalls() {
  // Ringing far longer than any real call could be: your ring_seconds plus
  // the maximum call length configured on the number.
  const stale = await crm.findCalls({ state: "ringing", olderThanMinutes: 20 });

  for (const record of stale) {
    const response = await fetch(`${BASE_URL}/calls/${record.amomicCallId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    if (response.status === 404) {
      await crm.update(record.id, { callState: "unknown" });
      continue;
    }
    if (!response.ok) continue;   // try again next sweep

    const call = await response.json();
    if (call.status === "ringing" || call.status === "in_progress") continue;

    await applyDisposition(record, call);
    await sleep(600);             // stay well inside 120 requests/minute
  }
}
```

```python Python
# reconcile_stuck_calls.py — run on a 15-minute schedule
import time
import httpx


def reconcile_stuck_calls() -> None:
    # Ringing far longer than any real call could be: your ring_seconds plus
    # the maximum call length configured on the number.
    stale = crm.find_calls(state="ringing", older_than_minutes=20)

    with httpx.Client(timeout=30.0) as client:
        for record in stale:
            response = client.get(
                f"{BASE_URL}/calls/{record.amomic_call_id}",
                headers={"Authorization": f"Bearer {API_KEY}"},
            )

            if response.status_code == 404:
                crm.update(record.id, call_state="unknown")
                continue
            if not response.is_success:
                continue  # try again next sweep

            call = response.json()
            if call["status"] in ("ringing", "in_progress"):
                continue

            apply_disposition(record, call)
            time.sleep(0.6)  # stay well inside 120 requests/minute
```

:::

## Mapping outcomes to dispositions

Two fields describe how a call finished. `status` is the coarse lifecycle state; **`outcome` is the one to map**, because it distinguishes a busy signal from a rejection from a conversation that ended normally.

An important detail: a call that was never answered still finalises with `status: "completed"` and `duration_seconds: 0`. Branching on `status` alone will book every voicemail as a conversation. Branch on `outcome`, and use `duration_seconds` to sanity-check it.

**The call never connected:**

| `outcome` | What happened | CRM disposition |
|---|---|---|
| `no_answer` | Rang out, or the network gave no better reason | `No answer` — retry later, count the attempt |
| `busy` | The line was engaged | `Busy` — retry sooner than a no-answer |
| `rejected` | The customer actively declined | `Rejected` — back off hard, treat as a soft opt-out |
| `invalid_number` | The number does not exist | `Bad number` — stop retrying, flag the record for correction |
| `unreachable` | Out of coverage or unroutable | `Unreachable` — retry, and stop after a few attempts |
| `congestion` | Network congestion | `Retry` — genuinely transient, safe to try again shortly |

**The call connected and a conversation happened:**

| `outcome` | What happened | CRM disposition |
|---|---|---|
| `caller_hangup` | The customer ended the call. The normal ending. | `Contacted` — read the transcript for the result |
| `agent_hangup` | The agent completed its job and ended the call | `Contacted` — usually the cleanest outcome |
| `idle` | Silence for long enough that the agent said goodbye | `Contacted, no engagement` — often a voicemail or a set-down handset |
| `max_duration` | The call hit its length cap | `Contacted, truncated` — worth a human review |

**Something went wrong on our side:**

| `outcome` | What happened | CRM disposition |
|---|---|---|
| `originate_error` | The call could not be placed | `Failed` — safe to retry |
| `setup_error` | The media path failed to establish | `Failed` — safe to retry |
| `suspended` | The workspace is billing-suspended | `Blocked` — alert an admin; every call will fail the same way |

::: note Handle the outcome you have not seen
`outcome` is a plain string with no closed enum on the API. New values can appear. Give your mapping a default branch that writes `Unknown` and logs the raw value rather than throwing — a `KeyError` in a webhook handler returns a 500, which costs you four retries and moves you closer to having the endpoint auto-disabled.
:::

A handler that puts it together:

::: codegroup

```javascript Node.js
const NEVER_CONNECTED = {
  no_answer: "No answer",
  busy: "Busy",
  rejected: "Rejected",
  invalid_number: "Bad number",
  unreachable: "Unreachable",
  congestion: "Retry",
};

const CONNECTED = {
  caller_hangup: "Contacted",
  agent_hangup: "Contacted",
  idle: "Contacted, no engagement",
  max_duration: "Contacted, truncated",
};

const PLATFORM_FAILURE = {
  originate_error: "Failed",
  setup_error: "Failed",
  suspended: "Blocked",
};

function disposition(call) {
  const outcome = call.outcome ?? "";
  if (outcome in PLATFORM_FAILURE) return PLATFORM_FAILURE[outcome];
  if (outcome in NEVER_CONNECTED) return NEVER_CONNECTED[outcome];
  if (outcome in CONNECTED) return CONNECTED[outcome];
  console.warn("unmapped call outcome", { outcome, call_id: call.call_id });
  return "Unknown";
}

async function onCallEnded(data) {
  const record = await crm.findByCallId(data.call_id);
  if (!record) return;

  await crm.update(record.id, {
    callState: "ended",
    disposition: disposition(data),
    callDurationSeconds: data.duration_seconds ?? 0,
    callEndedAt: new Date().toISOString(),
  });

  // Free a slot in your outbound worker pool here, not on the 201.
  await pool.release(data.call_id);
}
```

```python Python
NEVER_CONNECTED = {
    "no_answer": "No answer",
    "busy": "Busy",
    "rejected": "Rejected",
    "invalid_number": "Bad number",
    "unreachable": "Unreachable",
    "congestion": "Retry",
}

CONNECTED = {
    "caller_hangup": "Contacted",
    "agent_hangup": "Contacted",
    "idle": "Contacted, no engagement",
    "max_duration": "Contacted, truncated",
}

PLATFORM_FAILURE = {
    "originate_error": "Failed",
    "setup_error": "Failed",
    "suspended": "Blocked",
}


def disposition(call: dict) -> str:
    outcome = call.get("outcome") or ""
    for table in (PLATFORM_FAILURE, NEVER_CONNECTED, CONNECTED):
        if outcome in table:
            return table[outcome]
    logger.warning("unmapped call outcome", extra={"outcome": outcome, "call_id": call.get("call_id")})
    return "Unknown"


async def on_call_ended(data: dict) -> None:
    record = await crm.find_by_call_id(data["call_id"])
    if record is None:
        return

    await crm.update(
        record.id,
        call_state="ended",
        disposition=disposition(data),
        call_duration_seconds=data.get("duration_seconds") or 0,
    )

    # Free a slot in your outbound worker pool here, not on the 201.
    await pool.release(data["call_id"])
```

:::

## Reading what was said

`call.ended` gives you the outcome, not the content. For the content, read the conversation the call produced through [`GET /conversations/{id}/messages`](/api/conversations) — the transcript is stored as ordinary conversation turns.

Two things not to build on:

- **`summary` is not populated.** The field exists on `CallOut` and comes back `null`. Do not write a pipeline that expects prose in it.
- **`recording_uri` only exists if recording is enabled**, which is off by default and requires an explicit opt-in per number. When it is on, callers hear a spoken notice before the greeting. See [How voice works](/channels/voice).

## Cancelling a call in flight

If the CRM stage changes again while the phone is still ringing, hang up:

```bash
curl -X POST https://services.amomic.in/api/v1/calls/call_01JQRS4T8XZ0AB1CD2EF3GH4/hangup \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{ "call_id": "call_01JQRS4T8XZ0AB1CD2EF3GH4", "ended": true }
```

`ended: false` means the call was already over — it is not an error, and it is the answer you get if you race the customer hanging up. `call.ended` still fires either way.

## Going to production

- **Call yourself first.** Place a real call to your own mobile with the real `purpose` text and listen to the whole thing. Reading the brief is not the same as hearing the agent open with it.
- **Put the compliance check in the trigger**, not in a runbook. It is the one part of this flow the platform will not do for you.
- **Cap attempts per contact per day** in your own code and treat `rejected` as a stop signal.
- **Alert on `no_agent_deployed` and `workspace_suspended`** separately. Both mean every call will fail identically until a human acts.
- Watch the **Calls** page in the console during the first batch. It shows each call's outcome and duration as they finish.

## Next

::: cards

::: card The endpoint reference
[POST /calls](/api/calls) — every field, every guard, every error, plus hangup and read.
:::

::: card How voice actually works
[How voice works](/channels/voice) — what the agent hears, how turn-taking works, and what recording does.
:::

::: card Event payloads
[Event reference](/webhooks/events) — the exact `data` shape of `call.started` and `call.ended`.
:::

::: card Message them instead
[Send an order update on WhatsApp](/recipes/order-updates) — the same pattern for the messaging channel.
:::

:::


----------------------------------------------------------------------------
## Sync conversations into your warehouse
URL: https://docs.amomic.in/recipes/sync-conversations
----------------------------------------------------------------------------

Support volume is only useful next to everything else you measure. This page builds the job that gets it there: a scheduled process that pulls conversations and their transcripts into your own store, picks up where it left off, survives being run twice, and does not spend your whole rate-limit budget doing it.

The API gives you three read endpoints and a cursor. Everything hard about this job is in four decisions — what you persist between runs, when to stop walking, how fast to walk, and what you do about the events that arrive while you are not looking. This page makes all four explicit and then gives you the finished job.

## What you need before you start

- **An API key with `conversations:read`.** New keys have it by default, along with `agents:read`. See [Scopes](/api/scopes).
- **Somewhere durable to keep a watermark.** A row in a table, a key in Redis, a small JSON file next to the job. It must survive a deploy.
- **An upsert, not an insert.** Both conversations and messages carry stable ids. Every write in this job is keyed on one.
- **A schedule.** Every 5 to 15 minutes is normal. Read the pacing section below before you go faster.

## The shape of the job

1. Read the watermark you saved last time.
2. Walk `GET /conversations` from page one, newest activity first.
3. For every conversation whose `updated_at` is above the watermark, upsert it and walk its transcript.
4. Stop the moment you reach a conversation at or below the watermark, or when a short page ends the list.
5. Write the highest `updated_at` you processed back to the watermark — once, at the end.

Two nested loops. The outer one walks the conversation list newest-activity-first and stops as soon as it reaches something you already have. The inner one walks the transcript of every conversation the outer loop accepted. Around both sits a pacer, and above both sits the watermark.

## The cursor contract

Both paginated endpoints return the same envelope:

```json
{ "items": [ … ], "next_cursor": "…" }
```

One rule governs the loop, and getting it wrong is the most common bug in this integration:

::: warning A full page means maybe more. A short page means done.
`next_cursor` is non-null **only when the page came back with exactly `limit` items**. The server does not look ahead to check whether anything is actually left — a full page is a *maybe*, not a promise. Ask for 100, get 100, and there may be nothing at all behind it. Ask for 100 and get 63, and the walk is over.
:::

The practical consequences:

- **Loop on `next_cursor`, never on `items.length`.** A page of 100 followed by an empty page with `next_cursor: null` is normal and correct. Code that stops when it sees a full page is wrong in the other direction — it silently truncates.
- **Never construct or parse a cursor.** For conversations it happens to be an `updated_at` string; for messages it happens to be a `message_id`. Both are implementation details you should not be reading. Pass back what you were given, byte for byte.
- **There is no total, no `has_more`, no page number, and no way to go backwards.** If your UI needs a count, count what you stored.
- **An empty first page means the workspace has no conversations.** It does not mean an error. A bad `conversation_id` on the messages endpoint is a `404`, never an empty page — so an empty transcript genuinely means an empty transcript.

[Pagination](/api/pagination) is the full contract.

## What you persist between runs: a watermark, not a cursor

The instinct is to save `next_cursor` at the end of a run and resume from it next time. Do not. A cursor is a position inside one walk of a list that is reordering itself continuously — conversations come back ordered by `updated_at` descending, so every new message moves a conversation to the front and shifts everything behind it. A cursor from twenty minutes ago points at a place in a list that no longer exists.

What you persist is a **watermark**: the highest `updated_at` you have successfully processed. On the next run you walk from the top of the list again and stop the moment you reach a conversation at or below it.

This inverts the usual failure mode in a helpful direction. Consider a conversation that receives a new message *while* your walk is in progress:

1. It jumps to the front of the list — behind the cursor you already passed.
2. This run misses it.
3. Its `updated_at` is now later than anything this run observed, so it is above the watermark you save.
4. The next run sees it on page one.

The window is bounded by your schedule, not by luck. That is the whole reason to prefer a watermark.

::: tip Rewind the watermark a few minutes
Store the high watermark, but *compare* against it minus a small overlap — five minutes is a reasonable default. Reprocessing a handful of conversations costs one extra request each and every write in this job is an upsert, so the overlap is free. It buys you tolerance for clock skew, for a conversation whose `updated_at` lands a fraction behind another's, and for the run that died halfway through.
:::

On the very first run there is no watermark. That run is a full backfill: it walks until a short page ends it. Plan for it — the first run is covered in its own section below.

## Pacing against the rate limit

The limit is **120 requests per minute, per key**, counted in a fixed one-minute window rather than a sliding one. This job is request-hungry by construction: one request per page of conversations, plus at least one per conversation that changed.

A workspace with 400 conversations updated since the last run costs roughly 4 list requests plus 400 transcript requests. At full speed that is a guaranteed `429` and, worse, it starves whatever else that key is doing.

Three things to build in:

- **Pace deliberately.** Space requests so you land near 90 per minute rather than 120. The headroom is for the message you need to send while the sync is running.
- **Read `X-RateLimit-Remaining`.** It is set on every successful response, alongside `X-RateLimit-Limit`. When remaining drops into single digits, slow down before the server has to tell you.
- **Sleep to the window boundary on a 429.** There is no `Retry-After` header and no `X-RateLimit-Reset`. The window is a wall-clock minute, so sleeping until the next minute boundary is exactly right and anything shorter is a wasted request.

::: note Give the sync its own key
A key named `Warehouse sync` with only `conversations:read` is better than reusing your `Order service` key. It gets its own 120-request budget, its own line in the request log, and it can be revoked without taking your order notifications down. This is the single highest-value thing on this page. See [Rate limits](/api/rate-limits).
:::

## The complete job

Both versions below are runnable. The only things left as stubs are the four functions that talk to your own store: `load_state`, `save_state`, `upsert_conversation`, `upsert_messages`.

::: codegroup

```python Python
# sync_conversations.py
import json
import os
import time
from datetime import datetime, timedelta

import httpx

BASE_URL = "https://services.amomic.in/api/v1"
API_KEY = os.environ["AMOMIC_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 120 requests/minute is the ceiling. Aim at 90 and keep the rest for
# whatever else this key does while the sync is running.
MIN_INTERVAL_S = 60 / 90
OVERLAP = timedelta(minutes=5)
MAX_ATTEMPTS = 5
BACKOFF_S = [1, 4, 12, 30]


class SyncError(Exception):
    """A non-retryable API error. The envelope is attached for logging."""

    def __init__(self, status: int, error: dict):
        super().__init__(f"{error['code']}: {error['message']}")
        self.status = status
        self.code = error["code"]
        self.details = error.get("details") or {}
        self.reason = self.details.get("reason")
        self.request_id = error.get("request_id")


class Pacer:
    """Spaces requests, and slows down when the server says headroom is low."""

    def __init__(self) -> None:
        self._next_at = 0.0

    def wait(self) -> None:
        delay = self._next_at - time.monotonic()
        if delay > 0:
            time.sleep(delay)

    def observe(self, response: httpx.Response) -> None:
        interval = MIN_INTERVAL_S
        remaining = response.headers.get("X-RateLimit-Remaining")
        # The headers are present on success only; absent on any error.
        if remaining is not None and remaining.isdigit() and int(remaining) < 20:
            interval = 1.5
        self._next_at = time.monotonic() + interval


def _sleep_to_minute_boundary() -> None:
    # Fixed one-minute window: the counter resets on the wall-clock minute.
    time.sleep(60 - (time.time() % 60) + 0.25)


def get(client: httpx.Client, path: str, params: dict, pacer: Pacer) -> dict:
    for attempt in range(MAX_ATTEMPTS):
        pacer.wait()
        try:
            response = client.get(f"{BASE_URL}{path}", headers=HEADERS, params=params)
        except httpx.RequestError:
            if attempt == MAX_ATTEMPTS - 1:
                raise
            time.sleep(BACKOFF_S[min(attempt, len(BACKOFF_S) - 1)])
            continue

        if response.is_success:
            pacer.observe(response)
            return response.json()

        if response.status_code == 429:
            _sleep_to_minute_boundary()
            continue

        if response.status_code >= 500:
            if attempt == MAX_ATTEMPTS - 1:
                raise SyncError(response.status_code, response.json()["error"])
            time.sleep(BACKOFF_S[min(attempt, len(BACKOFF_S) - 1)])
            continue

        # 400, 401, 403, 404, 412 — retrying cannot change the answer.
        raise SyncError(response.status_code, response.json()["error"])

    raise RuntimeError(f"GET {path} gave up after {MAX_ATTEMPTS} attempts")


def parse_ts(value: str | None) -> datetime | None:
    """Timestamps are ISO 8601 with an offset, e.g. 2026-08-01T10:02:55.118307+00:00."""
    if not value:
        return None
    try:
        return datetime.fromisoformat(value)
    except ValueError:
        return None


def sync_transcript(client: httpx.Client, conversation_id: str, pacer: Pacer) -> None:
    cursor: str | None = None
    while True:
        params: dict = {"limit": 200}
        if cursor:
            params["cursor"] = cursor

        page = get(client, f"/conversations/{conversation_id}/messages", params, pacer)
        # Upsert on message_id. A conversation you synced yesterday can gain
        # turns today, and you will read the old ones again.
        upsert_messages(conversation_id, page["items"])

        if not page["next_cursor"]:
            return                      # short page — the transcript is complete
        cursor = page["next_cursor"]


def sync() -> None:
    state = load_state()
    watermark = parse_ts(state.get("watermark"))
    floor = watermark - OVERLAP if watermark else None
    high = watermark

    pacer = Pacer()
    cursor: str | None = None
    done = False

    with httpx.Client(timeout=30.0) as client:
        while not done:
            params: dict = {"limit": 100}
            if cursor:
                params["cursor"] = cursor

            page = get(client, "/conversations", params, pacer)

            for conversation in page["items"]:
                updated = parse_ts(conversation.get("updated_at"))

                # Ordered by updated_at DESC: the first old row ends the walk.
                if floor and updated and updated <= floor:
                    done = True
                    break

                upsert_conversation(conversation)
                sync_transcript(client, conversation["conversation_id"], pacer)

                if updated and (high is None or updated > high):
                    high = updated

            if done or not page["next_cursor"]:
                break                   # short page — no more conversations
            cursor = page["next_cursor"]

    # Only advance the watermark after the whole run succeeded. A crash
    # mid-walk leaves the old watermark in place and the next run redoes it.
    if high:
        save_state({"watermark": high.isoformat()})


# ---- your side ------------------------------------------------------------

def load_state() -> dict:
    try:
        with open("sync_state.json") as handle:
            return json.load(handle)
    except FileNotFoundError:
        return {}


def save_state(state: dict) -> None:
    with open("sync_state.json", "w") as handle:
        json.dump(state, handle)


def upsert_conversation(conversation: dict) -> None:
    ...   # keyed on conversation_id


def upsert_messages(conversation_id: str, messages: list[dict]) -> None:
    ...   # keyed on message_id


if __name__ == "__main__":
    sync()
```

```javascript Node.js
// sync-conversations.js
import { readFile, writeFile } from "node:fs/promises";

const BASE_URL = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };

// 120 requests/minute is the ceiling. Aim at 90 and keep the rest for
// whatever else this key does while the sync is running.
const MIN_INTERVAL_MS = 60_000 / 90;
const OVERLAP_MS = 5 * 60_000;
const MAX_ATTEMPTS = 5;
const BACKOFF_MS = [1_000, 4_000, 12_000, 30_000];

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

class SyncError extends Error {
  constructor(status, error) {
    super(`${error.code}: ${error.message}`);
    this.status = status;
    this.code = error.code;
    this.details = error.details ?? {};
    this.reason = error.details?.reason ?? null;
    this.requestId = error.request_id;
  }
}

class Pacer {
  #nextAt = 0;

  async wait() {
    const delay = this.#nextAt - Date.now();
    if (delay > 0) await sleep(delay);
  }

  observe(response) {
    // Rate-limit headers appear on success only, never on an error.
    const remaining = Number(response.headers.get("X-RateLimit-Remaining"));
    const interval = Number.isFinite(remaining) && remaining < 20 ? 1_500 : MIN_INTERVAL_MS;
    this.#nextAt = Date.now() + interval;
  }
}

// Fixed one-minute window: the counter resets on the wall-clock minute.
const sleepToMinuteBoundary = () => sleep(60_000 - (Date.now() % 60_000) + 250);

async function get(path, params, pacer) {
  const query = new URLSearchParams(params);

  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
    await pacer.wait();

    let response;
    try {
      response = await fetch(`${BASE_URL}${path}?${query}`, { headers: HEADERS });
    } catch (networkError) {
      if (attempt === MAX_ATTEMPTS - 1) throw networkError;
      await sleep(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
      continue;
    }

    if (response.ok) {
      pacer.observe(response);
      return response.json();
    }

    if (response.status === 429) {
      await sleepToMinuteBoundary();
      continue;
    }

    const { error } = await response.json();

    if (response.status >= 500) {
      if (attempt === MAX_ATTEMPTS - 1) throw new SyncError(response.status, error);
      await sleep(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
      continue;
    }

    // 400, 401, 403, 404, 412 — retrying cannot change the answer.
    throw new SyncError(response.status, error);
  }

  throw new Error(`GET ${path} gave up after ${MAX_ATTEMPTS} attempts`);
}

// Timestamps are ISO 8601 with an offset, e.g. 2026-08-01T10:02:55.118307+00:00.
// Date.parse drops sub-millisecond precision, which is fine for ordering.
const parseTs = (value) => {
  const ms = value ? Date.parse(value) : NaN;
  return Number.isFinite(ms) ? ms : null;
};

async function syncTranscript(conversationId, pacer) {
  let cursor = null;

  for (;;) {
    const params = { limit: "200" };
    if (cursor) params.cursor = cursor;

    const page = await get(`/conversations/${conversationId}/messages`, params, pacer);
    // Upsert on message_id. A conversation you synced yesterday can gain
    // turns today, and you will read the old ones again.
    await upsertMessages(conversationId, page.items);

    if (!page.next_cursor) return;      // short page — the transcript is complete
    cursor = page.next_cursor;
  }
}

export async function sync() {
  const state = await loadState();
  const watermark = parseTs(state.watermark);
  const floor = watermark === null ? null : watermark - OVERLAP_MS;
  let high = watermark;

  const pacer = new Pacer();
  let cursor = null;
  let done = false;

  while (!done) {
    const params = { limit: "100" };
    if (cursor) params.cursor = cursor;

    const page = await get("/conversations", params, pacer);

    for (const conversation of page.items) {
      const updated = parseTs(conversation.updated_at);

      // Ordered by updated_at DESC: the first old row ends the walk.
      if (floor !== null && updated !== null && updated <= floor) {
        done = true;
        break;
      }

      await upsertConversation(conversation);
      await syncTranscript(conversation.conversation_id, pacer);

      if (updated !== null && (high === null || updated > high)) high = updated;
    }

    if (done || !page.next_cursor) break;   // short page — no more conversations
    cursor = page.next_cursor;
  }

  // Only advance the watermark after the whole run succeeded. A crash
  // mid-walk leaves the old watermark in place and the next run redoes it.
  if (high !== null) {
    await saveState({ watermark: new Date(high).toISOString() });
  }
}

// ---- your side ------------------------------------------------------------

async function loadState() {
  try {
    return JSON.parse(await readFile("sync-state.json", "utf8"));
  } catch {
    return {};
  }
}

const saveState = (state) => writeFile("sync-state.json", JSON.stringify(state));
const upsertConversation = async (conversation) => {};  // keyed on conversation_id
const upsertMessages = async (conversationId, messages) => {};  // keyed on message_id

await sync();
```

:::

### Why the watermark is written last

Notice that `save_state` runs once, after both loops finish. If the job dies on page four, the watermark is unchanged and the next run repeats pages one to four. Every write is an upsert, so the repeat is invisible in your data.

The alternative — advancing the watermark page by page — looks more efficient and loses data. A crash after the watermark is written but before the transcripts are stored leaves a permanent hole that no future run will revisit, because the conversations are now below the watermark.

Slow and repeatable beats fast and holed. This job is not the expensive part of your pipeline.

### Why the transcript is re-read in full

`updated_at` moved because something was said, but the API does not tell you *what*. There is no "messages since" filter — the messages cursor is a position, not a timestamp. So the job re-walks the transcript and upserts everything.

For a 12-turn conversation that is one request. For a 900-turn conversation it is five, at `limit=200`. If you have conversations long enough for that to matter, remember the last `message_id` you stored per conversation and stop the transcript walk once you reach it — the ids are time-ordered, so the check is a comparison rather than a lookup.

## The first run is different

The first run has no watermark, so it walks until a short page ends it. On a workspace with 20,000 conversations that is 200 list requests and up to 20,000 transcript requests — well over an hour at a safe pace, and enough to occupy your entire rate limit for the duration.

Treat the backfill as its own operation:

- Run it with **its own API key** so it cannot interfere with production traffic.
- Run it **once, deliberately**, not as the first tick of your five-minute schedule. A backfill that gets killed by a scheduler timeout and restarted from scratch every five minutes will never finish.
- Consider seeding the watermark by hand if you only care about recent history. Write a timestamp into your state store before the first run and the job will treat everything older as already synced.
- Expect `429`s and let the pacer absorb them. They are not errors in this job; they are the shape of a backfill.

## Webhooks and reconciliation: use both

Neither mechanism is sufficient alone, and the reasons are different enough that combining them is not belt-and-braces — it is the design.

**Polling alone is late.** Your schedule is your latency. A five-minute sync means a conversation that ended thirty seconds ago is not in your store yet, which is fine for analytics and useless for anything that needs to react — routing, alerting, a live dashboard.

**Webhooks alone lose things.** Delivery is at-least-once, which is a promise about duplicates, not about completeness. An endpoint that returns a non-429 4xx is never retried. An endpoint that is down long enough burns four attempts per event over roughly a minute and then moves on. After **15 consecutive failed events** the endpoint is disabled automatically and receives nothing until an admin re-enables it — and there is no replay endpoint, so everything that fired during the outage is gone from your side.

The production shape:

| Job | Mechanism | Why |
|---|---|---|
| React to a new conversation now | `conversation.started` webhook | Sub-second. Carries `conversation_id` and `customer`. |
| React to a conversation ending | `conversation.ended` webhook | Same projection as `started`. |
| React to an inbound message | `message.received` webhook | Carries the text and the `conversation_id`. |
| Guarantee your store is complete | This sync job | Fills every gap the webhooks left, whatever the cause. |
| Guarantee your store is *correct* | This sync job | It re-reads the transcript from the source of truth. |

Two implementation notes where they meet:

- **A webhook is a trigger, not a record.** `conversation.started` fires when the conversation begins, so its transcript is empty or nearly so. Treat it as "this exists, and it is worth reading soon", not as data to store as-is.
- **Deduplicate on the envelope `id`.** The `evt_…` id at the top level of the webhook body is stable across redeliveries of the same event. This is separate from `data.event_id`, which is an internal identifier. Key your dedupe table on the top-level `id` or the `Amomic-Event-Id` header.

::: tip Let the webhook nudge the sync
The tidiest production version does not poll on a fixed timer at all. The webhook handler pushes a `conversation_id` onto a queue; a worker drains the queue and pulls that one conversation; a slower scheduled run of this full job — hourly, or nightly — catches anything the queue never heard about. You get webhook latency with sync completeness, and the reconciliation run stays small enough to be boring.
:::

[Getting events](/webhooks/overview) covers subscribing, and [Retries and failures](/webhooks/reliability) covers the ladder and the auto-disable in full.

## Failures you will actually hit

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Request validation failed — almost always a `limit` outside 1–100 (conversations) or 1–200 (messages). `details.errors` names the parameter."},
  {"status": 401, "code": "unauthenticated", "reason": "wrong_environment", "description": "A test key against the production host, or the reverse. The secret is fine; the host is not."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `conversations:read`. Widen it in the console; the running job will pick the change up within seconds."},
  {"status": 404, "code": "not_found", "reason": "", "description": "`Conversation not found.` — the id does not exist or belongs to another workspace. In this job it means your stored id is stale; skip it and move on."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_resource", "description": "Conversations are not available on this deployment. Configuration, not a blip — do not retry, and do not let the job spin."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests in one minute on this key. Sleep to the next minute boundary and continue. There is no Retry-After header."}
]
```

The branch that matters most is the one the sample code makes: **retry `429`, network errors, and 5xx; do not retry any other 4xx.** A job that retries a `403` will hammer the API until someone notices, and it will not have synced anything.

Log `error.request_id` on every failure. Every call your key made is in the request log under **Developers → Logs** for 7 days, and the request id turns a support conversation into a lookup.

## What is not in the synced data

Worth knowing before someone asks your warehouse a question it cannot answer:

- **Only `user` and `model` turns.** The internal operational trail your staff see in the inbox is filtered out of the public transcript, and `message_count` excludes it too. Your row counts will match `message_count`; they will not match what a colleague counts in the console.
- **No message `metadata`, no knowledge sources.** You get `message_id`, `role`, `text`, `created_at`. Nothing about which document produced an answer.
- **`customer` is as good as the channel it came from.** WhatsApp gives you a platform identity, web chat gives you whatever the lead form collected, voice gives you the caller's number. An empty `customer` object is an ordinary case, not an error.
- **No internal routing fields.** Correlate through `customer`, or capture the correlation at the moment the conversation starts via the `conversation.started` webhook.
- **Two timestamp shapes exist.** REST resources use ISO 8601 with an offset and microseconds (`2026-08-01T10:02:55.118307+00:00`). The webhook envelope's `created_at` uses second precision with a literal `Z` (`2026-08-01T10:02:55Z`). If you store both, normalise on the way in.

## Operating it

- **Alert on consecutive failed runs, not on a single one.** One `429` storm or one 502 is noise. Three runs in a row that stored nothing is an incident.
- **Emit the watermark as a metric.** Watermark age is the one number that tells you the pipeline is healthy: if it stops advancing, the job is failing regardless of whether it is throwing.
- **Watch the request log after a deploy.** **Developers → Logs** shows every call this key made with its status, error code, and duration — the fastest way to see that your new pacing is doing what you think.
- **Send `X-Correlation-Id`.** Any value you like, echoed back on the response and recorded on our side, so a support thread can join your trace to ours.

## Next

::: cards

::: card The endpoint reference
[Conversations](/api/conversations) — every field, every bound, and the exact shape of the transcript.
:::

::: card Pagination in detail
[The cursor contract](/api/pagination) — when `next_cursor` is set, and why a short page ends the walk.
:::

::: card Getting events
[Webhooks](/webhooks/overview) — subscribing, verifying, and the nine event types.
:::

::: card Rate limits
[120 per key per minute](/api/rate-limits) — the window, the headers, and how to pace a backfill.
:::

:::


----------------------------------------------------------------------------
## Escalate a conversation to a ticket
URL: https://docs.amomic.in/recipes/support-escalation
----------------------------------------------------------------------------

Some conversations end with a person. A refund outside policy, a document that will not validate, an angry customer who has asked twice — these need a human, and the moment they do you want a ticket with a reference number the customer can quote.

This page builds that path: your system decides a human is needed, opens a ticket with the context already attached, hands the customer a reference, and keeps its own record in step as your team works it.

## When you use this, and when you do not

Your agent already escalates on its own. When a customer asks for a human, or the agent hits something it cannot resolve, a ticket is opened without your involvement. You do not need to build that.

Build this when **your** system is the one that knows:

- A payment was captured and no order exists. Your reconciliation job found it; no conversation happened at all.
- A fulfilment exception your agent cannot see — a courier returned a parcel, a warehouse flagged a mismatch.
- A rule that lives in your code: third failed delivery attempt, second refund request this month, an account flagged for review.
- Your own product's "contact support" form, which you would rather land in the same queue than in a shared mailbox.

The common thread is that the trigger is in your system, not in the conversation.

::: note One scope covers create and read
Creating a ticket and reading one back both need `tickets:write`. There is no `tickets:read` scope. If your escalation flow also pulls conversation context, the same key needs `conversations:read` as well. See [Scopes](/api/scopes).
:::

## The requester is not optional

A ticket with no requester is a ticket nobody can answer, so the route refuses one:

```json title="400 Bad Request"
{
  "error": {
    "code": "invalid_argument",
    "message": "Provide at least one requester detail (name, email, or phone).",
    "details": {},
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Any one of `requester_name`, `requester_email`, `requester_phone` satisfies it. Note the empty `details` — this error carries no `reason`, so branch on `error.code` and the message rather than looking for a reason string.

| Field | Limit | What it does for the person working the ticket |
|---|---|---|
| `requester_name` | 120 characters | Tells them who this is. Without it the queue reads as a list of addresses. |
| `requester_email` | 200 characters | The reply path most teams reach for first. |
| `requester_phone` | 32 characters | The reply path that works when the conversation started on WhatsApp or a call. |

Send everything you have. The hard case is when you have nothing — a web-chat visitor who never filled in a lead form has an empty `customer` object on the conversation, and building `requester_email` from it gives you `null`.

::: warning Do not let an anonymous customer 400 your escalation
Check before you post. If every requester field would be null, synthesise a name from what you *do* know — `"Web visitor · con_01JQRS4T8XZ0AB1CD2EF3GH4"` is a legitimate `requester_name` and it is infinitely more useful to your team than a failed API call. The sample code below does exactly this.
:::

## Choosing a priority

`priority` is not decoration. `sla_due_at` is computed from it when the ticket is created:

| `priority` | `sla_due_at` | Use it when |
|---|---|---|
| `urgent` | 2 hours after creation | The customer is blocked *and* money or safety is involved. A captured payment with no order. A live outage affecting one named customer. Abuse or a threat. |
| `high` | 8 hours after creation | Blocked with no workaround, or a hard deadline today. A failed KYC that stops onboarding. A delivery that must move before the courier cut-off. |
| `normal` | 24 hours after creation | The default. The customer wants an answer, not a rescue. Most escalations belong here and putting them here is not a failure of care. |
| `low` | 72 hours after creation | No one is waiting. Feedback, a question about a future purchase, a duplicate of something already in flight. |

Two properties to design around.

**The clock is set once, at creation.** Changing priority later in the console does not recompute `sla_due_at`. Pass the right value from your system — you know how bad the failure is at the moment you detect it, and nobody will fix it up afterwards.

**Escalating everything to `urgent` deletes the signal.** A queue where every ticket is due in two hours is a queue with no ordering. Map priority from a rule in your code — amount at risk, customer tier, how many times this has already happened — rather than from how the exception felt to the developer who wrote the handler.

Send only the four values. Anything else fails validation with a `400` and `details.errors` naming the field.

## Tags

Up to **10** tags, each one a filter in your team's queue. Route by them: `billing`, `kyc`, `courier`, `refund`.

The server appends `api` to whatever you send:

```json title="you send"
{ "tags": ["refund", "escalated"] }
```

```json title="the ticket carries"
{ "tags": ["refund", "escalated", "api"] }
```

That tag is how your team separates machine-created tickets from ones a person or an agent opened — which matters the first time your integration misfires and files forty tickets at 2 a.m. It occupies a slot on the ticket, so plan for eleven where you sent ten.

## The dedupe that saves you

This is the part worth reading twice, because a retried escalation opening two tickets is a real incident: two people work the same problem, the customer gets two references, and your queue metrics lie.

`POST /tickets` deduplicates through **two independent mechanisms**.

### With an `Idempotency-Key` header

Standard behaviour. The stored `201` is replayed for 24 hours, and the key is scoped to your workspace, that specific API key, and this endpoint — so `escalate-con_01JQ…` on `/tickets` cannot collide with the same string on `/messages`. Reusing the key with a *different* body is a `409` with `details.reason` of `idempotency_key_reuse`.

### Without one

Tickets still deduplicate, on a **SHA-256 hash of the raw request body**. An identical body sent twice converges on the same ticket rather than opening a second one. The ticket id is derived from that hash, which is why `tkt_…` is a hash rather than a time-ordered id like every other identifier in this API.

This is a genuine safety net and it is why a naive retry loop against this endpoint is usually harmless. But it is a hash of *bytes*:

```javascript
// Retried three times by your job runner after a timeout.
// Byte-identical body each time → ONE ticket, returned three times.
await createTicket(payload);

// Same incident, but the description is rebuilt with a timestamp inside it.
// Different bytes → THREE tickets.
await createTicket({ ...payload, description: `${detail} (checked ${new Date()})` });
```

Anything that varies between attempts breaks it: a timestamp in the description, a trace id in the subject, a dictionary that serialises with a different key order, a transcript excerpt that gained a turn between attempt one and attempt two. That last one is the trap specific to this recipe — the context you attach is live data, and live data changes.

::: tip Send the header anyway, and derive it from your own record
The body hash protects you from a *byte-identical* retry. The header protects you from everything, because it lets **you** declare what "the same escalation" means. `escalate-con_01JQRS4T8XZ0AB1CD2EF3GH4` says: this conversation needs a human, once, however many times this handler runs. If a single conversation can legitimately escalate twice for two different reasons, put your own incident id in the key instead — `escalate-inc-99231`. Never `Date.now()`.
:::

One boundary: idempotency records live for **24 hours**. The same key 25 hours later opens a fresh ticket, which is correct for a retry queue and wrong for a job replayed from an archive. Check your own "already escalated" flag before calling. See [Idempotency](/api/idempotency).

## The complete escalation

This handler takes a `conversation_id` and a reason, pulls enough context that your team does not have to go looking, and opens the ticket. Both versions are runnable.

::: codegroup

```python Python
# escalate.py
import os
import httpx

BASE_URL = "https://services.amomic.in/api/v1"
API_KEY = os.environ["AMOMIC_API_KEY"]        # needs tickets:write + conversations:read
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

DESCRIPTION_LIMIT = 8000                       # hard API limit
SUBJECT_LIMIT = 240                            # hard API limit


class AmomicError(Exception):
    def __init__(self, status: int, error: dict):
        super().__init__(f"{error['code']}: {error['message']}")
        self.status = status
        self.code = error["code"]
        self.details = error.get("details") or {}
        self.reason = self.details.get("reason")
        self.request_id = error.get("request_id")


def _raise_for_error(response: httpx.Response) -> dict:
    if response.is_success:
        return response.json()
    raise AmomicError(response.status_code, response.json()["error"])


def _requester(conversation: dict) -> dict:
    """At least one of name/email/phone must be present, so never return all-null."""
    customer = conversation.get("customer") or {}
    name = customer.get("name") or customer.get("display_name")
    email = customer.get("email")
    phone = customer.get("phone")

    if not (name or email or phone):
        # An anonymous web visitor. A synthesised name beats a 400.
        name = f"Customer · {conversation['conversation_id']}"

    return {
        "requester_name": (name or None) and name[:120],
        "requester_email": (email or None) and email[:200],
        "requester_phone": (phone or None) and phone[:32],
    }


def _recent_turns(client: httpx.Client, conversation_id: str, turns: int = 12) -> str:
    """Last few turns of the transcript, oldest first. Roles are user and model."""
    page = _raise_for_error(
        client.get(
            f"{BASE_URL}/conversations/{conversation_id}/messages",
            headers=HEADERS,
            params={"limit": 200},
        )
    )
    lines = [
        f"{'Customer' if m.get('role') == 'user' else 'Agent'}: {m.get('text') or ''}"
        for m in page["items"][-turns:]
    ]
    return "\n".join(lines)


def escalate(conversation_id: str, reason: str, priority: str = "normal", tags=()) -> dict:
    with httpx.Client(timeout=30.0) as client:
        conversation = _raise_for_error(
            client.get(f"{BASE_URL}/conversations/{conversation_id}", headers=HEADERS)
        )

        transcript = _recent_turns(client, conversation_id)
        description = (
            f"{reason}\n\n"
            f"Channel: {conversation.get('channel')}\n"
            f"Conversation: {conversation_id}\n"
            f"Turns so far: {conversation.get('message_count', 0)}\n\n"
            f"--- recent transcript ---\n{transcript}"
        )[:DESCRIPTION_LIMIT]

        body = {
            "subject": f"Escalated: {reason}"[:SUBJECT_LIMIT],
            "description": description,
            "priority": priority,
            "tags": list(tags)[:10],
            **_requester(conversation),
        }

        response = client.post(
            f"{BASE_URL}/tickets",
            headers={
                **HEADERS,
                "Content-Type": "application/json",
                # One escalation per conversation. Not a timestamp, not a UUID.
                "Idempotency-Key": f"escalate-{conversation_id}",
            },
            json=body,
        )
        ticket = _raise_for_error(response)

    # public_ref is what you quote to the customer; ticket_id is your handle.
    record_escalation(conversation_id, ticket["ticket_id"], ticket["public_ref"])
    return ticket
```

```javascript Node.js
// escalate.js
const BASE_URL = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };
// The key needs tickets:write and conversations:read.

const DESCRIPTION_LIMIT = 8000;   // hard API limit
const SUBJECT_LIMIT = 240;        // hard API limit

class AmomicError extends Error {
  constructor(status, error) {
    super(`${error.code}: ${error.message}`);
    this.status = status;
    this.code = error.code;
    this.details = error.details ?? {};
    this.reason = error.details?.reason ?? null;
    this.requestId = error.request_id;
  }
}

async function json(response) {
  const payload = await response.json();
  if (!response.ok) throw new AmomicError(response.status, payload.error);
  return payload;
}

// At least one of name/email/phone must be present, so never return all-null.
function requesterFrom(conversation) {
  const customer = conversation.customer ?? {};
  let name = customer.name ?? customer.display_name ?? null;
  const email = customer.email ?? null;
  const phone = customer.phone ?? null;

  if (!name && !email && !phone) {
    // An anonymous web visitor. A synthesised name beats a 400.
    name = `Customer · ${conversation.conversation_id}`;
  }

  return {
    requester_name: name ? name.slice(0, 120) : null,
    requester_email: email ? email.slice(0, 200) : null,
    requester_phone: phone ? phone.slice(0, 32) : null,
  };
}

// Last few turns of the transcript, oldest first. Roles are user and model.
async function recentTurns(conversationId, turns = 12) {
  const page = await json(
    await fetch(`${BASE_URL}/conversations/${conversationId}/messages?limit=200`, {
      headers: HEADERS,
    }),
  );
  return page.items
    .slice(-turns)
    .map((m) => `${m.role === "user" ? "Customer" : "Agent"}: ${m.text ?? ""}`)
    .join("\n");
}

export async function escalate(conversationId, reason, { priority = "normal", tags = [] } = {}) {
  const conversation = await json(
    await fetch(`${BASE_URL}/conversations/${conversationId}`, { headers: HEADERS }),
  );

  const transcript = await recentTurns(conversationId);
  const description = [
    reason,
    "",
    `Channel: ${conversation.channel}`,
    `Conversation: ${conversationId}`,
    `Turns so far: ${conversation.message_count ?? 0}`,
    "",
    "--- recent transcript ---",
    transcript,
  ]
    .join("\n")
    .slice(0, DESCRIPTION_LIMIT);

  const ticket = await json(
    await fetch(`${BASE_URL}/tickets`, {
      method: "POST",
      headers: {
        ...HEADERS,
        "Content-Type": "application/json",
        // One escalation per conversation. Not a timestamp, not a UUID.
        "Idempotency-Key": `escalate-${conversationId}`,
      },
      body: JSON.stringify({
        subject: `Escalated: ${reason}`.slice(0, SUBJECT_LIMIT),
        description,
        priority,
        tags: tags.slice(0, 10),
        ...requesterFrom(conversation),
      }),
    }),
  );

  // public_ref is what you quote to the customer; ticket_id is your handle.
  await recordEscalation(conversationId, ticket.ticket_id, ticket.public_ref);
  return ticket;
}
```

```bash cURL
curl -X POST https://services.amomic.in/api/v1/tickets \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: escalate-con_01JQRS4T8XZ0AB1CD2EF3GH4" \
  -d '{
    "subject": "Escalated: refund requested outside the 30-day window",
    "description": "Customer asked for a refund on AM-4821, delivered 41 days ago. Policy is 30 days, so the agent could not approve it. Customer says the item was faulty on arrival and they were travelling.\n\nChannel: whatsapp\nConversation: con_01JQRS4T8XZ0AB1CD2EF3GH4\nOrder: AM-4821\nAmount: ₹4,299",
    "priority": "high",
    "requester_name": "Asha Menon",
    "requester_email": "asha.menon@example.in",
    "requester_phone": "+919876543210",
    "tags": ["refund", "policy-exception"]
  }'
```

:::

Three details in that code doing real work:

- **Every string is truncated to the API limit before it is sent.** `subject` over 240 or `description` over 8000 is a `400`, and a transcript excerpt is exactly the kind of field that grows past a limit in production but not in your tests.
- **`_requester` never returns three nulls.** The `400` it prevents would otherwise fire only for anonymous visitors, which is to say rarely, at night, in the branch you did not test.
- **The idempotency key names the conversation, not the moment.** A job runner that retries this handler four times files one ticket.

::: note There is no `conversation_id` field on a ticket
The API has no field that formally links a ticket to a conversation, so the link lives in the text — put `conversation_id` in the description, as the sample does, and store the pairing on your side. Your team can then find the thread in the inbox, and your own systems can join the two records.
:::

## What comes back

```json title="201 Created"
{
  "ticket_id": "tkt_4f9b21c7de03a85610bb47e2",
  "public_ref": "AM-20AB7B43",
  "subject": "Escalated: refund requested outside the 30-day window",
  "status": "new",
  "priority": "high",
  "tags": ["refund", "policy-exception", "api"],
  "requester": {
    "name": "Asha Menon",
    "email": "asha.menon@example.in",
    "phone": "+919876543210"
  },
  "sla_due_at": "2026-08-01T18:47:03.551204+00:00",
  "created_at": "2026-08-01T10:47:03.551204+00:00",
  "updated_at": "2026-08-01T10:47:03.551204+00:00"
}
```

Two identifiers, two audiences. **`public_ref`** (`AM-20AB7B43`) is the human handle — eight uppercase hex characters, short enough to read out over the phone. Put it in your confirmation message, your status page, and your own UI. **`ticket_id`** (`tkt_…`) is the machine handle and the argument to `GET /tickets/{ticket_id}`. Store both.

::: warning Read only the documented fields
The response is the ticket record, and that record carries more than the fields above — assignment, escalation bookkeeping, internal versioning. Those are not part of the API surface and can change shape or disappear without notice. Read the fields in [the endpoint reference](/api/tickets) and ignore the rest. Do not write a schema validator that rejects unknown keys.
:::

## Telling the customer

The escalation is only useful to the customer if they hear about it. If the conversation is on WhatsApp and they messaged you recently, the 24-hour window is open and you can send free-form text straight back into the thread:

```bash
curl -X POST https://services.amomic.in/api/v1/messages \
  -H "Authorization: Bearer $AMOMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: escalate-notice-con_01JQRS4T8XZ0AB1CD2EF3GH4" \
  -d '{
    "to": "+919876543210",
    "text": "I have passed this to our team as AM-20AB7B43. Someone will come back to you today — you can quote that reference any time."
  }'
```

If the window has closed, free-form text returns a `409` with `session_window_closed` and you need an approved template instead. [The 24-hour window](/channels/whatsapp-window) explains the rule; [Templates](/channels/whatsapp-templates) covers getting one approved.

## Reading the ticket back

```endpoint
GET /api/v1/tickets/{ticket_id}
```

Scope `tickets:write` — the same one that created it. No query parameters. Returns the same object with the current `status`, `priority`, `tags`, and `updated_at`.

```bash
curl https://services.amomic.in/api/v1/tickets/tkt_4f9b21c7de03a85610bb47e2 \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

The thread — staff replies, customer messages, internal notes — is **not** included. This returns the ticket record only; the conversation on the ticket lives in the console.

An unknown id, or one belonging to another workspace, returns `404 not_found` with `Ticket not found.` The two cases are deliberately indistinguishable.

There is no list endpoint, no update endpoint, and no way to add a comment or change status over the API. Once a ticket exists it belongs to your team.

## Syncing status into your own helpdesk

Do not poll `GET /tickets/{ticket_id}` on a timer. Subscribe to `ticket.created` and `ticket.updated` and let the status come to you.

```json title="POST to your endpoint"
{
  "id": "evt_9f2c4b1e7a3d5c8f0b2e6d41",
  "type": "ticket.updated",
  "created_at": "2026-08-01T13:22:41Z",
  "tenant_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "data": {
    "ticket_id": "tkt_4f9b21c7de03a85610bb47e2",
    "public_ref": "AM-20AB7B43",
    "subject": "Escalated: refund requested outside the 30-day window",
    "status": "resolved",
    "priority": "high",
    "channel": "api",
    "event_id": "evt_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Both events carry the same six fields plus `event_id`. That is usually the entire payload a status sync needs — the id to join on, the reference to display, and the state to mirror.

Four rules for the handler:

- **Verify the signature against the raw request bytes.** Parsing and re-serialising changes the bytes and the HMAC will not match. This is the most common webhook bug there is. [Verifying signatures](/webhooks/signatures) has the code.
- **Deduplicate on the envelope `id`.** Delivery is at-least-once; the same `evt_…` can arrive more than once. The top-level `id` is the dedupe key, not `data.event_id`.
- **Fields with a null value are omitted entirely** rather than sent as `null`. Read defensively — `data.priority` may not be there at all.
- **Return 2xx fast, then work.** The delivery times out at 10 seconds. A non-429 4xx stops retries immediately; 5xx, 429, and timeouts get four attempts over roughly a minute; 15 consecutive failed events disable the endpoint until an admin re-enables it.

::: warning The sync is one-way
`ticket.updated` pushes our state to you. There is no endpoint that pushes your state back — no update, no comment, no status change over the API. If your helpdesk is the system of record, treat these tickets as a feed to mirror, and do the work in the console rather than expecting a write path that does not exist.
:::

Also expect a `ping` event. The console's "test endpoint" button sends `{"id": "evt_test", "type": "ping", …}`, which is not one of the nine subscribable event types. A `default` branch that ignores unknown types handles it, and handles every future event type as well. See [Event reference](/webhooks/events).

## Failures

```responses
[
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "`Provide at least one requester detail (name, email, or phone).` — all three requester fields were null."},
  {"status": 400, "code": "invalid_argument", "reason": "", "description": "Request validation failed — an empty `subject` or `description`, a `subject` over 240 or `description` over 8000 characters, more than 10 tags, or a `priority` outside the four values. `details.errors` names the field."},
  {"status": 401, "code": "unauthenticated", "reason": "", "description": "Key missing, malformed, invalid, revoked, expired after a roll, or used against the wrong host. `details.reason` distinguishes all six."},
  {"status": 403, "code": "permission_denied", "reason": "missing_scope", "description": "The key lacks `tickets:write` — required for creating *and* reading. `details.required_scope` names it."},
  {"status": 404, "code": "not_found", "reason": "", "description": "`Ticket not found.` — unknown id, or a ticket belonging to another workspace."},
  {"status": 409, "code": "conflict", "reason": "idempotency_key_reuse", "description": "The same `Idempotency-Key` arrived with a different request body. Fix the key or the body — do not retry with a fresh key."},
  {"status": 412, "code": "failed_precondition", "reason": "unsupported_resource", "description": "Tickets are not available on this deployment. Configuration, not a transient failure — do not retry."},
  {"status": 429, "code": "rate_limited", "reason": "rate_limited", "description": "120 requests in one minute on this key. Back off to the next minute boundary; there is no Retry-After header."}
]
```

Retry `429`, 5xx, and network errors with the same key and the same bytes. Do not retry `400`, `403`, `404`, `409`, or `412` — the answer will not change, and an escalation stuck in a retry loop is an escalation nobody is working.

## Going to production

- **Alert on escalation volume, not on individual failures.** A handler that suddenly files ten times as many tickets is a bug in your rules, and it looks like success from the API's side.
- **Store `public_ref` against your own record** the moment you get it. It is the only reference a customer can quote and the only one your support team can search for quickly.
- **Log `error.request_id` on every failure.** Every call your key made appears in **Developers → Logs** for 7 days with its status, error code, and duration.
- **Escalate once.** Guard the handler with your own "already escalated" flag as well as the idempotency key. The key expires after 24 hours; your flag does not.

## Next

::: cards

::: card The endpoint reference
[Tickets](/api/tickets) — every field, every bound, and the full deduplication contract.
:::

::: card Ticket events
[`ticket.created` and `ticket.updated`](/webhooks/events) — the exact payloads and the other seven event types.
:::

::: card Idempotency
[How keys are scoped](/api/idempotency), how long they live, and what a replayed response looks like.
:::

::: card Before you launch
[Going live](/operate/going-live) — the checklist this recipe assumes you have worked through.
:::

:::


============================================================================
# SECTION: Operate
============================================================================



----------------------------------------------------------------------------
## Going live
URL: https://docs.amomic.in/operate/going-live
----------------------------------------------------------------------------

Everything on this page is something that has broken a real launch. Work through it once, properly, before your integration touches a customer — the whole list is an afternoon, and every item on it is cheaper now than it is at 2 a.m. with a queue backing up.

Each item states what to do and then why it matters. The why is the part that prevents the bug; skipping to the bullet points will get you a checklist you follow without understanding, which is the failure mode this page exists to prevent.

## Keys and secrets

### Keys live in a secret manager, never in source

Put every `amk_…` token in the secret store your platform already has — Secret Manager, Vault, your orchestrator's secret objects, your CI provider's encrypted variables. It reaches the process as an environment variable at runtime and it appears in no file that a human can `git clone`.

The reason is not abstract. The token prefix `amk` exists precisely so that automated secret scanners can find a leaked key in a repository, which tells you how often it happens. A key in a config file survives every later attempt to be careful: it is in the git history after you delete it, in the fork someone made last year, in the container image layer, and in the CI log that printed the environment during a debugging session. A key in a secret manager is in one place, is rotatable in one place, and has an audit trail.

The same applies to your webhook signing secret. `whsec_…` is shown once, at endpoint creation, and cannot be retrieved afterwards — if you lose it, the only path is delete the endpoint and create a new one.

::: danger Never put a key in front-end code
`/api/v1` sends no CORS headers, so a browser cannot call it — that is deliberate, and it is the reason. A key in a JavaScript bundle is a key anyone can read out of your site. For in-page use there is the [web chat widget](/channels/web-chat), which has its own origin-scoped auth and no API key.
:::

### One key per system, named after that system

Do not share one key across your order service, your warehouse sync, and your support tooling. Create one for each, and name it after the thing that holds it — `Order service`, `Warehouse sync`, `Support console`. Not `Test key 2`, not `Backend`, not `Vinit's key`.

This is a debugging decision more than a security one. When a key starts throwing `429`s at 3 a.m., the name is what tells you which deployment to look at. When you need to revoke one because a contractor left, the name is what tells you what will break. And because the **120 requests per minute limit is per key**, separate keys mean a backfill cannot starve your customer notifications — they are drawing from different budgets. Every call is attributed to its key in the request log under **Developers → Logs**, so the names show up exactly where you need them.

### Each key carries the least scope it needs

New keys are read-only by default — `conversations:read` and `agents:read` — and that default is a position, not an accident. Widen a key only to the six scopes the system holding it actually uses.

A key can be widened later in one click and can never be un-leaked. A warehouse sync needs `conversations:read` and nothing else; if it is compromised, the blast radius is a data read. Give that same key `messages:send` "in case we need it later" and the blast radius becomes messages sent to your customers from your number. Note one asymmetry when you size them: **reading a ticket requires `tickets:write`** — there is no read-only ticket scope, so a key that only looks tickets up can also create them.

Verify what you actually granted with a single call that changes nothing:

```bash
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order service",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

Most "why is this a 403" questions are answered by that response, before any real request is made. See [Scopes](/api/scopes).

### The environment on the key matches the host you point it at

Keys carry an environment. A `amk_test_…` key against `services.amomic.in` fails, and so does a `amk_live_…` key against the development host. The failure is a `401` with `details.reason` of `wrong_environment` — a specific, readable error rather than a silent misroute.

Make the pairing explicit in your configuration so a promotion cannot half-apply. If your base URL and your key come from two different config sources, one of them will eventually be promoted without the other, and the resulting `401` will look like a bad secret to whoever is on call. It is not: it is the right key at the wrong host.

### Rehearse a roll before you need one

Rolling a key mints a new secret with the same name, scopes, and limit, and keeps the old one working for **24 hours**. That grace window exists so you can deploy the new secret without a gap in service. Revoking, by contrast, is immediate and permanent — a revoked key returns `401` within seconds and there is no un-revoke.

Do a roll once, in a non-production environment, before launch. You want to discover that your secret only reloads on a full restart during a rehearsal rather than during an incident. And write down which one you would reach for: a suspected leak is a **revoke**, planned hygiene is a **roll**.

## Requests

### Every money-moving POST carries an idempotency key derived from your own record ids

`POST /messages`, `POST /calls`, and `POST /tickets` honour the `Idempotency-Key` header. Send one on every call to all three. Derive it from an identifier your own system already treats as unique — an order id, an incident id, a conversation id — combined with what the call *is*.

| Key | Verdict |
|---|---|
| `order-4821-shipped` | Correct. One shipment event, retried as many times as needed. |
| `order-4821` | Wrong. The "delivered" message later reuses it, hits a different body, and `409`s. |
| `crypto.randomUUID()` | Wrong. Every retry is a new key, so every retry sends another message. |
| `order-4821-${Date.now()}` | Wrong. The timestamp changes per attempt, so it is not a key at all. |

The point of the header is that your retry after a timeout replays the stored response instead of messaging the customer twice or placing a second call. Within 24 hours, the same key with the same body replays; the same key with a *different* body is a `409` with `idempotency_key_reuse`.

Two properties to code against. The body match is a hash of the **raw request bytes**, so serialise your JSON once and resend the identical string — re-serialising a dictionary with a different key order counts as a different body. And the stored response is written just after the response is returned, so two retries fired milliseconds apart can both execute; space your retries by at least a second. [Idempotency](/api/idempotency) has the full contract.

::: note `POST /contacts` does not honour the header
It is the one POST on the public surface that ignores `Idempotency-Key`. It resolves by email then phone instead, so a repeat with the same identities converges on the same contact — but if the email and phone you send point at two *different* existing contacts, you get a `409` with `identity_conflict` rather than a guessed merge.
:::

### Error handling branches on `error.code`, then on `error.details.reason`

Every non-2xx response uses one envelope:

```json
{
  "error": {
    "code": "failed_precondition",
    "message": "This workspace has no WhatsApp sender connected.",
    "details": { "reason": "channel_not_connected" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Branch on `error.code` for the class of problem — there are nine codes and no others can exist — and on `error.details.reason` for the specific cause. Write a `default` branch on both.

The distinction earns its keep on `401`. Six different reasons produce a `401`, and they call for four different responses: `missing_api_key` and `malformed_api_key` are code defects, `invalid_api_key` and `revoked_api_key` mean fetch the current secret, `expired_api_key` means a roll's grace window ended without you deploying, and `wrong_environment` means the key is fine and the host is wrong. Code that treats all six as "auth broken, page someone" pages the wrong person five times out of six.

Then decide retryability once, centrally:

| Outcome | Retry? |
|---|---|
| Connection error, timeout, no response | Yes — same key, same bytes |
| `429 rate_limited` | Yes, after backing off past the minute boundary |
| `500 internal`, `502 provider_error` | Yes, with backoff |
| `400`, `401`, `403`, `404`, `409`, `412` | No. Retrying cannot change the answer |

And log `error.request_id` on every failure. Every call your keys made is in **Developers → Logs** for 7 days, and quoting a request id turns a support thread into a lookup. [Errors](/api/errors) lists every code and reason.

### Log a correlation id you control

Send `X-Correlation-Id` on every request with a value from your own tracing. It is echoed back on the response and recorded on our side, so when you need to ask about one specific send, the identifier that finds it is one you already have in your logs. If you send nothing, one is generated — which helps us and not you.

## Webhooks

### The endpoint verifies the real signature, against the raw bytes

Your handler must compute `HMAC-SHA256` over the exact string `"{timestamp}.{body}"`, using your `whsec_…` secret as raw UTF-8 bytes, and compare it against the `v1` value in the `Amomic-Signature` header with a constant-time comparison. It must also reject a timestamp more than **5 minutes** from now, which is what stops a captured delivery being replayed at you later.

The failure mode here is specific and extremely common: reading the body with a JSON body-parser and then re-serialising it to verify. Compact separators, key order, and every byte of whitespace are part of what was signed. Use `express.raw` rather than `express.json`, or `await request.body()` rather than the parsed model, and parse only *after* verification passes. [Verifying signatures](/webhooks/signatures) has working code in both languages.

An unverified endpoint is a public URL that anyone who guesses it can post ticket updates and delivery receipts to. Signature verification is the only thing standing between that and your database.

### The endpoint returns 2xx fast, then does the work

Acknowledge, enqueue, process. The delivery times out at **10 seconds**, and the retry ladder is four attempts with roughly a minute of backoff between the first and last.

The consequence of a slow handler is not just latency. A **non-429 4xx stops retries immediately** — that is deliberate, because a `400` is your endpoint saying "this request is wrong" — while 5xx, 429, and timeouts are retried. After **15 consecutive failed events** the endpoint is disabled automatically and receives nothing until an admin re-enables it in the console. There is no replay endpoint, so everything that fired during the outage is gone.

Which leads to the last webhook item.

### Someone is alerted when the endpoint starts failing

Auto-disable is silent from your code's point of view: your handler stops being called, with no error to catch. Monitor for it from both ends.

From our side, the console shows `last_delivery_at`, `last_status`, `consecutive_failures`, and `disabled_reason` per endpoint under **Developers → Webhooks**, along with the delivery log for the last 7 days. From your side, alert on the *absence* of events — a handler that has received nothing for an hour on a workspace that normally sees traffic is the signal, and it fires whether the cause is a disabled endpoint, a DNS change, or an expired certificate.

Also, deduplicate on the envelope `id`. Delivery is at-least-once, which is a promise about duplicates rather than about completeness — the same `evt_…` can arrive twice, and your handler must be safe when it does.

### There is a reconciliation path that does not depend on webhooks

Because events can be lost — an outage, an auto-disable, a deploy that 500s for ten minutes — anything you must not lose needs a second path. For conversations that is the [sync job](/recipes/sync-conversations): scheduled, watermarked, and complete by construction. For call outcomes it is `GET /calls/{call_id}`. For tickets it is `GET /tickets/{ticket_id}`.

Webhooks for freshness, polling for completeness. Either alone has a failure mode the other covers.

## Channels

### Notification flows have a plan for the 24-hour window

WhatsApp only permits free-form text inside the **24-hour customer service window**, which opens when the customer messages you and closes 24 hours after their most recent message. Business events — an order shipped, a payment failed, an appointment tomorrow — almost never fall inside it.

So decide per flow, in advance:

- **Notifications send an approved template, every time.** Templates bypass the window; that is the entire reason they exist. Do not "try text and fall back to a template" — you spend a round trip to discover a state you already know, and customers whose window happens to be open receive differently-worded messages from the rest.
- **Reply flows send text**, inside the window your customer opened.

Sending text with the window closed returns `409` with `session_window_closed`. Before launch, confirm every template you depend on is **approved** — not `pending`, not `rejected` — because both non-approved states produce the same `404 template_not_found` at send time. [The 24-hour window](/channels/whatsapp-window) and [Templates](/channels/whatsapp-templates) cover both halves.

### You have sent to a real phone number and read the result on a handset

Not the console preview. Not a colleague's screenshot. A real number you control, receiving the real message from the real key against the production host, read on a phone.

Templates approve on their wording and render with your values. A line that reads correctly with `{{1}} = "Asha"` can read badly with `{{1}} = "asha menon (guest checkout)"`, an amount can arrive without its separators, and a message you thought was one paragraph can arrive as four. For voice, place a real call and listen to the whole thing: the opening line, the pace, how the agent handles being interrupted, and what it says when it does not know something.

Read the numbers you are sending to, too. Phone numbers must match `^\+?\d+$` and be 6–20 characters — `+919876543210` and `919876543210` both validate, while `+91 98765 43210`, `+91-98765-43210`, and `(+91) 98765 43210` are all rejected. If your CRM stores formatted numbers, normalise them before they reach the API, not after the first `400`.

### Outbound calls are treated as asynchronous

`POST /calls` returns `201` when the number is **ringing**, not when someone answers. The outcome — `duration_seconds`, `outcome`, `summary` — arrives later, from `GET /calls/{call_id}` or the `call.ended` webhook.

Code that treats the `201` as a completed call will report every unanswered phone as a success. Also budget for the concurrency ceiling: **10 live calls per workspace**, enforced as a `429` with `details.reason` of `call_concurrency`, which is entirely separate from the per-key request limit. A campaign that fires 200 calls in a loop meets it on call eleven. Queue them.

## Capacity and operations

### You know your rate-limit headroom

The limit is **120 requests per minute, per key**, counted in a fixed one-minute window rather than a sliding one. Before launch, work out your steady-state and your worst case:

- What does one customer event cost in requests? An order update is one `POST /messages`. An escalation that pulls context is three.
- What is your peak? A sale, a dispatch batch, a nightly reconciliation run.
- What else shares the key? If the answer is anything, give that thing its own key.

On success, every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining` — read them and slow down before you are told to. On a `429` there is **no `Retry-After` and no `X-RateLimit-Reset`**; the window is a wall-clock minute, so sleeping to the next minute boundary is exactly right. Pace bulk work at roughly two requests per second rather than bursting and absorbing rejections. [Rate limits](/api/rate-limits) has the details.

### Configuration failures alert separately from message failures

`channel_not_connected` and `template_not_found` are not message failures. They are configuration incidents, and every message you attempt will fail identically until a human fixes something in the console. Folding them into a generic "message failed" alert buries the one line that tells you what to do.

Give them their own alert, with the fix in the alert text. The same applies to `no_agent_deployed` and `no_phone_number` on the voice side.

### You have watched the request log

Open **Developers → Logs** in the console and look at your own traffic before you launch. Every `/api/v1` call your keys made is there for **7 days** with method, path, status, duration, key name, error code, request id, and correlation id.

Doing this once before launch is worth more than reading about it. You will find the call you thought you removed, the retry loop that fires four times instead of once, and the endpoint you are hitting twice per event. All three are easier to fix now.

### You know who to contact, and what to send them

Write it down where the on-call person will find it, before the incident.

| Situation | Contact | Send |
|---|---|---|
| Something is broken or behaving unexpectedly | `support@amomic.in` | The `request_id` from the error envelope, the time in IST, and the key name |
| A suspected security issue or a leaked key | `security@amomic.in` | What you found and how to reproduce it — and revoke the key first, from the console |
| A key needs revoking right now | Console → **Developers → API keys** | Nothing. Revoke takes effect within seconds and does not need us |

`request_id` is the single most useful thing you can quote. It appears in every error envelope and in your request log, and it identifies exactly one call.

## The list, condensed

| # | Item | Done when |
|---|---|---|
| 1 | Keys in a secret manager | No `amk_` string exists in any repository or image |
| 2 | One key per system, named for it | Each key's name identifies a deployment you could point at |
| 3 | Least scope on every key | `GET /ping` returns only the scopes that system uses |
| 4 | Key environment matches host | Base URL and key come from the same config source |
| 5 | Roll rehearsed | You have rolled a key and deployed the new secret without downtime |
| 6 | Idempotency keys everywhere | Every `POST` to messages, calls, and tickets sends one derived from your record ids |
| 7 | Errors branch on code then reason | Six `401` reasons take four different actions; a `default` branch exists |
| 8 | Correlation ids sent | `X-Correlation-Id` carries your trace id on every request |
| 9 | Signature verified on raw bytes | Your handler rejects a tampered body and a 6-minute-old timestamp |
| 10 | Handler returns 2xx in well under 10 s | Work happens after the acknowledgement, not before |
| 11 | Webhook failure alerts | You are paged on silence, not just on errors |
| 12 | Reconciliation path exists | Losing an hour of webhooks costs you nothing permanent |
| 13 | Window plan per flow | Notifications use templates; replies use text |
| 14 | Real phone tested | You have read the message on a handset and heard the call |
| 15 | Rate-limit headroom known | You can state your peak requests per minute per key |
| 16 | Config failures alert separately | `channel_not_connected` does not look like a bad message |
| 17 | Request log reviewed | You have seen your own traffic in **Developers → Logs** |
| 18 | Contacts written down | On-call knows where to send a `request_id` at 2 a.m. |

## Next

::: cards

::: card Limits and plans
[What is enforced](/operate/limits) — rate limits, field bounds, and which plan limits actually block a create.
:::

::: card Troubleshooting
[Symptom-first index](/operate/troubleshooting) — every error you can hit, what it means, and how to fix it.
:::

::: card Security and data
[How keys are stored](/operate/security), what the request log keeps, and how to report a vulnerability.
:::

::: card API versioning
[What can change without notice](/operate/versioning) and what would require a new version.
:::

:::


----------------------------------------------------------------------------
## Limits & plans
URL: https://docs.amomic.in/operate/limits
----------------------------------------------------------------------------

There are two kinds of limit here and confusing them wastes an afternoon. **Plan limits** govern how many things your workspace can own — agents, knowledge bases, deployments, team seats. **API limits** govern individual requests — how fast you may call, how long a field may be, how many items a page may hold.

Plan limits are enforced in the console and in the platform when you create a resource. API limits are enforced on every request. Neither depends on the other: your plan does not change your rate limit, and no plan gates access to `/api/v1`.

## Plans

Four plans. Prices are per month and exclude GST.

| | **Free** | **Starter** | **Growth** | **Enterprise** |
|---|---|---|---|---|
| Plan id | `free` | `starter` | `growth` | `enterprise` |
| Price | ₹0 | ₹2,999 | ₹7,999 | Custom |
| AI agents | 1 | 3 | 10 | Unlimited |
| Knowledge bases | 1 | 3 | 10 | Unlimited |
| Deployments | 3 | 9 | 40 | Unlimited |
| Team seats | 2 | 3 | 10 | Unlimited |
| AI conversations / month | 100 | 1,000 | 5,000 | Custom |
| Voice minutes / month | — | Pay-as-you-go at ₹6/min | 500 included, then ₹6/min | Custom |
| Phone numbers | — | ₹399/number/month | 1 included, then ₹399/month | Custom |
| Channels | Web chat | Web chat and WhatsApp | Everything, including voice | Everything |

A **conversation** is one customer-to-agent thread on one channel within 24 hours. The same person messaging you on WhatsApp on Monday and again on Wednesday is two conversations; twenty messages back and forth on Monday is one.

An unknown or unreadable plan id resolves to `free`. Enterprise carries no numeric caps at all.

::: note Voice is a separate meter from conversations
Voice minutes are counted on their own and are deliberately excluded from the conversation count, so a call is not billed twice. Voice usage and WhatsApp usage both reset on the **UTC calendar month**.
:::

## What is actually enforced

This distinction matters more than the table above, because it tells you which limits can fail a request.

**Four limits block a create.** When you are at the cap, the create returns `409` with the message below and nothing is written:

| Limit | Enforced when | Message |
|---|---|---|
| `agents` | You create an agent | *Your plan includes {limit} agent(s). Upgrade to add more.* |
| `knowledge_bases` | You create a knowledge base | *Your plan includes {limit} knowledge base(s). Upgrade to add more.* |
| `deployments` | You create a deployment | *Your plan includes {limit} deployment(s). Upgrade to add more.* |
| `members` | You invite a team member | *Your {Plan} plan includes {limit} team seats and they're all used (including pending invites). Upgrade your plan to add more.* |

Seats count **active members plus pending invites**. An invitation that nobody has accepted still occupies a seat, which is the usual explanation for a workspace that appears to have room and does not. Cancel stale invites before you buy more seats.

**Everything else on the plan table is a meter.** Conversations and voice minutes are counted and displayed in the console. They do not block a create, they do not fail an API call, and going past one does not stop your agents answering. If your volumes are heading well past your plan, talk to us before the month ends rather than after — the meter is telling you something about the plan you are on, not about a wall you are approaching.

::: warning Downgrading does not delete anything
If you drop from Growth to Starter with six agents, all six keep working. What changes is that you cannot create a seventh until you are back under the cap. Nothing is deleted, disabled, or hidden — the limit is on creation only.
:::

Two more properties worth knowing:

- **Enforcement fails open.** If the entitlement lookup cannot be read, the create is allowed. A blip in our infrastructure will never block you from adding an agent. It also means an occasional create can slip past a cap; the next one will not.
- **There are absolute backstops above the plan caps.** A workspace cannot exceed 20 agents or 50 knowledge bases regardless of plan. You will meet your plan limit long before either.

Plan limits apply to resources, not to API calls. Nothing on `/api/v1` is gated by plan — access there is scope plus rate limit, nothing else.

## API rate limit

```
120 requests per key, per minute
```

Counted in a **fixed one-minute window** keyed on the wall clock, not a sliding window. At the top of each minute the counter resets to zero. The counter is shared across every server that handles your traffic, so the limit is global rather than per-instance.

The limit is **per key, not per workspace**. Three keys give you three independent budgets, which is the cheapest way to stop a backfill starving your production sends.

### Headers

On every **successful** response where a key was checked:

```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
```

Read `X-RateLimit-Remaining` and slow down before you are rejected. Note the asymmetry: these headers appear on success only. A `4xx` or `5xx` — including the `429` itself — carries no `X-RateLimit-*` header.

### When you exceed it

```json title="429 Too Many Requests"
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 120 requests/minute exceeded for this key.",
    "details": { "reason": "rate_limited", "limit": 120, "window_seconds": 60 },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

There is **no `Retry-After` header** and **no `X-RateLimit-Reset` header**. Because the window is a wall-clock minute, sleeping until the next minute boundary is the correct backoff and anything shorter is a wasted request:

```python
import time
time.sleep(60 - (time.time() % 60) + 0.25)
```

If the counter store is unreachable, the limiter fails open and your request is served. You will never be rejected because our rate limiter had a bad day.

For bulk work, pace at roughly two requests per second rather than bursting and absorbing rejections. [Rate limits](/api/rate-limits) covers pacing patterns in more depth.

## Concurrent outbound calls

```
10 live calls per workspace
```

Separate from the request limit, counted differently, and reported differently. This one counts calls that are currently ringing or in progress across the whole workspace, regardless of which key placed them.

```json title="429 Too Many Requests"
{
  "error": {
    "code": "rate_limited",
    "message": "This workspace already has 10 calls in progress (limit 10). Try again shortly.",
    "details": { "reason": "call_concurrency", "limit": 10 },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

Both limits produce `429` with `code: "rate_limited"`, so branch on `details.reason` to tell them apart. `rate_limited` means slow down; `call_concurrency` means wait for a call to end. A loop that fires 200 calls will meet this on the eleventh — queue them and drain the queue as `call.ended` events arrive.

## Field and size limits

Every one of these is enforced at validation. Exceeding one returns `400` with `code: "invalid_argument"`, the message `Request validation failed.`, and `details.errors` naming the field.

| Field | Endpoint | Limit |
|---|---|---|
| `text` | `POST /messages` | 4096 characters |
| `to` | `POST /messages`, `POST /calls` | 6–20 characters, pattern `^\+?\d+$` |
| `sender_id` | `POST /messages` | 64 characters |
| `template.name` | `POST /messages` | 1–120 characters |
| `template.language` | `POST /messages` | 16 characters |
| `agent_id` | `POST /calls` | 64 characters |
| `from_number` | `POST /calls` | 20 characters |
| `purpose` | `POST /calls` | 500 characters |
| `ring_seconds` | `POST /calls` | 10–90, default 30 |
| `subject` | `POST /tickets` | 1–240 characters |
| `description` | `POST /tickets` | 1–8000 characters |
| `priority` | `POST /tickets` | One of `low`, `normal`, `high`, `urgent` — default `normal` |
| `tags` | `POST /tickets` | At most 10 items |
| `name` | `POST /contacts` | 120 characters |
| `email` | `POST /contacts` | 200 characters |
| `phone` | `POST /contacts` | 32 characters |
| `Idempotency-Key` | Header | Truncated to 200 characters |

Non-request limits that show up in the same conversations:

| Thing | Limit |
|---|---|
| Maximum call length | 60–3600 seconds, default 600 |
| Web chat image upload | 5 MB, on paid plans only |
| Knowledge base file upload | 15 MB per file |

::: note Phone number formatting is stricter than it looks
`^\+?\d+$` means digits with an optional leading `+` and nothing else. `+919876543210` and `919876543210` both pass. `+91 98765 43210`, `+91-98765-43210`, and `(+91) 98765 43210` are all rejected at validation. Normalise before you send. Responses always come back as `+` followed by digits.
:::

There is no media or attachment upload on `POST /messages` — text and approved templates only. There is no batch send endpoint and no scheduling parameter.

## Pagination bounds

| Endpoint | `limit` range | Default |
|---|---|---|
| `GET /conversations` | 1–100 | 25 |
| `GET /conversations/{id}/messages` | 1–200 | 100 |
| `GET /agents` | No `limit` parameter | Returns everything |

A `limit` outside its range is a `400`, not a silent clamp. `GET /agents` returns the same `{items, next_cursor}` envelope as the others but never paginates — `next_cursor` is always `null`.

`next_cursor` is non-null only when a page came back **full**. A short page ends the walk. See [Pagination](/api/pagination).

## Retention

| Thing | Kept for |
|---|---|
| API request log | **7 days** |
| Webhook delivery records | **7 days** |
| Idempotency records | **24 hours** |
| Key roll grace window | **24 hours** |
| WhatsApp session window | **24 hours** |
| Webhook signature timestamp tolerance | **5 minutes** |

The request log is the one you will use. Every `/api/v1` call your keys made appears under **Developers → Logs** with method, path, status, duration, key name, error code, request id, and correlation id — for seven days, enforced on read as well as on expiry. Requests rejected before authentication are not attributed to any workspace and do not appear.

If you need call or conversation history beyond what the console shows, pull it into your own store — [Sync conversations into your warehouse](/recipes/sync-conversations) is the job for that.

## Related

::: cards

::: card Rate limits in depth
[The window, the headers, and pacing](/api/rate-limits) — including what a backfill costs.
:::

::: card Going live
[The pre-launch checklist](/operate/going-live) — including how to work out your rate-limit headroom.
:::

::: card Troubleshooting
[Symptom-first index](/operate/troubleshooting) — including both flavours of `429`.
:::

::: card Errors
[Every code and reason](/api/errors) in one place.
:::

:::


----------------------------------------------------------------------------
## Security & data
URL: https://docs.amomic.in/operate/security
----------------------------------------------------------------------------

This page describes what the platform actually does with your credentials and your data. It is written to be checked rather than believed — every claim here corresponds to a behaviour you can observe from the outside.

## API keys

### The secret is hashed, and nobody can recover it

A key looks like this:

```
amk_live_7Fk2xQ9pR4vN8mJ1cT6yW3zB5hL0dG2s
│   │    └─ 32 random bytes, base64url encoded
│   └────── environment: live or test
└────────── product prefix, always amk
```

The 32 random bytes come from a cryptographically secure generator. What we store is **`SHA-256` of that secret and nothing else**. The raw token exists in exactly one place after creation: wherever you put it.

That means the secret is not recoverable by anyone. Not by support, not by an engineer with database access, not by us under any circumstances. This is a deliberate design decision and not a limitation we intend to fix — a system that can show you your key can be compelled, tricked, or breached into showing it to someone else. A hash cannot.

SHA-256 rather than a slow password hash is also deliberate. Slow hashes exist to defend low-entropy human-chosen passwords against offline guessing. These secrets carry 256 bits of entropy from a random generator; guessing is not the threat model, and a fast one-way function is the right tool.

Alongside the hash we keep a **key id** — a public, loggable identifier derived one-way from the secret. It is what appears in the request log and in support conversations. It cannot be turned back into a key.

### One reveal, then a masked hint

The full token is shown exactly once, in the dialog that created it, and once more if you roll it. Every read after that returns a masked form:

```
amk_live_7Fk2xQ…
```

Enough to tell two keys apart in a list. Not enough to authenticate.

::: danger Copy it before you close the dialog
If you lose a secret, there is no recovery path — only a roll, which issues a new one. Put it into your secret manager while the dialog is open. The same applies to a webhook signing secret (`whsec_…`), which is also shown once and, if lost, requires deleting and recreating the endpoint.
:::

The `amk` prefix is there so automated secret scanners can recognise a leaked key in a repository, a paste, or a log. If you receive an alert from one, treat it as real and revoke.

### Roll with grace, or revoke immediately

Two operations with two different purposes. Choose by intent, not by convenience.

**Roll** mints a new key with the **same name, same scopes, and same rate limit**, returns the new secret once, and keeps the old key working for **24 hours**. That window exists so you can deploy the new secret to every consumer without a gap in service. When the window ends, the old key returns `401` with `details.reason` of `expired_api_key` — a distinct reason, so you can tell "you missed the deployment window" apart from "this key was never valid".

**Revoke** is immediate and permanent. The key returns `401` with `revoked_api_key` from then on, and there is no un-revoke — a revoked key is dead, and replacing it means creating a new one.

| Situation | Operation |
|---|---|
| Planned rotation, quarterly hygiene | Roll |
| A developer with the key has left, no evidence of misuse | Roll, then revoke the old one early |
| A key appeared in a repository, a log, or a screenshot | **Revoke.** Then create a new one |
| You lost the secret and cannot deploy | Roll |

A revoked or rolled-out key stops working **within seconds**. Verified key records are cached in memory for up to five seconds, so a revocation propagates in that time across every instance serving your traffic; the instance that handled the change applies it immediately.

::: note `last_used_at` is coarse on purpose
It is written at most once a minute per key, to keep verification a single fast read. Use it to spot a key nobody has touched in months, not to reason about a specific request. For that, use the request log.
:::

### Keys are workspace-wide

There is no per-user, per-agent, or per-deployment key. A key belongs to the workspace, and **scopes are the only partitioning mechanism**. Six scopes exist; a new key gets the two read-only ones by default.

Size keys accordingly: one per system that calls the API, each with the least scope that system needs. That gives you separate rate-limit budgets, separate lines in the request log, and the ability to revoke one integration without taking the rest down. See [Scopes](/api/scopes).

## No CORS on `/api/v1`, deliberately

The public API sends **no** `Access-Control-Allow-Origin` header and does not answer preflight requests. A browser cannot call it from a web page, and no configuration option will change that.

The reasoning is short: an API key in front-end JavaScript is a leaked API key. Anyone can open developer tools and read it out of your bundle, and once it is out you cannot un-leak it — you can only revoke and redeploy. CORS support would be a feature whose main use is making that mistake possible, so it does not exist.

Call `/api/v1` from your backend. For genuine in-page use there is the [web chat widget](/channels/web-chat), which authenticates by origin, carries no API key, and is scoped to exactly what a visitor should be able to do.

## Webhook signing

Every delivery to your endpoint carries:

```
Amomic-Signature: t=1754049600,v1=6f1c9e0b4a2d8f37c5e1b0a94d7f2e63c8b1a05e9f3d7c26b4a8e1f0d5c937b2
```

`v1` is `HMAC-SHA256` over the exact string `"{t}.{body}"`, keyed on your endpoint's signing secret. Your verifier recomputes it against the **raw request bytes**, compares in constant time, and rejects any delivery whose timestamp is more than **5 minutes** from now. [Verifying signatures](/webhooks/signatures) has working code.

### Why signing rather than an IP allowlist

We could publish a list of source addresses and ask you to allow them. We sign instead, for four reasons that all bite in production:

- **An allowlist proves origin, not integrity.** It tells you a packet came from our range. It does not tell you the body was not modified in transit, and it cannot tell you the request was not replayed. A signature over the body proves both.
- **Addresses change.** Ours run on managed infrastructure that scales and moves. A published list is a promise to never change infrastructure, or an outage the day we do.
- **Shared infrastructure makes an allowlist weak.** Anything else running on the same platform can appear to be in the range. "It came from a big cloud provider" is close to no assertion at all.
- **A signature works everywhere.** Behind a load balancer, a CDN, a corporate proxy, a tunnel to a laptop. Anywhere the header survives, the check works — which means the check you wrote in development is the check running in production.

The timestamp in the header is what makes replay expensive. A captured delivery re-sent an hour later fails the tolerance check even though its signature is genuine.

::: warning Verify against the bytes you received
The most common webhook bug in any integration: parse the JSON, re-serialise it, verify against the result. It will not match. The body is serialised compactly and every byte is part of what was signed. Read the raw body, verify, and parse only afterwards.
:::

## Transport

Everything is HTTPS. There is no plaintext endpoint for the API and no plaintext option for webhooks — a webhook URL must start with `https://`, and an `http://` URL is rejected at creation with a `400` and the message `Webhook URLs must use https.`

Webhook deliveries do **not follow redirects**. If your endpoint moves, update the endpoint in the console; a `301` to the new address will be treated as a failed delivery rather than quietly followed to a destination we cannot verify. Deliveries time out at 10 seconds total, 5 seconds to connect.

## Workspace isolation

Your data does not cross a workspace boundary. The rule is enforced at the point every query is built, not by a filter someone remembered to add at the end:

- **Every read is scoped to the workspace on the key.** There is no parameter, header, or trick that widens it.
- **A foreign id is a `404`, identical to a missing one.** `GET /conversations/{id}`, `GET /calls/{id}`, and `GET /tickets/{id}` all return the same `not found` message whether the id does not exist or belongs to someone else. That is a deliberate choice: distinguishing the two would confirm the existence of another workspace's data to anyone with an id-shaped guess.
- **Responses are projections, not dumps.** Conversation and message responses carry a fixed set of public fields; internal routing and identity fields are not projected at all.
- **Webhook payloads are allow-lists.** Each event type emits a named set of fields. Adding a field to an internal event does not leak it into your webhook — it has to be added to the projection deliberately.

Credentials you give us — WhatsApp tokens, knowledge base source headers, webhook signing secrets — are held in a managed secret vault, referenced rather than stored, and **masked on every read**. A configuration you write is accepted on the way in and never returned on the way out.

## What the request log keeps

Every `/api/v1` call your keys make is recorded in your workspace's own request log, visible under **Developers → Logs**:

| Recorded | Not recorded |
|---|---|
| Method and path | Request bodies |
| HTTP status and `error_code` | Response bodies |
| Duration | Any secret, header value, or token |
| Key id and key name | |
| `request_id` and `correlation_id` | |

Retention is **7 days**, enforced when the log is read as well as when records expire — so the seven-day promise is true at the moment it is made, not whenever a cleanup last ran.

Requests rejected *before* authentication — a missing key, a malformed one — are not attributed to any workspace and do not appear in anyone's log.

Webhook delivery records are kept for the same 7 days and carry the endpoint, event type, event id, final attempt number, status code, error text, duration, and the event payload we sent when it is small enough to store. They are a record of what we sent you, not of what you did with it.

Send `X-Correlation-Id` on your requests and it is echoed back and recorded, which lets you join your traces to ours during an investigation.

## Call recording

Recording is **off by default**. It is an explicit opt-in, set per workspace or per deployment, and nothing is captured until someone turns it on.

When it is on, a spoken notice plays **before the greeting**, on every call:

> Just to let you know, this call may be recorded for quality and training purposes.

On calls running in an Indian-language register, the same notice is spoken in that register. It is an announcement rather than a gate — there is no keypad option to decline — so if your use case needs a genuine opt-out, build it into what your agent says and does after the notice.

Recordings are dual-channel WAV with the caller on one channel and the agent on the other, stored in your workspace's own space. Playback links are **signed URLs valid for one hour**; the storage has no public access, so a link that leaks stops working within the hour and there is no unauthenticated path to the file at all.

::: note Recording is a decision you own
Turning it on changes what you are collecting about your customers. Whether that is appropriate — and what you must tell people beyond the spoken notice — depends on your jurisdiction and your own policies. The platform gives you the switch and the announcement; the rest is yours.
:::

## Reporting a security issue

If you have found a vulnerability in the API, the console, the widget, or anything else we operate, we want to hear about it.

**Write to `security@amomic.in`.** Include what you found, the steps to reproduce it, and what an attacker could do with it. A request id, a timestamp in IST, and the workspace you were working in all help us find it quickly.

Two requests, and we mean both of them:

- **Tell us before you publish.** Give us a reasonable window to fix the issue and get a fix deployed before the details are public. We will keep you informed while we work on it, and we are happy to credit you when it is resolved.
- **Do not test against other customers' workspaces.** Use your own. Do not access, modify, or retain data that is not yours; do not run traffic that degrades service for anyone else; and if you stumble into someone else's data while investigating, stop, and tell us what you saw rather than exploring further.

If you find a leaked key — yours or one you believe is someone else's — revoke it first if you can, then tell us.

For a security review or a procurement questionnaire, the same address is the right one. We would rather answer a specific question accurately than point you at a badge.

## Related

::: cards

::: card Authentication
[Key formats, header forms, and all six 401 reasons](/api/authentication).
:::

::: card Scopes
[The six scopes](/api/scopes) and how to size a key to a system.
:::

::: card Verifying signatures
[Working verifiers](/webhooks/signatures) in Node.js and Python, and the mistakes that break them.
:::

::: card Going live
[The pre-launch checklist](/operate/going-live) — where most of this becomes a task with a tick box.
:::

:::


----------------------------------------------------------------------------
## API versioning
URL: https://docs.amomic.in/operate/versioning
----------------------------------------------------------------------------

`/api/v1` is the published, stable surface. Everything documented on this site lives under it, and the contract on this page is what you can build against.

There is currently **one version**. There is **no version header**, no `Accept-Version`, and no `/api/v2`. The version lives in the path and nowhere else, so a request that works today works tomorrow without you sending anything extra.

## What is public and what is not

| Surface | Prefix | Supported? |
|---|---|---|
| Public developer API | `/api/v1` | **Yes.** Documented here, authenticated with an `amk_…` key, stable under the rules below. |
| The console's own API | Everything else | **No.** Private, undocumented, authenticated differently, and changed whenever the console needs it to change. |

The console is a client of an internal API that exists to serve the console. Its routes are not a supported external surface: they carry no compatibility promise, they can be renamed or removed in any deploy, and they authenticate with a session rather than a key. If you find one in a browser's network tab and build against it, it will break, and it will break without warning because nobody was told it had users.

Anything the console can do that you need programmatically is either on `/api/v1` already or is not currently available over an API. Creating keys and webhook endpoints is the clearest example — both are console-only operations, on purpose, because minting a credential from a credential is a design decision we have not made.

A machine-readable description of the public surface is served, without authentication, at:

```endpoint
GET /api/v1/openapi.json
```

The `info.version` inside that document describes the document. The API version is the `v1` in the path.

## Changes we may make without notice

These are additive. Client code written to the rules further down absorbs all of them without a deploy.

**Adding a field to a response.** A new field can appear on any object at any time — a conversation, a ticket, a call, a webhook payload. Existing fields keep their names, types, and meanings.

**Adding an endpoint.** A new path under `/api/v1`, or a new method on an existing path. Nothing you already call changes.

**Adding an optional request field.** New optional parameters with defaults that preserve current behaviour. A request that does not send them behaves exactly as it does today.

**Adding a value to an enum-like field.** A new `status`, a new `outcome`, a new `channel`, a new event type. This is the one that breaks naive clients most often — see below.

**Adding a new `details.reason`.** The nine `error.code` values are fixed. The `reason` strings inside `details` are not: a condition that today produces a generic error may later produce one with a more specific reason, so that you can handle it better. Your `default` branch is what makes that a free improvement rather than an incident.

**Adding a response header.** Diagnostic or informational headers may appear.

## Changes that would require a new version

We would not ship any of these into `/api/v1`. If one became necessary, it would arrive as a new versioned namespace, and `/api/v1` would keep behaving as documented.

**Removing or renaming a field.** If `preview` exists on a conversation today, it exists on a conversation in `/api/v1` tomorrow.

**Changing a field's type.** A string does not become an object. An integer does not become a string. A single value does not become an array.

**Changing the error code for an existing condition.** A condition that returns `412 failed_precondition` today will not start returning `409 conflict` in `v1`. The `reason` inside `details` may become more specific; the code and status will not move underneath you.

**Tightening validation.** A request that is accepted today will not start being rejected. Loosening — accepting something we currently reject — is additive and may happen.

**Changing the meaning of an existing value.** Not just the name or the type: if `status: "ringing"` means the phone is ringing, it will not come to mean something else.

**Removing an endpoint, a scope, or an event type.**

::: note There is no deprecation timeline to plan around, because there is nothing deprecated
Nothing in `/api/v1` is scheduled for removal. If that ever changes, it will be a new version alongside this one rather than a countdown inside it.
:::

## What this means for your code

Five habits. Each one costs nothing to adopt now and each one prevents a specific outage.

### Tolerate unknown fields

Parse permissively. Read the fields you need and ignore the rest.

Concretely: do not use a strict schema validator that rejects unknown keys, do not use a deserialiser configured to fail on unrecognised properties, and do not assert on the exact shape of a response in a production code path. If your language's JSON library has a "fail on unknown" mode, this API is not the place for it.

Two endpoints make this non-negotiable rather than merely advisable. `POST /tickets` and `GET /tickets/{ticket_id}` return the ticket record, which carries more than the fields documented in [Tickets](/api/tickets) — assignment state, escalation bookkeeping, internal versioning. `POST /contacts` returns a contact object whose full shape is owned elsewhere. Read the documented fields from both; treat everything else as absent.

```python
# Fine — reads what it needs.
ticket_ref = response.json()["public_ref"]

# Fragile — breaks the first time a field is added.
Ticket(**response.json())
```

### Do not switch exhaustively on a status

Several fields carry values from systems that own their own vocabularies. Write a `default` branch on every one of them.

**Call `status` is the important case.** It is typed as a plain string with **no declared enum**. You will observe `ringing`, `in_progress`, `completed`, and `failed`, and that list is an observation rather than a contract — the call lifecycle can write a state you have not seen. Code that raises on an unrecognised call status is code that raises during an incident, which is the worst possible moment to lose your call tracking.

```javascript
// Correct: known states get behaviour, everything else is recorded and ignored.
switch (call.status) {
  case "ringing":
  case "in_progress":
    return keepPolling(call);
  case "completed":
    return finalise(call);
  case "failed":
    return markFailed(call);
  default:
    log.info({ status: call.status }, "unrecognised call status");
    return keepPolling(call);
}
```

The same applies to:

- **`status` on a `message.status` webhook.** WhatsApp owns that vocabulary — `sent`, `delivered`, `read`, `failed` — and we pass it through unchanged rather than mapping it into one of our own.
- **`channel` on a conversation.** New channels are additive.
- **`status` on a conversation or a ticket.** Lifecycle states your team drives in the console.
- **`type` on a webhook envelope.** Nine event types exist today. An endpoint subscribed to all events — one created with an empty `events` list — will receive any new type the moment it exists. The console's "test endpoint" button already sends a `ping` type that is not one of the nine, so a handler with no `default` branch has a bug you can trigger yourself from the console in about four seconds.

### Treat a missing field as absent, not as an error

Webhook payload projections **omit keys whose value is null** rather than sending them as `null`. A `message.received` event without a `text` key is an ordinary media message, not a malformed delivery. Read with a default (`data.get("text")`, `data.text ?? null`) rather than an index that throws.

REST responses do the opposite for documented fields — they send `null` explicitly. Both shapes exist; code that handles either handles both.

### Do not depend on field ordering or whitespace

JSON objects are unordered. The order keys appear in a response is an artifact of serialisation and carries no meaning; do not compare responses as strings, and do not hash a response body to detect change.

There is one place where bytes genuinely matter, and it runs in the opposite direction. **Webhook signatures are computed over the exact bytes we sent**, so your verifier must read the raw body and must not re-serialise a parsed object first. And **idempotency matching hashes the raw request bytes**, so a retry must resend the identical string — serialise once, keep the string, resend it. In both cases the rule is "use the bytes as they are", never "reproduce the bytes yourself".

### Regenerate clients deliberately

If you generate a client from `/api/v1/openapi.json`, regenerate on your schedule rather than at build time from a live fetch. A build that reaches out to a remote document is a build that fails when the network does, and a generated client that silently changes shape between two deploys of the same commit is worse than a hand-written one.

Generated clients also tend to default to strict deserialisation, which is exactly the setting to turn off. Check what yours does with an unexpected field before you trust it in production.

## Timestamps: two shapes, both stable

Not a versioning rule but the same class of assumption, and worth stating because it surprises people:

| Where | Shape | Example |
|---|---|---|
| REST resources | ISO 8601 with an offset and microseconds | `2026-08-01T10:02:55.118307+00:00` |
| Webhook envelope `created_at` | ISO 8601 with second precision and a literal `Z` | `2026-08-01T10:02:55Z` |

Both are stable. Parse them with a real ISO 8601 parser rather than a format string, and normalise on the way into your store if you keep both. A field that cannot be formatted comes back as `null` rather than as an error.

## Related

::: cards

::: card Errors
[The nine codes](/api/errors) — the fixed part of the error contract, and the `reason` strings that can grow.
:::

::: card Overview
[The API surface](/api/overview) — every endpoint under `/api/v1` in one place.
:::

::: card Changelog
[What has actually shipped](/operate/changelog), and how this changelog is maintained.
:::

::: card Going live
[The pre-launch checklist](/operate/going-live) — where forward-compatible error handling becomes a tick box.
:::

:::


----------------------------------------------------------------------------
## Troubleshooting
URL: https://docs.amomic.in/operate/troubleshooting
----------------------------------------------------------------------------

Something is not working. This page is organised by what you are looking at, not by what we think the cause is. Find your symptom, read what it means, apply the fix.

## Before you dig

Three things to have in front of you. They resolve a surprising share of cases on their own.

**The error envelope.** Every non-2xx response carries the same shape, and it names the problem twice:

```json
{
  "error": {
    "code": "failed_precondition",
    "message": "This workspace has no WhatsApp sender connected.",
    "details": { "reason": "channel_not_connected" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

`error.code` is the class of problem — nine possible values. `error.details.reason` is the specific cause. Read both before forming a theory.

**`GET /ping`.** It costs nothing, changes nothing, and answers most authentication questions outright:

```bash
curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"
```

```json title="200 OK"
{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Order service",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}
```

Which key is this really? Which workspace? Which environment? Which scopes? All four, in one call, with no side effects.

**The request log.** **Developers → Logs** in the console holds every `/api/v1` call your keys made for the last **7 days**, with method, path, status, duration, key name, error code, and `request_id`. When your logs and your theory disagree, this is the tiebreaker. Requests rejected before authentication — no key, malformed key — are not attributed to a workspace and will not appear here.

## Symptom index

| What you are seeing | Go to |
|---|---|
| `401` on every call, or suddenly after a deploy | **401 — the key was not accepted** |
| The key works from my laptop but not from production | **401 — `wrong_environment`** |
| `403` on one endpoint only | **403 — `missing_scope`** |
| WhatsApp text fails but templates work | **409 — `session_window_closed`** |
| A retry returns `409` instead of the original response | **409 — `idempotency_key_reuse`** |
| Creating a contact returns `409` | **409 — `identity_conflict`** |
| Every message fails identically | **412 — `channel_not_connected`** |
| An endpoint says the channel or resource is unavailable | **412 — `unsupported_channel` / `unsupported_resource`** |
| Calls fail before they ring | **412 — voice preconditions** |
| A template that exists returns `404` | **404 — `template_not_found`** |
| A template send returns `400` | **400 — `template_variables`** |
| A message send returns `400` with no obvious cause | **400 — `empty_message`** |
| `429` under load | **429 — two different limits** |
| My webhook handler rejects everything as unsigned | **Webhook signature mismatch** |
| My webhook handler stopped being called | **Webhook endpoint auto-disabled** |
| A call never leaves `ringing` in my database | **A call stuck in `ringing`** |
| The agent keeps saying it does not know | **The agent answers "I don't know" too often** |
| A phone number is rejected before anything happens | **A phone number rejected at validation** |

---

## 401 — the key was not accepted

Six different problems produce a `401`, and `details.reason` tells you which. They need four different responses, so read the reason before paging anyone. Every `401` also carries `WWW-Authenticate: Bearer`.

The checks run in order, which is itself diagnostic: a malformed key never reaches a database lookup, so `malformed_api_key` and `invalid_api_key` mean genuinely different things.

### `missing_api_key`

**What you see.** `"Provide your API key as \`Authorization: Bearer amk_…\` or \`X-Api-Key\`."`

**What it means.** No key arrived. Not a wrong key — no key at all.

**How to fix.** In order of how often each is the culprit: the environment variable is empty in this environment (a secret that exists in staging and not in production, or a typo in the variable name); a proxy or gateway is stripping the `Authorization` header; the header was built as `Bearer` with no value because the variable resolved to an empty string; or the header name is misspelled. Print the *length* of your secret at startup — never the value — and you will catch the empty-variable case immediately.

Two header forms are accepted. `X-Api-Key: amk_live_…` is checked **first** and wins if both are present, which matters if a shared HTTP client is injecting one of them.

### `malformed_api_key`

**What you see.** `"That doesn't look like an Amomic-AI API key."`

**What it means.** The token does not parse. A key is exactly `amk`, an underscore, `live` or `test`, an underscore, and a secret of at least 20 characters. No lookup was attempted, so this says nothing about whether the key exists.

**How to fix.** Look at what you actually sent. Common causes: a trailing newline from `$(cat secret.txt)`; a quoted string that kept its quotes; a truncated paste; the *masked* display form `amk_live_7Fk2xQ…` copied out of the console list instead of the real secret; or a `Bearer ` prefix that got included in the variable and then prefixed again.

### `invalid_api_key`

**What you see.** `"That API key is not valid."`

**What it means.** The token parsed, and no key matching it exists. The shape was right; the secret was not.

**How to fix.** Almost always the wrong secret rather than a broken one — an old value in a secret manager, a key that was deleted from a different workspace, or a partial copy. Create or roll a key, deploy the new secret, and confirm with `GET /ping`. If `ping` works from your machine with the same string, the difference is in how your service is loading it, not in the key.

### `revoked_api_key`

**What you see.** `"That API key has been revoked."`

**What it means.** Someone revoked this key. It is permanent — there is no un-revoke.

**How to fix.** Find out who revoked it and why before creating a replacement; a revocation is usually a deliberate response to a suspected leak, and reissuing the same access without knowing that is how the same incident happens twice. Then create a new key, scoped to what the system needs, and deploy it.

Revocation takes effect **within seconds**, so this appearing mid-run is normal and not a caching bug.

### `expired_api_key`

**What you see.** `"That API key was rolled and its grace period has ended."`

**What it means.** This key was rolled more than **24 hours** ago. The roll issued a replacement and kept this one alive for a day so you could deploy without downtime. The day passed.

**How to fix.** Deploy the replacement secret — it was shown once, at the moment of the roll. If nobody saved it, roll again from the console and deploy the new one promptly this time.

Prevention: treat a roll as a deploy with a deadline, not as a task you have finished when the dialog closes. And rehearse one in a non-production environment first, so you find out whether your service reloads secrets without a restart during a rehearsal rather than during the grace window.

### `wrong_environment`

**What you see.** `"That is a test key; this environment expects a live key."` — or the reverse.

**What it means.** **The secret is correct. The host is wrong.** This is not a bad key, not a revoked key, and not a permissions problem. Keys carry an environment, hosts expect a matching one, and these two disagree.

| Key | Host | Result |
|---|---|---|
| `amk_live_…` | `services.amomic.in` | Works |
| `amk_test_…` | `services.amomic.in` | `401 wrong_environment` |
| `amk_test_…` | Development host | Works |
| `amk_live_…` | Development host | `401 wrong_environment` |

**How to fix.** Change one of the two so they agree. Which one depends on what you meant to do — that is the whole diagnosis.

The reason this deserves its own treatment is that it is almost always a *deployment* bug wearing an authentication costume. The classic sequence: base URL and API key come from two different configuration sources, someone promotes one of them, and the service comes up pointing at production with a test secret. The on-call engineer sees `401`, concludes the key is broken, rolls it, deploys the new secret, and gets the identical `401` — because the key was never the problem.

Make the pairing structural. Load the base URL and the key from the same source, and assert on startup that the key's environment segment matches the host you are about to call:

```python
import os

BASE_URL = os.environ["AMOMIC_BASE_URL"]
API_KEY = os.environ["AMOMIC_API_KEY"]

expected = "live" if BASE_URL.startswith("https://services.amomic.in") else "test"
if not API_KEY.startswith(f"amk_{expected}_"):
    raise SystemExit(f"Key environment does not match {BASE_URL} — expected an {expected} key")
```

A process that refuses to start is much cheaper than one that runs and fails every request.

::: note There is no way to get a test key against production
The environment split is the host. There is no sandbox toggle, no test-mode header, and no way to send a non-live request to the production host. If you need a safe place to experiment, use a development environment key against the development host.
:::

---

## 403 — the key is valid but not allowed

### `missing_scope`

**What you see.**

```json title="403 Forbidden"
{
  "error": {
    "code": "permission_denied",
    "message": "This API key does not have the `messages:send` scope.",
    "details": { "reason": "missing_scope", "required_scope": "messages:send" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

**What it means.** The key authenticated. It is not permitted to do this. `details.required_scope` names exactly what it needs — no guessing.

**How to fix.** Widen the key in **Developers → API keys**, or use the key that already has the scope. The change takes effect within seconds; a running job will pick it up without a restart.

The two things that produce this unexpectedly:

- **New keys are read-only.** They get `conversations:read` and `agents:read` and nothing else. A key created for "the integration" and then used to send messages hits this on its first real request.
- **Reading a ticket requires `tickets:write`.** There is no `tickets:read` scope. A key that only looks tickets up must also be able to create them — an asymmetry worth knowing when you are sizing keys.

`GET /ping` returns the key's exact scope list, which is faster than reasoning about what you think you granted. Six scopes exist in total; see [Scopes](/api/scopes).

---

## 400 — the request was wrong

Validation failures return `400` with `code: "invalid_argument"`, the message `Request validation failed.`, and `details.errors` naming the offending field. These are code defects, not transient conditions: **do not retry a `400`.**

### `empty_message`

**What you see.** `"Provide either \`text\` or \`template\`."` with `details.reason` of `empty_message`.

**What it means.** `POST /messages` received neither a `text` nor a `template`. There is nothing to send.

**How to fix.** Usually one of three: your template lookup returned nothing and you posted the result anyway; `text` was built from a variable that resolved to `""` or `null`; or a conditional built the body with `text` on one branch and `template` on the other and a third branch built neither. Guard before you post — a message with no content is a bug you can catch a function earlier, without a round trip.

### `template_variables`

**What you see.** `400` with `details.reason` of `template_variables`.

**What it means.** The variables you supplied do not fit the approved template's components. Wrong count, or the right count in the wrong place.

**How to fix.** Compare your request against the approved template in **Channels → WhatsApp → Templates**, component by component. The usual mistake is treating all variables as one list:

```json
{
  "to": "+919876543210",
  "template": {
    "name": "order_shipped",
    "language": "en_US",
    "header_variables": ["Asha"],
    "variables": ["AM-4821", "2-3 days"],
    "button_variables": ["4821"]
  }
}
```

Header, body, and button variables are **three separate fields**. A template with a variable in its header needs `header_variables`, not an extra entry at the front of `variables`.

`variables` accepts either a positional array or a numbered object — `["Asha", "AM-4821"]` and `{"1": "Asha", "2": "AM-4821"}` are the same request. It does not accept named placeholders.

### A field is too long, or the wrong shape

`details.errors` names the field and the rule. The bounds that catch people: `text` at 4096 characters, ticket `subject` at 240, ticket `description` at 8000, `purpose` at 500, `tags` at 10 items. Truncate on your side before sending — a transcript excerpt or a generated description is exactly the kind of field that fits in testing and overflows in production. Full table in [Limits and plans](/operate/limits).

### `"Provide at least one requester detail (name, email, or phone)."`

`POST /tickets` with all three requester fields null. Note the empty `details` — no `reason` string — so branch on the code and message. Synthesise something rather than failing: a name built from the conversation id is a valid requester and infinitely more useful than a failed escalation. See [Escalate a conversation to a ticket](/recipes/support-escalation).

### `"Provide an email or a phone number."`

`POST /contacts` with only a `name`. A contact with no reachable identity cannot be matched to anything, so a name-only request is refused.

---

## 404 — not found

### `template_not_found`

**What you see.** `404` with `"No approved WhatsApp template named 'order_shipped'."` and `details.reason` of `template_not_found`.

**What it means.** No **approved** template with that name exists in this workspace. Three different situations produce the identical error.

**How to fix.** Check them in this order:

1. **It is not approved yet.** Only `approved` templates can be sent. `pending` and `rejected` both produce this same `404` — the API does not distinguish them. Look at the status in the console.
2. **The name differs.** Template names are lowercase with underscores. `order_shipped` is not `Order_Shipped` and not `order-shipped`.
3. **It was approved in a different workspace.** Templates belong to the WhatsApp Business Account connected to *this* workspace. A template your colleague approved in a different workspace does not exist here.

Not retryable. Fail the job and alert — and alert on this **separately** from generic message failures, because it is a configuration incident with a specific fix, and a generic "message failed" alert buries the one line that says what to do.

### `Conversation not found.` / `Call not found.` / `Ticket not found.`

**What it means.** The id does not exist, **or** it belongs to another workspace. The two cases are deliberately indistinguishable — telling you an id exists but is not yours would confirm the existence of another workspace's data.

**How to fix.** Check the id you stored, and check which key you are using. If a call id worked yesterday and 404s today, the most likely explanation is that you switched keys and the new key belongs to a different workspace.

On the messages endpoint this is a feature: a bad `conversation_id` returns `404` rather than `200` with an empty list, so a typo fails on the first call instead of silently producing an empty report for three weeks.

---

## 409 — conflict

### `session_window_closed`

**What you see.**

```json title="409 Conflict"
{
  "error": {
    "code": "conflict",
    "message": "The 24-hour session window is closed; only approved template messages can be sent.",
    "details": { "reason": "session_window_closed" },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

**What it means.** You sent free-form `text` to a customer whose 24-hour service window is not open. The window opens when **the customer** messages you and closes 24 hours after their most recent message. WhatsApp enforces it; we report it.

**How to fix.** Send an approved template instead. Templates exist precisely to bypass this window.

The deeper fix is structural: decide per flow rather than per send. **Notification flows send a template every time** — an order shipped, a payment failed, an appointment reminder. **Reply flows send text**, inside a window the customer opened. Do not "try text and fall back to a template": you spend a round trip discovering a state you already know, and customers whose window happens to be open receive differently-worded messages from everyone else.

Note the clock is per customer and not per order. It runs from *their* last message, and each new message from them extends it. [The 24-hour window](/channels/whatsapp-window) covers the rule in full.

::: note A related 403: `suppressed`
A customer who replied `STOP` (or `unsubscribe`, `cancel`, `opt out`, and the Hindi equivalents) is suppressed for your workspace, and further sends return `403 permission_denied` with `"Recipient has opted out."` and `details.reason` of `suppressed`. This applies to **templates too** — an opt-out is not a window problem and cannot be worked around by switching message type. Record the suppression against your own customer record so you stop trying. `START` resubscribes them.
:::

### `idempotency_key_reuse`

**What you see.** `409` with `"This Idempotency-Key was already used with a different request body."`

**What it means.** The same `Idempotency-Key` arrived within 24 hours attached to a **different body**. The match is a hash of the raw request bytes.

**How to fix.** One of two causes, and they need opposite fixes.

**The body changes between attempts.** Something inside it is regenerated per attempt: a timestamp, a trace id, a "checked at" line in a description, or a serialiser producing a different key order. Fix: build the body **once**, keep the serialised string, and resend that exact string on every retry.

```python
body = json.dumps(payload)      # once
for attempt in range(4):
    response = client.post(url, headers=headers, content=body)   # the same bytes
```

**One key is being used for two different messages.** `order-4821` used for both the "shipped" and the "delivered" notification will collide on the second. Fix: one key per real-world **event**, not per order — `order-4821-shipped` and `order-4821-delivered`.

::: warning Do not retry with a fresh key to "get past" this
That is exactly the double-send the header exists to prevent. A `409` here is the system doing its job.
:::

### `identity_conflict`

**What you see.** `409` with `"Those details belong to two different contacts."` and `details.reason` of `identity_conflict`.

**What it means.** `POST /contacts` was given an email that matches one existing contact and a phone that matches a **different** one. Rather than guessing which record is right — or silently merging two customers into one — the API refuses.

**How to fix.** Decide, then send one identity at a time. Send just the email to resolve to that contact, or just the phone to resolve to the other. Then reconcile the duplicate in the console, where a human can see both records.

This usually surfaces a real data problem on your side: the same person entered twice with a typo in one address, or a phone number reassigned to a new customer. Worth investigating rather than working around.

---

## 412 — the workspace is not in a state to do this

`412 failed_precondition` means the request was well-formed and the key was fine, but something in the workspace's configuration has to change first. **These are never transient — do not retry them.** A retry loop against a `412` will run until your queue gives up, and it will not have sent anything.

### `channel_not_connected`

**What you see.** `412` with `"This workspace has no WhatsApp sender connected."`

**What it means.** No WhatsApp sender is connected. Not a bad number, not a bad message — nothing to send from.

**How to fix.** Connect a sender in the console under **Channels → WhatsApp**. Until someone does, every message will fail identically.

Alert on this separately from message failures. It is a single configuration incident that will produce thousands of identical errors, and folding it into a generic alert makes it look like a message-quality problem.

If your workspace has several senders and you need a specific one, pass `sender_id` from `GET /channels`. Omit it and the workspace default is used.

### `unsupported_channel` and `unsupported_resource`

**What you see.** `412` with a message like `"The whatsapp channel is not available on this deployment."` or `"Conversations are not available on this deployment."`, with `details.reason` of `unsupported_channel` (plus a `supported` array) or `unsupported_resource`.

**What it means.** The capability itself is not present where you are pointing. This is different from `channel_not_connected`, which means the capability exists but nothing is configured on it.

**How to fix.** Call `GET /api/v1/channels` to see what this deployment can actually do — that is what the endpoint is for. On the standard production surface these should not fire; if one does, check that you are calling the host you think you are calling.

Note that these are `412`, not `501` or `503`. That is deliberate: the request cannot succeed until a precondition changes, and it is not a transient outage you should retry into.

### Voice preconditions

`POST /calls` has several, and each names its own cause:

| `details.reason` | What it means | How to fix |
|---|---|---|
| `no_phone_number` | The workspace owns no phone number, so there is nothing to call from. | Provision a number under **Channels → Numbers**. |
| `no_agent_deployed` | The caller-ID number has no agent deployed to it. The number exists; nothing is listening on it. | Deploy an agent to that number, then retry. |
| `agent_number_mismatch` | You passed an `agent_id`, and a **different** agent is deployed to the caller-ID number. `details.deployed_agent_id` names the one that is actually there. | See below. |
| `workspace_suspended` | The workspace is suspended. | Resolve billing in the console. |
| `voice_not_configured` | Voice is not configured on this deployment. | Contact support. |

`agent_number_mismatch` deserves a note, because the mental model behind it trips people up. **The agent that speaks on an outbound call is resolved from the caller-ID number, not from `agent_id`.** Passing `agent_id` does not choose the agent — it asserts which agent you expect, and the call fails if the assertion is wrong. That is a safety feature: it stops a code change that repointed a number from silently having the wrong agent phone your customers.

So there are two fixes and they are different actions: either send the `agent_id` from `details.deployed_agent_id` (you were wrong about which agent is there), or change which agent is deployed to that number (the deployment was wrong). Alternatively, pass `from_number` explicitly to select the number whose agent you want.

Two related failures that are **not** `412`:

- **`403` with `unknown_from_number`** — the `from_number` you passed is not one of this workspace's numbers.
- **`400` with `self_dial`** — the destination is one of your own numbers. Usually a test fixture that outlived its usefulness.

---

## 429 — two different limits

Both return `code: "rate_limited"`. `details.reason` tells them apart, and they need completely different responses.

### `rate_limited` — too many requests

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 120 requests/minute exceeded for this key.",
    "details": { "reason": "rate_limited", "limit": 120, "window_seconds": 60 },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

**What it means.** More than 120 requests in one minute **on this key**. The window is a fixed wall-clock minute, not a sliding one.

**How to fix.** There is **no `Retry-After` header** and no `X-RateLimit-Reset`. Because the window is a wall-clock minute, sleep to the next minute boundary:

```python
time.sleep(60 - (time.time() % 60) + 0.25)
```

Then fix the shape of the traffic. In order of effectiveness:

1. **Give the noisy job its own key.** The limit is per key, so a backfill on its own key cannot starve your customer notifications. This is the single highest-value change.
2. **Pace rather than burst.** Roughly two requests per second keeps you under the limit continuously instead of exhausting it in the first ten seconds of every minute.
3. **Read `X-RateLimit-Remaining`.** It is on every successful response. Slow down when it gets low, rather than waiting to be rejected. Note it is absent on errors — including on the `429` itself.

### `call_concurrency` — too many live calls

```json
{
  "error": {
    "code": "rate_limited",
    "message": "This workspace already has 10 calls in progress (limit 10). Try again shortly.",
    "details": { "reason": "call_concurrency", "limit": 10 },
    "request_id": "req_01JQRS4T8XZ0AB1CD2EF3GH4",
    "correlation_id": "cor_01JQRS4T8XZ0AB1CD2EF3GH4"
  }
}
```

**What it means.** Ten calls are already ringing or in progress **across the whole workspace**, regardless of which key placed them. Slowing your request rate does not help; you need a call to end.

**How to fix.** Queue outbound calls and drain the queue as `call.ended` events arrive, keeping at most ten in flight. A loop that fires 200 calls meets this on the eleventh. If you have hung calls inflating the count, `POST /calls/{call_id}/hangup` ends one — and its `ended: false` response tells you the call was already over.

---

## Webhooks

### Signature mismatch

**What you see.** Your handler computes an HMAC that does not equal the `v1` value in `Amomic-Signature`, so every delivery is rejected. From our side, the endpoint accumulates failures and eventually disables itself.

Causes, in the order they actually occur:

**1. You verified a re-serialised body.** By far the most common. A JSON body-parser ran before your verifier, and you signed the re-serialised output. The signature covers the exact bytes we sent — compact separators, that key order, that whitespace. Read the raw body, verify, and parse only afterwards.

```javascript
// express.raw, not express.json
app.post("/hooks/amomic", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");    // exactly what was sent
  if (!verify(raw, req.get("Amomic-Signature") ?? "")) return res.status(401).end();
  const event = JSON.parse(raw);            // parse after verifying
  // …
});
```

**2. The signed string is assembled wrongly.** It is `"{t}.{body}"` — the timestamp from the header, a literal full stop, then the body. Not the body alone, not the body then the timestamp, and not a JSON object containing both.

**3. The secret is being decoded.** `whsec_…` is used as **raw UTF-8 bytes**, including the `whsec_` prefix. Do not base64-decode it, do not strip the prefix, and do not trim characters from it.

**4. The clock is wrong.** Verifiers reject a timestamp more than **5 minutes** from now. A server whose clock has drifted rejects perfectly good deliveries and, helpfully, will also fail every other TLS-adjacent thing it does. Check `date` on the box.

**5. You are comparing the wrong field.** Parse the header by splitting on `,` and then on the first `=`. Compare against `v1`. Use a constant-time comparison — a normal string equality leaks timing, and some libraries also throw on a length mismatch rather than returning false.

**6. A proxy modified the body.** Rarer, but real: a gateway that pretty-prints JSON, transcodes character encodings, or strips a trailing newline breaks the signature by definition. Test by logging the raw byte length you received and comparing it against `Content-Length`.

[Verifying signatures](/webhooks/signatures) has complete verifiers in both languages.

### The endpoint was auto-disabled

**What you see.** Your handler stops being called. No errors on your side — just silence. In the console, under **Developers → Webhooks**, the endpoint shows as disabled with `disabled_reason` reading `"Disabled automatically after 15 consecutive failed deliveries."`

**What it means.** Fifteen consecutive **events** failed delivery. Note the unit: not fifteen HTTP attempts. Each event gets up to four attempts across roughly a minute of backoff, so fifteen failed events can represent sixty requests to your endpoint.

The retry rules that got you here:

- **2xx** — success, counter resets to zero.
- **4xx that is not 429** — no retry at all. A `400` or a `401` is your endpoint saying "this request is wrong", and repeating it would be rude. This is why a broken signature check disables an endpoint quickly.
- **429, any 5xx, connection errors, timeouts** — retried, up to four attempts.

**How to fix.** Fix the handler first, then re-enable the endpoint in the console. Re-enabling resets the failure counter and clears `disabled_reason`.

::: warning Events that fired while it was disabled are gone
A disabled endpoint receives nothing, and there is no replay or redelivery endpoint. Anything you must not lose needs a reconciliation path that does not depend on webhooks — the scheduled [sync job](/recipes/sync-conversations) for conversations, `GET /calls/{call_id}` for call outcomes, `GET /tickets/{ticket_id}` for tickets.
:::

To catch this before it costs you fifteen events, alert on **silence**: a handler that has received nothing for an hour on a workspace that normally sees traffic. That alert fires whether the cause is auto-disable, a DNS change, or an expired certificate.

### Duplicate events

Delivery is **at-least-once**. The same event can arrive more than once — a timeout on our side after your handler already committed, for instance. Deduplicate on the top-level envelope `id` (`evt_…`), which is also sent as the `Amomic-Event-Id` header. Note that `data.event_id` is a *different*, internal identifier; do not key your dedupe table on it.

### An event type you do not recognise

The console's "test endpoint" button sends `{"id": "evt_test", "type": "ping", …}`, which is not one of the nine subscribable types. New event types may also be added. A handler with a `default` branch that logs and returns `200` handles both; a handler without one throws, returns 500, and starts the fifteen-event countdown.

---

## Symptoms that are not an error response

### A call stuck in `ringing`

**What you see.** Your database says a call has been `ringing` for an hour.

**What it means.** Almost never that the phone is still ringing. `POST /calls` returns `201` **as soon as the number is ringing** — that is an acknowledgement, not an outcome — and `ring_seconds` caps the actual ringing at 10 to 90 seconds, defaulting to 30. If your record still says `ringing`, your record is stale.

**How to fix.** In order:

1. **Ask the API.** `GET /calls/{call_id}` returns the current state. If it says `completed` or `failed`, your record never got updated, and the problem is on the path between us and your database.
2. **Check whether `call.ended` is arriving at all.** The usual cause of a stale record is a webhook endpoint that is failing or has been auto-disabled. Look at **Developers → Webhooks**.
3. **Check you are polling.** Code that treats the `201` as the end of the story never learns the outcome. The outcome comes from `GET /calls/{call_id}` or from `call.ended`, and one of the two must be wired up.
4. **Confirm with a hangup.** `POST /calls/{call_id}/hangup` returns `{"call_id": "…", "ended": false}` when the call was **not** ringing or in progress — which is a direct statement that the call is already over and your record is wrong.

Also make sure you are not switching exhaustively on `status`. It is typed as a plain string with no declared enum; a state you have not seen before must not throw. See [API versioning](/operate/versioning).

### The agent answers "I don't know" too often

**What you see.** The agent is polite and useless — it declines to answer things you are certain are in its knowledge base.

**What it means.** Almost always retrieval, not the model. The agent answers from what it can find, and if it cannot find the passage it will say so rather than invent one. That refusal is the desired behaviour; the problem is upstream of it.

**How to work through it:**

1. **Check the knowledge base has content.** Open the knowledge base and look at its sources. A source sitting in `error`, or one that finished with zero chunks, contributes nothing. Re-sync it and read the error text.
2. **Check the agent is using the knowledge base you think it is.** An agent can be attached to a different knowledge base than the one you have been editing.
3. **Check you published.** Edits to a knowledge base or an agent reach customers through a deployment. If the live deployment is pinned to an older version, your improvements are sitting in a draft.
4. **Ask the question the way a customer does.** Retrieval matches meaning, but a document written in internal vocabulary — product codes, team names, an acronym nobody outside uses — will not match a customer's phrasing. The fix is usually to add the customer's words to the document, not to change the agent.
5. **Look for the answer actually being absent.** A surprising share of these end with someone discovering the policy was never written down anywhere. The agent was right.

Test changes in the console before publishing, and read the transcript rather than only the final answer. [Knowledge bases](/build/knowledge) and [Testing and publishing](/build/testing) cover both loops.

### A phone number rejected at validation

**What you see.** `400` with `Request validation failed.` and `details.errors` pointing at `to`, before anything is sent or dialled.

**What it means.** The number does not match `^\+?\d+$` at 6–20 characters: digits, with an optional single leading `+`, and nothing else.

| Value | Result |
|---|---|
| `+919876543210` | Valid |
| `919876543210` | Valid |
| `+91 98765 43210` | **Rejected** — spaces |
| `+91-98765-43210` | **Rejected** — hyphens |
| `(+91) 98765 43210` | **Rejected** — parentheses |
| `+91 (0) 9876543210` | **Rejected** — parentheses and spaces |

**How to fix.** Normalise before you send, not after the first failure. Most CRMs store numbers as a human typed them:

```python
import re

def normalise(raw: str) -> str:
    digits = re.sub(r"\D", "", raw)
    if len(digits) == 10:          # a bare Indian mobile number
        digits = f"91{digits}"
    return f"+{digits}"
```

Responses always come back normalised to `+` followed by digits, so the value you get back may not be byte-identical to what you sent. Store the normalised form.

One related failure that is *not* a validation error: a destination shorter than 8 digits on `POST /calls` returns `400` with `"That destination number is too short."` and no `details.reason` — a real number that is too short to dial, rather than a badly formatted one.

---

## Still stuck

Write to `support@amomic.in` with three things:

- **The `request_id`** from the error envelope. It identifies exactly one call.
- **The time, in IST**, and the **key name**.
- **What you expected** and what happened instead.

If you cannot get a `request_id` because the request never returned one, send the `correlation_id` you set on `X-Correlation-Id`, or the timestamp and the endpoint. Check **Developers → Logs** first — the last 7 days of your own traffic are there, and the answer often is too.

For a suspected security issue, use `security@amomic.in` instead. See [Security and data](/operate/security).

## Related

::: cards

::: card Errors
[Every code and reason](/api/errors) in one reference, with the full status map.
:::

::: card Limits and plans
[What is enforced](/operate/limits) — rate limits, concurrency, and every field bound.
:::

::: card Going live
[The pre-launch checklist](/operate/going-live) — most of this page, prevented.
:::

::: card API versioning
[Forward-compatible client code](/operate/versioning) — why a `default` branch matters.
:::

:::


----------------------------------------------------------------------------
## Changelog
URL: https://docs.amomic.in/operate/changelog
----------------------------------------------------------------------------

Changes that affect people building against the public API, newest first.

## 2026-08-01 — Public API and webhooks

The public developer platform shipped. Everything below became available on `/api/v1` on this date.

**A REST API for your own systems.** Thirteen endpoints covering the operations your team already performed in the console: send a WhatsApp message, place and end an AI call, read conversations and transcripts, create and read tickets, upsert contacts, and discover which agents and channels a workspace has.

| Method | Path |
|---|---|
| `GET` | `/api/v1/ping` |
| `GET` | `/api/v1/channels` |
| `POST` | `/api/v1/messages` |
| `POST` | `/api/v1/calls` |
| `GET` | `/api/v1/calls/{call_id}` |
| `POST` | `/api/v1/calls/{call_id}/hangup` |
| `GET` | `/api/v1/conversations` |
| `GET` | `/api/v1/conversations/{conversation_id}` |
| `GET` | `/api/v1/conversations/{conversation_id}/messages` |
| `GET` | `/api/v1/agents` |
| `POST` | `/api/v1/contacts` |
| `POST` | `/api/v1/tickets` |
| `GET` | `/api/v1/tickets/{ticket_id}` |

See [API overview](/api/overview).

**API keys with scopes.** Keys took the form `amk_live_…` or `amk_test_…`, authenticated with either `Authorization: Bearer` or `X-Api-Key`, and were stored as a SHA-256 hash with the secret revealed exactly once. Six scopes — `messages:send`, `calls:write`, `conversations:read`, `contacts:write`, `tickets:write`, `agents:read` — partitioned what a key could do, and new keys were created read-only. See [Authentication](/api/authentication) and [Scopes](/api/scopes).

**Rolling with a 24-hour grace window.** Rolling a key minted a replacement with the same name, scopes, and rate limit while the previous key kept authenticating for 24 hours, so a secret could be rotated without a deploy window. Revoking stayed immediate and permanent.

**Signed webhooks.** Nine event types — `message.received`, `message.status`, `conversation.started`, `conversation.ended`, `call.started`, `call.ended`, `ticket.created`, `ticket.updated`, and `lead.created` — pushed activity to an endpoint you own, signed with a timestamped HMAC over the raw body. Delivery was at-least-once with a four-attempt retry ladder, and an endpoint that failed fifteen consecutive events was disabled with the reason recorded. See [Getting events](/webhooks/overview).

**Outbound AI calling.** `POST /api/v1/calls` had an agent place a call and hold the conversation, returning as soon as the destination was ringing. The caller-ID number selected which agent spoke, a `purpose` string shaped the opening line, and guards refused a self-dial, a number the workspace did not own, or a number with no agent deployed to it. A ceiling of ten concurrent calls per workspace applied. See [Outbound calls](/channels/outbound-calls).

**Idempotency on every request that spends money.** `POST /messages`, `POST /calls`, and `POST /tickets` honoured an `Idempotency-Key` header for 24 hours. A retry replayed the original response; the same key with a different body was refused rather than silently sending twice. See [Idempotency](/api/idempotency).

**Rate limiting.** 120 requests per key per minute, counted in a fixed one-minute window, with `X-RateLimit-Limit` and `X-RateLimit-Remaining` on successful responses. See [Rate limits](/api/rate-limits).

**A published OpenAPI document.** `GET /api/v1/openapi.json` was served without authentication and covered the public surface only.

**A per-workspace request log.** Every `/api/v1` call was recorded against the workspace that made it — method, path, status, duration, key name, error code, request id, and correlation id — kept for seven days and visible in the console under **Developers → Logs**.

```mock
{"component": "RequestLogScreen", "props": {"caption": "The request log. Failed calls are recorded alongside successful ones, which is what makes it useful."}}
```

## How this changelog is maintained

**Entries are added when something changes for integrators.** A new endpoint, a new event type, a new scope, a change in behaviour you could observe from your own code — those get a dated entry here.

**Backwards-compatible additions may ship without an entry.** A new field on a response, a new `details.reason` on an existing error, a new optional request parameter, a new value in an enum-like field. These are covered by the compatibility rules in [API versioning](/operate/versioning), and client code written to those rules absorbs them without a deploy. Not every one of them appears here.

**Breaking changes would arrive as a new API version rather than a silent change.** Removing or renaming a field, changing a type, changing the error code for an existing condition, tightening validation — none of those happen inside `/api/v1`. If one ever became necessary, it would be published as a new versioned namespace alongside this one.

This page records what has shipped. It is not a roadmap.