Welcome to the Botbiz API documentation. Our API allows you to create, manage, and integrate chatbots into your applications.
The API is organized around REST principles. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Botbiz API uses API keys for authentication. You can view and manage your API keys in the dashboard. Authentication is performed via HTTP Bearer Auth. Provide your API key as the bearer token value.
curl -X GET 'https://api.botbiz.io/v1/users' \ -H 'Authorization: Bearer YOUR_API_KEY'
Always keep your API keys secure and never share them in publicly accessible areas such as GitHub, client-side code, etc.
The Botbiz API uses conventional HTTP response codes to indicate the success or failure of an API request.
| Code | Description |
|---|---|
| 200 - OK | The request was successful. |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 403 - Forbidden | The API key doesn't have permissions to perform the request. |
| 404 - Not Found | The requested resource doesn't exist. |
| 429 - Too Many Requests | Too many requests hit the API too quickly. |
| 500 - Server Error | Something went wrong on Botbiz's end. |
{
"error": {
"code": "invalid_request",
"message": "Missing required parameter: user_id",
"status": 400
}
}
Connect a new WhatsApp Business account to your Botbiz account.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_number | string | Yes | The WhatsApp phone number to connect (with country code) |
| name | string | Yes | A name for this WhatsApp account |
{
"phone_number": "+1234567890",
"name": "Customer Support"
}
{
"id": "wha_12345",
"phone_number": "+1234567890",
"name": "Customer Support",
"status": "pending",
"qr_code_url": "https://api.botbiz.io/v1/whatsapp/accounts/wha_12345/qr-code",
"created_at": "2023-04-08T12:00:00Z"
}
Send a message to a WhatsApp contact.
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | The recipient's phone number with country code |
| type | string | Yes | Message type: 'text', 'image', 'document', etc. |
| content | string | Yes | The message content (text or media URL) |
{
"to": "+1234567890",
"type": "text",
"content": "Hello! How can we help you today?"
}
The Botbiz API has rate limits to ensure fair usage and maintain service stability. Rate limits are applied on a per-API key basis.
| Plan | Rate Limit |
|---|---|
| Free | 60 requests per minute |
| Pro | 300 requests per minute |
| Enterprise | Custom limits available |
When you exceed your rate limit, the API will return a 429 Too Many Requests error. The response will include headers that provide information about when you can retry.
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1681036800
Botbiz uses webhooks to notify your application when events happen in your account. Webhooks are particularly useful for asynchronous events like new WhatsApp messages or subscriber actions.
{
"id": "evt_12345",
"type": "whatsapp.message.received",
"created": 1681036800,
"data": {
"account_id": "wha_67890",
"message_id": "msg_54321",
"from": "+1234567890",
"type": "text",
"content": "Hello, I need help with my order.",
"timestamp": "2023-04-09T10:00:00Z"
}
}
We recommend verifying webhook signatures to ensure they were sent by Botbiz and not a third party. Each webhook request includes a signature in the X-Botbiz-Signature header.