Skip to main content

Quickstart

Send your first WhatsApp message in 5 minutes. This guide assumes you have a Mojeeb account on the Professional plan or higher and at least one connected WhatsApp number.

Step 1 — How do I get an API key?​

  1. Sign in to the Mojeeb dashboard
  2. Open the API Keys page from the sidebar
  3. Click Create key, give it a name, and confirm
  4. Copy the key — it looks like mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5

The secret is shown once. Lose it and you must revoke and create a new one. Store it in your secret manager, never in source code.

Step 2 — How do I find my agent ID and from-phone?​

The same API Keys page lists every agent in your organization under "Your agent IDs" — click any ID to copy it to the clipboard. The agent_id is a UUID like 12345678-1234-1234-1234-123456789012.

For the from phone, go to Connections on the agent and copy any active WhatsApp number — it looks like +15557654321. If you supply a from number that doesn't match an active connection, the API tells you exactly which numbers will work in the error response — no guessing required.

Step 3 — How do I send my first template?​

Templates are pre-approved by Meta and can be sent at any time, even outside the customer's 24-hour service window. Free-form text is restricted to inside the window and is covered separately under Send Message.

curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "arabic_signup_message",
      "language": "ar"
    }
  }'

A successful response — HTTP 202 Accepted:

{
  "id":                  "01c45011-d803-4eb0-a762-3228a4c392f3",
  "status":              "queued",
  "agent_id":            "12345678-1234-1234-1234-123456789012",
  "to":                  "+15551234567",
  "type":                "template",
  "platform_message_id": null,
  "created_at":          "2026-04-30T09:18:31Z",
  "sent_at":             null,
  "failed_at":           null
}

The id is your handle for status polling. The 202 means the message is queued — actual delivery happens asynchronously through Meta's WhatsApp Business Cloud API.

Step 4 — How do I check delivery status?​

curl https://api.mojeeb.app/v1/whatsapp/messages/01c45011-d803-4eb0-a762-3228a4c392f3 \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

Status moves through queued → sent → delivered → read (or transitions to failed). Once Meta accepts the message, platform_message_id populates with Meta's wamid for cross-referencing in their logs. Full status taxonomy is on Get Message Status.

What's next?​

  • Authentication — full key format, scopes, per-agent restrictions
  • Idempotency — make retries safe with Idempotency-Key
  • Errors — every error code with HTTP status and meaning
  • Rate Limits — default 60 req/min/key and how to handle 429
  • API Reference — full machine-readable contract

Common questions​

What if my from number doesn't match any connection?​

You'll get a 422 from_phone_not_found_for_agent with available_phones listing every active WhatsApp number on the agent. Fix and retry — no second roundtrip needed to discover what was valid.

Why didn't my message arrive?​

The 202 means Mojeeb queued the send. Delivery can fail at Meta's side for reasons we can't predict (recipient blocked the business number, recipient outside the 24h window for free-form text, template not approved in the recipient's region). Poll GET /v1/whatsapp/messages/{id} — status: "failed" with failed_at populated tells you the send was rejected downstream.

Can I send the same message twice safely?​

Yes — add an Idempotency-Key header. The first send returns 202; an identical retry with the same key replays the exact same response. See Idempotency.