API Reference
What it is
The BotBat API Reference is the complete technical documentation for the REST API that powers every feature of the platform. It provides detailed specifications for authentication using Bearer tokens, base URL and versioning conventions, request and response formats, cursor-based pagination, standardized error codes, and per-endpoint rate limits. Every operation you can perform in the BotBat console has a corresponding API endpoint, making it possible to fully automate your messaging, contact management, and campaign workflows.
The API follows RESTful design principles. Resources are identified by URL paths, standard HTTP methods indicate the operation (GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing), and all data exchange uses JSON. The versioning strategy is URL-based: the current version is v1, and future versions will use /v2, /v3, etc., ensuring backward compatibility for existing integrations while allowing the API to evolve.
The interactive API Reference, accessible from the Developer section of the BotBat console, goes beyond static documentation. It includes a built-in "Try It" panel where you can construct requests, execute them against the sandbox environment, and inspect the full response including headers, status codes, and JSON bodies. This makes it the fastest way to explore the API and understand how each endpoint behaves before writing any integration code.
When to use
| Scenario | Description |
|---|---|
| Starting a new API integration | Begin here to understand the base URL, authentication mechanism, and common patterns before writing any code. |
| Looking up a specific endpoint | Find the exact request format, required parameters, optional parameters, and expected response shape for any API operation. |
| Debugging an error response | Reference the error codes table to understand what a specific HTTP status code and error body mean and how to resolve the issue. |
| Implementing pagination | Learn how to use cursor-based pagination to efficiently iterate through large result sets without missing or duplicating records. |
| Understanding rate limits per endpoint | Check the rate limit for a specific endpoint to design your integration's request frequency appropriately. |
| Onboarding new developers | Share the API Reference with new team members so they can self-serve when building or maintaining integrations. |
Steps
1. Identify the base URL
All API requests use the base URL https://api.botbat.com/v1. The version number is included in the URL path. When a new version is released, existing v1 endpoints will continue to function for a documented deprecation period, giving you time to migrate.
2. Authenticate your requests
Include your API key as a Bearer token in the Authorization header of every request. The format is Authorization: Bearer YOUR_API_KEY. Requests without a valid token receive an HTTP 401 response. API keys are created and managed in the Developer dashboard. Each key is scoped to specific permissions, so ensure your key has the required scopes for the endpoints you intend to call.
3. Set request headers
All requests must include Content-Type: application/json and Accept: application/json. Request bodies are JSON-encoded, and all responses are returned as JSON. Binary uploads (such as CSV imports) use multipart/form-data instead.
4. Make a request
Construct your HTTP request with the appropriate method (GET, POST, PUT, PATCH, DELETE), the endpoint path, query parameters for filtering and pagination, and a JSON request body for create and update operations. The interactive documentation provides copy-ready code snippets in cURL, JavaScript, Python, and PHP for every endpoint.
5. Use the Try It panel
The Try It panel in the interactive documentation lets you execute requests directly from the browser. Select an endpoint, fill in the parameters and request body, attach your sandbox API key, and click Send. The panel displays the full response including HTTP status, response headers, and the JSON body.
This is the fastest way to explore unfamiliar endpoints and verify that your request payloads are correctly structured before integrating them into your codebase.
6. Handle pagination
List endpoints return paginated results. Each response includes a data array containing the current page of results and a cursor field. To retrieve the next page, include ?cursor=RETURNED_CURSOR as a query parameter in your subsequent request. When the cursor field is null, you have reached the end of the result set. The default page size is 25 items, and you can adjust it with the limit query parameter (maximum 100).
7. Parse successful responses
Successful responses return HTTP 200 for read and update operations, or HTTP 201 for creation operations. The response body contains the requested data. For single-resource endpoints, the data is returned directly. For list endpoints, the response includes data (an array of resources), cursor (for pagination), and total (the total count of matching resources).
8. Handle errors
Error responses include an HTTP status code, an error object with a machine-readable code, a human-readable message, and optionally a details array for validation errors. Always check the status code first, then parse the error body for specifics.
Key endpoints
Campaigns API
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/campaigns | List campaigns, filterable by status and date range |
| POST | /v1/campaigns | Create a new campaign |
| GET | /v1/campaigns/:id | Get campaign details |
| PUT | /v1/campaigns/:id | Update a campaign |
| DELETE | /v1/campaigns/:id | Delete a draft campaign |
| POST | /v1/campaigns/:id/send | Send or schedule a campaign |
The Campaigns API lets you create, manage, and send campaigns programmatically. You can filter campaign lists by status (draft, scheduled, sending, completed, failed) and by date range. The POST /send endpoint accepts optional scheduling parameters; omitting them sends the campaign immediately.
Contacts API
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/contacts | List contacts, filterable by segment, tag, and date |
| POST | /v1/contacts | Create a contact |
| GET | /v1/contacts/:id | Get contact details |
| PUT | /v1/contacts/:id | Update a contact |
| DELETE | /v1/contacts/:id | Delete a contact |
| GET | /v1/contacts/search?q= | Search contacts by name, email, or phone |
| POST | /v1/contacts/import | Bulk import contacts via CSV upload |
The Contacts API supports full CRUD operations as well as search and bulk import. The search endpoint performs a fuzzy match across name, email, and phone fields. The import endpoint accepts a CSV file via multipart/form-data and returns a job ID that you can poll for completion status.
Messages API
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/messages/send | Send a message to a contact |
| GET | /v1/messages/:id | Get message details and delivery status |
The Messages API handles individual message sending and status tracking. The send endpoint requires a contact_id, channel (e.g., whatsapp, sms), and either a template_id or a body for freeform messages. The status endpoint returns the full delivery lifecycle: queued, sent, delivered, read, or failed.
Conversations API
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/conversations | List conversations, filterable by status and assignee |
| GET | /v1/conversations/:id | Get conversation details with message history |
| POST | /v1/conversations/:id/assign | Assign a conversation to an agent |
| POST | /v1/conversations/:id/resolve | Resolve a conversation |
Templates API
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/templates | List message templates |
| POST | /v1/templates | Create a template |
| GET | /v1/templates/:id | Get template details |
| PUT | /v1/templates/:id | Update a template |
| DELETE | /v1/templates/:id | Delete a template |
| POST | /v1/templates/:id/submit | Submit a template for WhatsApp approval |
Webhooks API
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/webhooks | List webhook endpoints |
| POST | /v1/webhooks | Create a webhook endpoint |
| GET | /v1/webhooks/:id | Get webhook details |
| PUT | /v1/webhooks/:id | Update a webhook endpoint |
| DELETE | /v1/webhooks/:id | Delete a webhook endpoint |
Common error codes
| HTTP Status | Error Code | Description | Resolution |
|---|---|---|---|
| 400 | invalid_request | Malformed request body or missing required fields | Check the request body structure against the endpoint schema. |
| 401 | unauthorized | Missing or invalid API key | Verify that the Authorization header contains a valid Bearer token. |
| 403 | forbidden | API key lacks the required scope for this endpoint | Update the key's scopes in the Developer dashboard or use a different key. |
| 404 | not_found | The requested resource does not exist | Confirm the resource ID is correct and belongs to your organization. |
| 409 | conflict | Resource state conflict (e.g., sending an already-sent campaign) | Check the current state of the resource before attempting the operation. |
| 422 | validation_error | Request body fails validation; check the details array | Fix the fields listed in the details array and retry. |
| 429 | rate_limited | Rate limit exceeded | Wait for the number of seconds specified in the Retry-After header, then retry. |
| 500 | internal_error | Server error | Retry with exponential backoff and jitter, up to 3 to 5 attempts. |
Common pitfalls
| Pitfall | Impact | Recommendation |
|---|---|---|
| Using API keys without sufficient scopes | Requests fail with 403, blocking your integration. | Check required scopes in the endpoint documentation before generating a key. |
| Ignoring cursor pagination | Only the first page of results is returned, leading to incomplete data. | Always paginate until cursor is null. |
| Not validating request bodies before sending | Unnecessary round trips due to 422 errors. | Validate payloads client-side using the schemas from the API docs. |
| Hardcoding the API version | Makes version upgrades painful and error-prone. | Store the API version in a configuration variable so upgrades require only a config change. |
| Not implementing retry logic for 500 errors | Transient failures cause permanent data loss or missed operations. | Implement exponential backoff with jitter, retrying 3 to 5 times for 500-level responses. |
Use the interactive "Try It" feature in the API Reference documentation to test endpoints directly from your browser with your sandbox API key. This is the fastest way to understand request/response shapes before writing integration code.
- API Reference
- Endpoint Detail
- Try It Panel
- Pagination
- Error Codes
- Campaigns API
- Contacts API
- Messages API
- Conversations API
- Templates API
- Webhooks API