# Quickstart

> Send your first WhatsApp message via the Mojeeb Public API in 5 minutes — get an API key, send a template with curl, and verify delivery.

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](https://app.mojeeb.app)
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](./agents/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](./whatsapp/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](./whatsapp/list-templates).

```bash
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](./api-reference/send-whats-app-template).

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?

```bash
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](./whatsapp/message-status).

## What's next?

- [Authentication](./authentication) — full key format, scopes, per-agent restrictions
- [Idempotency](./idempotency) — make retries safe with `Idempotency-Key`
- [Errors](./errors) — every error code with HTTP status and meaning
- [Rate Limits](./rate-limits) — default 60 req/min/key and how to handle 429
- [Your Key and Agents](./agents/key-and-agents) — the first of the agent guides: settings, contacts and leads, knowledge, channels, team, analytics and usage
- [API Reference](./api-reference/mojeeb-public-api) — 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](./whatsapp/list-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](./idempotency).