Docs & API

How the sandbox works

• Your own workspace: Each developer gets a private workspace that starts with 50 sample messages and 50 sample calls.
• Real response shapes: A correct request returns the same response as the real API, plus "simulated": true and a hint for the next step.
• Errors that teach: A wrong request tells you which field is wrong, what was expected, what was received and a working example.
• A live lifecycle: Messages go sent → delivered (~5s) → read (~20s). Call permissions are granted after ~10s, and calls complete after ~15s with a transcript.

Get access

1. Ask for a sandbox code: Email maomel.hadi@adamhub.ai and our team creates your workspace and sends you a personal code that starts with rc_.
2. Keep it private: The code is shown once. Do not share it or put it in public code; ask us to revoke it if it leaks.
3. Send it with every request: Add the header Authorization: Bearer rc_YOUR_CODE. Base URL: https://mockapi.adamhub.ai/api/v1/whatsapp

Your first request

Like real WhatsApp, a free-text message can only be sent within 24 hours of the customer’s last message. So first pretend a customer wrote to you, then reply. Phone numbers use the international format (+964…).

# 1. A customer writes to you
curl -X POST https://mockapi.adamhub.ai/api/v1/whatsapp/simulate/inbound \
  -H "Authorization: Bearer rc_YOUR_CODE" \
  -H "Content-Type: application/json" \
  -d '{"from": "+9647701234567", "body": "Hi, are you open today?", "ai_reply": false}'

# 2. You reply
curl -X POST https://mockapi.adamhub.ai/api/v1/whatsapp/send \
  -H "Authorization: Bearer rc_YOUR_CODE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+9647701234567", "body": "Hello from Adam"}'

When something is wrong

The same request with a local number (07…) returns an error that shows how to fix it:

{
  "ok": false,
  "error": {
    "code": "phone_needs_plus",
    "message": "The real API requires the phone to start with '+'.",
    "field": "to",
    "got": "07701234567",
    "example": "+9647701234567"
  }
}

Messages

• POST /send: Send one text message: to, body.
• POST /send-bulk: Send to many numbers, as plain text or with a template and variables; creates a campaign.
• POST /simulate/inbound: Sandbox only: pretend a customer wrote to you (from, body), with an optional AI reply.
• GET /conversations: List conversations; GET /conversations/{id}/messages for the messages.
• GET /templates: The message templates you can use.
• GET /campaigns: Bulk campaigns and their delivery numbers; GET /campaigns/{id} for one.
• GET /me · GET /balance: Your workspace, and how many messages and calls you have left.

Calls

A WhatsApp call needs the customer’s permission first, exactly like the real flow:

# 1. Ask the customer for permission (granted after ~10s in the sandbox)
POST /api/v1/whatsapp/call-permissions/request   {"customer_phone": "+9647701234567"}

# 2. Check it
GET  /api/v1/whatsapp/call-permissions/+9647701234567

# 3. Call (ringing -> completed after ~15s)
POST /api/v1/whatsapp/calls/initiate              {"customer_phone": "+9647701234567"}

# 4. Read the result
GET  /api/v1/whatsapp/calls/{call_id}/transcript

• GET /calls: Call history; filter with ?direction=inbound or outbound.
• GET /calls/{id}/recording-url: The recording link of a completed call. The sandbox returns url: null; the real API returns a short-lived link.
• PATCH /calls/{id}/outcome: Mark the result: order_placed, question_answered, callback_requested, complaint, no_answer or other.
• POST /call-permissions/refresh: Re-read the current permission status for a customer.

Integrations available today

• WhatsApp Business Platform: Official Meta integration through Embedded Signup, for messages and calls.
• Instagram & Messenger: Messages through Meta’s official APIs.

Frequently asked questions

Can the sandbox send real WhatsApp messages?

No. Nothing reaches Meta or a real customer; everything is simulated in your own workspace.

Is the production API open?

Not publicly yet. When your integration works in the sandbox, contact us to move it to your real Adam account.

Related pages

• Knowledge base: Step-by-step guides for Adam Hub: create your account, set up your agent, connect a phone number or WhatsApp, launch a campaign and read your analytics.
• WhatsApp, Instagram & Messenger: Adam replies to WhatsApp, Instagram and Messenger messages in Iraqi Arabic from one inbox. Adam Hub is a verified Meta Tech Provider.
• Support: How to reach Adam Hub support: email, in-dashboard help and booking a call with the team in Baghdad. and what to include so we can help faster.