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:

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 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.