Agent bots and the API channel

Open in

Conversa Labs

Last updated on Jul 16, 2026

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.

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.

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.
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.
Configure the channel webhook_url to receive outgoing messages: when an agent replies in the conversation, the payload is delivered to your endpoint.
(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.

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

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.

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.

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.