BotInbox API Reference
Build powerful integrations with the BotInbox REST API. Manage conversations, contacts, messages, and more programmatically.
Authentication
How to authenticate your API requests
All API requests must include an API key. Two header formats are accepted:
- X-API-Key: bi_... (recommended)
- Authorization: Bearer bi_... (standard OAuth2 style)
Create API keys from the Manage > API Playground page. Keys are prefixed bi_ and shown only once on creation — store them securely.
Permission scopes (set per key):
- read — list and retrieve resources (GET endpoints)
- write — create and update resources (POST, PATCH)
- delete — remove resources (DELETE)
- admin — implies all of the above
Requests using a key that lacks the required scope return 403 Forbidden with a message naming the missing permission.
Example request:
`bash
curl https://your-domain.com/api/v1/conversations \
-H "X-API-Key: bi_your_api_key_here"
`
Errors:
- 401 — missing, invalid, expired, or inactive key
- 403 — key lacks required permission, or org is suspended
- 404 — resource not found in your org
- 400 — invalid request body or query
curl -X GET "https://your-domain.com/api/v1/conversations" \ -H "X-API-Key: bi_your_api_key_here" \ -H "Content-Type: application/json"
Conversations
Create, list, and manage conversations
Messages
Send and retrieve messages
Contacts
Manage contacts and customer profiles
Labels
Manage conversation labels and tags
Users
List agents and team members
Channels
List communication channels
Webhooks
Subscribe to real-time events
Webhooks allow you to receive real-time HTTP POST notifications when events occur in BotInbox. Configure webhooks from Manage > Webhooks.
Headers on every delivery:
- X-BotInbox-Event — the event type (e.g. message.created)
- X-BotInbox-Signature — HMAC-SHA256 of the raw request body, signed with your webhook secret
- Content-Type: application/json
Payload shape:
`json
{
"event": "message.created",
"data": { /* resource payload */ },
"timestamp": "2025-01-15T10:30:00.000Z"
}
`
Verifying signatures (Node.js):
`js
import crypto from "crypto"
function verify(req, secret) {
const sig = req.headers["x-botinbox-signature"]
const expected = crypto
.createHmac("sha256", secret)
.update(req.rawBody)
.digest("hex")
return crypto.timingSafeEqual(
Buffer.from(sig),
Buffer.from(expected)
)
}
`
Retry behavior: BotInbox retries up to 3 times on transport failures and 5xx / 408 / 429 responses, with delays of 0s, 3s, and 10s. 4xx responses (other than 408 / 429) are treated as permanent rejections and not retried. The final error is stored on the webhook record.
Available event types:
- conversation.created / conversation.updated / conversation.closed / conversation.assigned
- message.created / message.updated
- contact.created / contact.updated / contact.deleted
- channel.created / channel.updated
- * (subscribe to all events)