MCP is live.Set upAsk the community
OmniDimension
Dashboard
DocumentationAPI referenceSDKsMCP
WhatsApp

Send a message

Send one message through phone_number_id to a customer, in a text, a template, an image or a document. Set type and the matching field.

Set up WhatsApp first. Connect a WhatsApp number in the dashboard or with Connect numbers. Included on every paid plan. See plans.

POST/whatsapp/messages
Body
8 fields
·

The number to send from.

The customer's number in international format, such as +15551234567.

Required when type is text.

Required when type is template.

Id*
Params
curl -X POST 'https://backend.omnidim.io/api/v1/whatsapp/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "take_over": false
}'
Example response
synthetic
{
  "id": 0,
  "conversation_id": "string",
  "wa_message_id": "string",
  "sender": "customer",
  "type": "string",
  "text": "string",
  "caption": "string",
  "profile_name": "string",
  "sent_by_workflow": "string",
  "timestamp": "string",
  "status": "pending",
  "reply_to": {
    "wa_message_id": "string",
    "preview": "string",
    "sender": "customer"
  },
  "reactions": [
    {
      "emoji": "string",
      "sender": "customer",
      "timestamp": "string"
    }
  ],
  "media": {
    "mime": "string",
    "filename": "string",
    "size": 0,
    "fetch_status": "done"
  },
  "voice": {
    "duration_seconds": 0,
    "transcript": "string"
  },
  "location": {
    "lat": 0,
    "lng": 0,
    "name": "string",
    "address": "string",
    "map_url": "string"
  },
  "contacts": [
    {
      "name": "string",
      "phones": [
        "string"
      ]
    }
  ],
  "interactive": {
    "title": "string"
  },
  "template": {
    "id": 0,
    "name": "string"
  },
  "failure": {
    "code": "string",
    "reason": "string",
    "retryable": false
  },
  "charged": {
    "amount": 0,
    "currency": "string"
  },
  "timeline": [
    {
      "status": "received",
      "at": "string"
    }
  ]
}

Authorization

BearerAuth
headerAuthorizationBearer <token>

Bearer token authentication. Obtain your API key from the OmniDimension dashboard.

Header Parameters

Idempotency-Key*string

A unique string you choose, up to 255 characters. Required on this route. The same key with the same body replays the first answer for 24 hours instead of acting twice. A different body with the same key answers 409.

Lengthlength <= 255

Request Body

application/json
phone_number_id*integer

The number to send from.

to*string

The customer's number in international format, such as +15551234567.

type*string
Value in"text""template""image""document"
text?string

Required when type is text.

Lengthlength <= 4096
template?

Required when type is template.

media?

Required when type is image or document.

reply_to?integer

A message id in the same conversation to quote. Not allowed with a template.

take_over?boolean

Stop the agent answering this conversation and let a person run it.

Defaultfalse

Response body

application/json

Response Body

The message was accepted. A provider failure that still created the row also returns 201, with status: "failed" and a failure reason.

application/json
id?integer
conversation_id?string
wa_message_id?string

The message's id at WhatsApp, when there is one.

sender?string
Value in"customer""agent""person"
type?string

The message type: text, image, video, audio, document, template, reaction, interactive, location, contacts, call or other.

text?string
caption?string
profile_name?string
sent_by_workflow?string

The workflow that sent it, when a workflow did.

timestamp?string
status?WhatsappMessageStatus

received is an inbound customer message. The rest are outbound, in order: pending, sent, delivered, read, or failed.

Value in"pending""sent""delivered""read""received""failed"
reply_to?

The message this one quotes, when it quotes one.

reactions?
media?

Media details, when the message carries a file. It holds no download link.

voice?

Voice note details, when the message is one.

location?
contacts?
interactive?
template?

The template this message sent, when it is a template message.

failure?

Why a send failed, present only when status is failed.

charged?

What this send cost, when it has been charged.

timeline?

The delivery steps of this message, oldest first.

List messages

One conversation's messages, newest first. Poll forward with after (the id of the newest message you already have) to get only new ones. Page backward through history with cursor. Do not pass both.

Get a message

One message with its timeline: the delivery and read steps, oldest first. Poll it after a send to learn whether the message was delivered and read. Also shows what the send cost once it is charged.