WhatsApp API

The WhatsApp API does everything the dashboard does: send a message, read a conversation, hand one over to a person, manage templates and opt-outs, and run a broadcast. The agent answers incoming messages by default, and your code follows along by polling.

Base URL https://omnidim.io/api/v1  ·  All routes live under /api/v1/whatsapp.

Before you start

• An API key. Copy it from the dashboard. See Authentication.
• A WhatsApp number connected, in the dashboard or over the API with your Meta access token and WhatsApp Business Account id. See Connect a number below, or Connect a number in the dashboard.
• An approved template for any chat you start yourself, because the 24-hour window is closed until the customer writes to you. See Templates.
• An agent on the number if you want replies answered. See Agent replies.

To see the whole API at a glance, open the WhatsApp reference.

How a conversation flows

The routes, by task

Lists come back as { "data": [...], "has_more": true, "next_cursor": "..." }. Pass limit (1 to 100, default 20) and hand next_cursor back until it is null.

Connect a number

Connect numbers from your own WhatsApp Business Account with a Meta access token that never expires and has both WhatsApp permissions. A system user token does. Meta credentials shows where to find the token and the account id.

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/numbers/preview" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"waba_id": "YOUR_WABA_ID", "access_token": "YOUR_META_TOKEN"}'

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waba_id": "YOUR_WABA_ID",
    "access_token": "YOUR_META_TOKEN",
    "phone_number_ids": ["PHONE_NUMBER_ID"],
    "app_secret": "YOUR_META_APP_SECRET"
  }'

To change the token or the app secret later, connect the same number again with the new value. It updates the number.

Send a message

curl "https://backend.omnidim.io/api/v1/whatsapp/numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": 412,
      "phone_number": "+15551234567",
      "provider": "meta",
      "name": "Support",
      "status": "active",
      "quality_rating": "GREEN",
      "messaging_limit": "TIER_10K",
      "capabilities": {
        "types": ["text", "template", "image", "document"],
        "reply_to": true,
        "window_enforced": true,
        "delivery_status": "push",
        "template_sync": true
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d9e-0b7a-4c1e-9a55-3e2f8b1d7c40" \
  -d '{
    "phone_number_id": 412,
    "to": "+15557654321",
    "type": "text",
    "text": "Your appointment is confirmed for Friday at 10 am."
  }'

{
  "id": 98123,
  "conversation_id": "412-15557654321",
  "sender": "person",
  "type": "text",
  "text": "Your appointment is confirmed for Friday at 10 am.",
  "status": "pending",
  "timestamp": "2026-10-18T09:04:11+00:00",
  "timeline": [{ "status": "accepted", "at": "2026-10-18T09:04:11+00:00" }]
}

curl "https://backend.omnidim.io/api/v1/whatsapp/numbers/412/templates?status=approved" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": 3676,
      "name": "appointment_reminder",
      "language": "en_US",
      "category": "UTILITY",
      "status": "approved",
      "body_preview": "Hi {{1}}, your appointment is on {{2}}.",
      "fields": [
        { "key": "1", "label": "Customer name", "kind": "text", "required": true, "example": "Demo User" },
        { "key": "2", "label": "Appointment time", "kind": "text", "required": true, "example": "Friday, 10 am" }
      ],
      "buttons": []
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a2b7c1e-4d6f-4a80-9c33-5e1f2d8b6a07" \
  -d '{
    "phone_number_id": 412,
    "to": "+15557654321",
    "type": "template",
    "template": { "id": 3676, "params": { "1": "Rahul", "2": "Friday, 10 am" } }
  }'

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "phone_number_id=412" \
  -F "type=document" \
  -F "file=@invoice.pdf"

{
  "media_id": "kQ8v2mZ0pLc4xR7tN1sW3yB6dF9hJ5aE",
  "type": "document",
  "mime": "application/pdf",
  "filename": "invoice.pdf",
  "size": 48213,
  "expires_at": "2026-10-19T09:04:11+00:00"
}

Read and follow messages

There are no event webhooks, so you poll. Two ways, depending on what you need:

• Follow one chat. Call List messages with conversation_id and after set to the newest message id you already have. You get only the messages newer than it, newest first.
• Watch the whole inbox. Call List conversations with updated_since set to the time of your last call. You get every conversation with a change since then, including new messages, takes over and opt-outs.

curl "https://backend.omnidim.io/api/v1/whatsapp/messages?conversation_id=412-15557654321&after=98123" \
  -H "Authorization: Bearer YOUR_API_KEY"

To read a message's delivery, call Get a message. Its timeline walks through accepted, sent, delivered and read, and a failed message carries a failure with a reason and whether a retry is safe.

Take over and hand back

The agent owns a conversation by default and answers every incoming message. An API send does not take it over: send a message and the agent keeps replying.

To answer as a person, take the conversation over. The agent goes quiet, and customer messages are still stored and shown but not answered.

curl -X POST "https://backend.omnidim.io/api/v1/whatsapp/conversations/412-15557654321/take_over" \
  -H "Authorization: Bearer YOUR_API_KEY"

Hand back when the person is done and the agent resumes on the next message. You can also set take_over: true on a send to do both in one call.

Broadcasts

A campaign sends one approved template to a list. It is always created as a draft:

1. Create a campaign with a name, a phone_number_id and an approved template_id.
2. Add contacts, one object up to 500 at once. Each needs a phone_number. Any other key you send can fill a template parameter through variable_mapping.
3. Launch it with a new Idempotency-Key. Every pending contact is queued once.

Launch checks the plan's monthly broadcast allowance and your wallet balance. If either runs short, launch answers 402. You can pause, resume and cancel a running campaign, and read per-contact status with List contacts.

Scheduling is not offered over the API. In the dashboard the same broadcasts are described at Broadcasts.

Opt-outs

A customer stops your messages by replying STOP, or by turning marketing off in WhatsApp. Both are listed under List opt-outs.

Block a customer yourself with their number, and lift it when they ask to come back. A block the customer made themselves cannot be lifted over the API: the request answers 409 customer_opt_out, because only the customer can opt back in by messaging you.

Calling

WhatsApp calling lets a customer call the number, and the agent answers. It is off by default, only on Meta Cloud numbers, and must be included in your plan. Read the state and the checks with Get calling, then Turn it on once every blocking check passes. See WhatsApp calls for the product side.

Errors

Every error is { "error", "error_description", "code", "request_id" }, and X-Request-Id is on every response. code is the specific reason to branch on.

Related