Getting Started with the MotherBot REST API: A Developer's Guide

Send WhatsApp messages, manage contacts, and trigger campaigns programmatically. Here's how to authenticate, make your first request, and explore the full MotherBot REST API — Postman collection included.

Everything in MotherBot — chatbots, campaigns, the team inbox — is built for a no-code interface first. But if you're integrating WhatsApp into your own systems, the REST API gives you the same capabilities programmatically: send messages, manage contacts and segments, run campaigns, issue coupons, and receive real-time events over webhooks.

Here's how to get from zero to your first authenticated request.

Base URL and authentication

Every endpoint lives under one base URL and takes a Bearer key:

https://motherbot.io/api/v1
Authorization: Bearer motherbot_<your_api_key>

Create a key from Settings → API Keys in your dashboard. The raw key is shown exactly once, at creation — only a SHA-256 hash is stored afterwards, so there's no way to recover it later. Keys are scoped to a single organization and cannot reach another org's data. If a key ever leaks, revoke and reissue from the same screen.

Make your first request

A minimal request to list your contacts:

curl https://motherbot.io/api/v1/contacts \
  -H "Authorization: Bearer motherbot_<your_api_key>"

Every response is JSON. Successful responses carry success: true and a data payload; list endpoints add a pagination object alongside it.

What you can do with the API

• Send individual and template messages
• Manage contacts, custom fields, and segments
• Run campaigns and drip sequences
• Issue and redeem coupons that work at your Shopify or WooCommerce checkout
• Create trackable links, manage deals and products
• Upload media and register webhooks
• Watch number health and pull plan usage
• Read message history and analytics

Import the Postman collection

Rather than writing requests from scratch, import the full collection — every endpoint, plus a request for every webhook event, with example bodies and saved responses already filled in:

Collection   https://motherbot.io/postman/motherbot-api.postman_collection.json
Environment  https://motherbot.io/postman/motherbot-api.postman_environment.json

In Postman: Import → Link, paste the collection URL, then repeat for the environment. Select the environment, set apiKey, and every request in the collection inherits it — you only set it once. Run Usage & Plan first; it tells you which folders your plan can actually use before a 403 does.

Rate limits

Enforced per API key, per minute, by plan:

| Plan | Limit |

|---|---|

| Starter | 60 req/min |

| Growth | 300 req/min |

| Enterprise | 1,200 req/min |

Bulk-sending endpoints (POST /messages/bulk, POST /campaigns/send) each draw from a separate bucket set to a tenth of your plan limit, so a broadcast can't exhaust the allowance your regular reads depend on. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceeding the limit returns a 429.

Handling errors and plan limits

Two different error codes mean two different things:

• 403 `feature_not_available` — the feature isn't on your plan at all. Stop calling the endpoint; the account needs to upgrade.
• 402 `plan_limit_reached` — the feature is available, but the quota is full. The response body includes the exact numbers (limit, current) so your integration can report precisely what ran out.

Call GET /usage before a long-running job — it returns every quota, how much is used, and every feature flag, so you can size a batch instead of discovering the ceiling halfway through an import.

Webhooks

Configure a webhook endpoint under Settings → Webhooks to receive real-time events — message_received, message_delivered, campaign_completed, payment_confirmed, contact_created, and more — as signed HTTPS POST requests. Verify each payload with the HMAC-SHA256 signature in the X-MotherBot-Signature header before trusting it.

Where to go next

The full [API Reference](/docs/api) documents every endpoint, error code, and webhook payload in detail. Fork the Postman collection, send your first authenticated request, and you'll have a working integration well before you need most of what's documented there.