Developer Resources
What it is
BotBat is an API-first platform, meaning every feature available in the console is also accessible through a comprehensive REST API. Whether you are building custom integrations, automating campaign workflows, or syncing contact data with third-party tools, the Developer Resources section serves as the centralized hub for all integration-related management. From here you can create and rotate API keys, inspect rate limits, configure webhooks, download SDKs, and switch between sandbox and production environments.
The platform follows RESTful conventions throughout, with JSON request and response bodies, Bearer token authentication, cursor-based pagination, and standardized error codes. Every API key you generate is scoped to specific permissions, ensuring that each integration only has access to the resources it truly needs. This design supports both simple single-purpose integrations (such as a read-only analytics feed) and complex multi-system architectures where several services interact with BotBat simultaneously.
The Developer dashboard also provides real-time visibility into how your integrations are performing. Usage charts, error rate breakdowns, and rate limit consumption metrics let you proactively identify and resolve issues before they affect your business operations. Combined with the sandbox environment for risk-free testing, the Developer Resources section gives your engineering team everything required to build, test, and maintain robust integrations with confidence.
When to use
| Scenario | Description |
|---|---|
| Building a custom integration | Connect BotBat to your CRM, ERP, e-commerce platform, or internal tools using the REST API to programmatically manage contacts, send messages, and trigger campaigns. |
| Generating and managing API keys | Create API keys with specific scopes (e.g., read-only for analytics, write for messaging) so each integration has the minimum permissions it needs. |
| Setting up event-driven workflows | Configure webhooks to receive real-time notifications when events occur in BotBat (message delivered, contact created, campaign completed) and trigger downstream actions. |
| Testing before going live | Use the sandbox environment to validate API calls, webhook deliveries, and message flows without affecting real contacts or consuming messaging credits. |
| Monitoring API usage and rate limits | Check your API consumption against per-key and per-organization rate limits to ensure your integrations stay within bounds and avoid service disruptions. |
| Rotating credentials | Periodically rotate API keys or immediately revoke compromised keys. The dashboard supports creating a replacement key before revoking the old one for zero-downtime rotation. |
Steps
1. Open Developer Resources
Navigate to Developer in the main sidebar. The dashboard displays a summary of your active API keys, configured webhook endpoints, and a usage chart showing recent API call volume.
2. Create an API key
Click Create API Key. In the creation form, provide a descriptive name for the key (e.g., "CRM Integration" or "Analytics Dashboard"), then select the scopes the key should have. Available scopes include contacts:read, contacts:write, messages:send, campaigns:read, campaigns:write, webhooks:manage, and more. Each scope corresponds to a specific set of API endpoints. Click Generate to create the key.
Once generated, the key value is displayed exactly once. Copy it immediately and store it in a secure location such as a secrets manager or encrypted vault. The key cannot be retrieved after you close the dialog.
3. Review rate limits
The Rate Limits section shows your per-key and per-organization limits. These limits are expressed as requests per second and requests per minute, and they vary by plan tier. Enterprise plans have significantly higher thresholds. The table below summarizes the default limits by plan.
| Plan | Requests per second (per key) | Requests per minute (per org) |
|---|---|---|
| Starter | 5 | 300 |
| Professional | 20 | 1,200 |
| Enterprise | 50 | 5,000 |
When a rate limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.
4. Set up a webhook
Go to the Webhooks section and click Add Endpoint. Enter your server's HTTPS URL, select the event types you want to receive (such as message.delivered, contact.created, or campaign.completed), and save. BotBat generates a signing secret that your server uses to verify the authenticity of incoming payloads. For full details on webhook configuration, see the Webhooks documentation.
5. Explore the API documentation
Click API Reference to open the interactive documentation. Endpoints are organized by module: Campaigns, Contacts, Messages, Conversations, Templates, and Webhooks. Each endpoint includes the HTTP method, path, required and optional parameters, request body schema, response schema, and example payloads. The built-in "Try It" feature lets you execute API calls directly from the browser using your sandbox key.
6. Download an SDK
In the SDKs section, download client libraries for your preferred language. Each SDK wraps the REST API with idiomatic methods, handles authentication, implements automatic retries, and includes TypeScript/type definitions where applicable.
| Language | Package Manager | Install Command |
|---|---|---|
| JavaScript / Node.js | npm | npm install @botbat/sdk |
| Python | pip | pip install botbat |
| PHP | Composer | composer require botbat/sdk |
| Java | Maven | Add com.botbat:sdk dependency |
7. Activate the sandbox
Toggle to Sandbox Mode in the Developer dashboard. In sandbox mode, API calls execute against isolated test data, messages are simulated (not actually delivered to real recipients), and webhook events are generated with test payloads. This allows you to develop and test your entire integration end-to-end without any risk of affecting production data or consuming messaging credits.
The sandbox also includes an Event Simulator that lets you manually trigger specific webhook events on demand. This is especially useful for testing edge cases such as message delivery failures, rate limit events, or contact merge scenarios that are difficult to reproduce organically.
8. Monitor API usage
The Usage dashboard presents your API call volume over time, broken down by endpoint and key. It highlights rate limit violations, error spikes, and latency trends. Use this data to identify integrations that may need optimization, keys that should be retired, or capacity issues that require a plan upgrade.
Common pitfalls
| Pitfall | Why it matters | How to avoid it |
|---|---|---|
| Exposing API keys in client-side code | Keys embedded in frontend JavaScript, mobile apps, or public repositories can be stolen and abused. | Use API keys only in server-side code. Store them in environment variables or a secrets manager. |
| Creating a single key with all scopes | A compromised all-access key gives an attacker full control over your BotBat account. | Follow the principle of least privilege. Create separate keys per integration, each with only the scopes it needs. |
| Not handling rate limit responses | Ignoring HTTP 429 responses causes request failures and can lead to temporary IP blocks. | Implement backoff logic that respects the Retry-After header on 429 responses. |
| Skipping the sandbox for testing | Testing against production sends real messages, creates real contacts, and consumes real credits. | Always validate integrations in sandbox mode first before switching to production. |
| Forgetting to rotate API keys | Long-lived keys accumulate risk over time, especially if team members who had access have left the organization. | Rotate keys every 90 days. Use the zero-downtime rotation workflow: create the new key, update your integration, then revoke the old key. |
Use the sandbox environment's "Event Simulator" to generate specific webhook events on demand. This lets you test edge cases (like message delivery failures or rate limit events) that are difficult to trigger organically.
- Developer Dashboard
- API Keys
- Create API Key
- API Key Scopes
- Rate Limits
- Webhooks
- SDKs
- Sandbox Mode
- Usage Dashboard