## Overview

Conversa Labs offers two complementary extension points for developers:

- **API channel**: a **programmable inbox**. Instead of a ready-made channel (WhatsApp, email and
  so on), you create an inbox of type API and connect your own application. Inbound messages arrive
  through the REST API and agent replies are delivered to your `webhook_url`.
- **Agent bot**: a **webhook bot** (`bot_type: webhook`). It is assigned to an inbox (of any
  channel) and receives the conversation/message events at its `outgoing_url`. The bot processes the
  event and can reply by calling the API back with its access token.

When to use each:

- Use the **API channel** when you need a custom channel that the platform does not offer natively.
- Use an **agent bot** when you want to automate replies (triage, auto-answers, AI) before or
  alongside human agents, on any inbox.

The two can be combined: an API inbox that also has an agent bot assigned to it.

## Prerequisites

- **Administrator** permission on the account (creating inboxes and agent bots is admin-only).
- A reachable **HTTPS endpoint** to receive webhooks (the channel `webhook_url` and/or the bot
  `outgoing_url`).
- A valid **access token** to authenticate REST API calls.

## Step by step

1. **Create an API inbox**: go to **Settings → Inboxes → Add → API**. Provide a name and,
   optionally, the `webhook_url`. After creating it, note the channel **identifier** that was
   generated.
2. **Send an inbound message**: create/open a conversation in that inbox and post the customer's
   message via the API (`POST .../conversations/:id/messages`), authenticating with the access token.
3. **Configure the channel `webhook_url`** to receive outgoing messages: when an agent replies in
   the conversation, the payload is delivered to your endpoint.
4. **(Optional) Create an agent bot**: under **Settings → AI agents/Agent bots**, provide a name,
   description and the `outgoing_url` (`bot_type` = webhook). Then **assign the bot to the inbox** so
   it starts receiving that inbox's events.

## Settings & options

- **Bot access token**: used by the bot to call the API back (create replies, react, update status).
  It can be regenerated via **reset_access_token**.
- **Bot secret**: used to sign/verify the webhook payload sent to the `outgoing_url`. It can be
  regenerated via **reset_secret**.
- **Channel HMAC verification** (`hmac_token`, `hmac_mandatory`): validates the contact's identity.
  With `hmac_mandatory` enabled, contacts are only accepted with a valid identifier hash, computed
  from the `hmac_token`.
- **Message status update**: allowed **only on API inboxes** (for example, marking delivered/read or
  recording a send error).
- **Bot payload** (`webhook_data`): identifies the bot in the event with
  `{ id, name, type: "agent_bot" }`.

## Use cases

- **Custom channel**: connect your own application (an internal app, a marketplace, a proprietary
  channel) as an inbox via the API.
- **Automated replies**: an agent bot that does the initial triage, answers frequent questions and
  only then hands the conversation over to a human agent.

## Tips, limits & best practices

- Always **verify the HMAC signature** of the webhook (channel and/or bot secret) before processing
  the payload.
- Ensure **idempotency**: when creating inbound messages, use a unique `source_id` to deduplicate
  redeliveries.
- Define a clear **handoff point** from the bot to the human (for example, assign the conversation
  to an agent/team and stop replying with the bot).
- Treat tokens and secrets as credentials: never expose them in the front-end.

## Troubleshooting

- **401/403**: invalid, expired or unauthorized access token.
- **The bot does not receive events**: confirm the `outgoing_url` is correct and reachable, and that
  the bot is assigned to the inbox.
- **Invalid HMAC**: the identifier hash does not match the `hmac_token`; recompute the signature and
  check the field order/encoding.

## See also

- [REST API, tokens and webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-en)
- [Events by module](/hc/ajuda/articles/api-developers-eventos-por-modulo-en)
- [API channel: the structured event contract](/hc/ajuda/articles/api-developers-api-channel-contract-en)