Skip to main content

Quickstart

Send your first WhatsApp message in 5 minutes. This guide assumes you have a Mojeeb account on the Starter or Professional plan 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. Your key can also tell you: GET /v1/me confirms the key works, and GET /v1/agents lists the agents it can act on (see Your Key and Agents).

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.

Not sure of a template's exact name or language? List the number's templates first: each one comes with its status and what to fill in, and only approved templates are delivered. See List WhatsApp Templates.

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 is HTTP 202 Accepted with the message object, starting in status: queued. Every field is in the Send WhatsApp template reference.

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
  • Your Key and Agents — the first of the agent guides: settings, contacts and leads, knowledge, channels, team, analytics and usage
  • 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.

Will Mojeeb stop me from sending a template that isn't approved?​

No. Before queuing, Mojeeb checks that the template's name and language exist on the number, whatever their status. A template that is still pending, or was rejected, is accepted with 202 and then fails at Meta. List the number's templates first and send only those with status: approved; see List WhatsApp Templates.

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 original response. See Idempotency.