Browse the docs

Messages

Send template, text and media messages. Delivery happens asynchronously: poll a message to follow it from SENT to DELIVERED and READ.

Base address: https://app.ezreach.in/api/v1

POST/api/v1/messages

Send a message

Permission:messages:sendIdempotency-KeyCounts as a send

Sends a message to a phone number. The contact is created automatically (source API) when it doesn't exist. Templates can be sent at any time; text and media messages only within 24 hours of the customer's last message.

Body

  • torequired

    string

    Recipient phone number in international format, e.g. +919876543210.

  • typerequired

    "template" | "text" | "image" | "document" | "video" | "audio"

    Kind of message.

  • accountId

    string

    WhatsApp account to send from. Defaults to the template's account when the template is given by id, otherwise to the workspace's default account.

  • template

    object

    Required for type template. Either { name, language? } or { id }, plus optional variables and headerMediaId. Without language, the approved translation updated most recently is used.

  • template.variables

    { header?: string[], body?: string[], buttons?: { index, subType, value }[] }

    Values for {{1}}, {{2}}… in order. Dynamic URL buttons need { index, subType: "url", value } (the URL suffix).

  • template.headerMediaId

    string

    Media library id for IMAGE / VIDEO / DOCUMENT headers (defaults to the template's sample media).

  • text

    string

    Required for type text. Up to 4096 characters.

  • previewUrl

    boolean

    Show a link preview for text messages (auto-detected when omitted).

  • mediaId

    string

    Required for media types: id of a file uploaded to the Media library (the {id} in its file URL /api/media/{id}/file).

  • caption

    string

    Caption for image, video and document messages (max 1024 characters).

  • filename

    string

    File name shown for document messages.

  • contact

    { name?: string, email?: string }

    Saved on the contact, overwriting stored values when provided. Nothing is saved when the request is rejected.

Request

curl -X POST "https://app.ezreach.in/api/v1/messages" \
  -H "Authorization: Bearer $EZREACH_API_KEY" \
  -H "Idempotency-Key: order-A-1042-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+919876543210",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "variables": {
      "body": [
        "Ananya",
        "A-1042",
        "shipped"
      ],
      "buttons": [
        {
          "index": 0,
          "subType": "url",
          "value": "A-1042"
        }
      ]
    }
  },
  "contact": {
    "name": "Ananya Iyer"
  }
}'

Response

200 OK
{
  "data": {
    "id": "cm4m3ss4g30001h8j2k4l6m8n",
    "conversationId": "cm4c0nv000001p1q2r3s4t5u6",
    "contactId": "cm4c0nt4ct0001x7k2p9q3r8s",
    "accountId": "cm4acc0unt0001v7w8x9y0z1a",
    "to": "+919876543210",
    "direction": "OUTBOUND",
    "type": "template",
    "status": "SENT",
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkQ0RjBBQ0Y0RTRCRjBFMzZBAA==",
    "errorCode": null,
    "errorTitle": null,
    "errorMessage": null,
    "campaignId": null,
    "automationId": null,
    "timestamps": {
      "createdAt": "2026-09-16T10:30:00.000Z",
      "sentAt": "2026-09-16T10:30:00.412Z",
      "deliveredAt": null,
      "readAt": null,
      "failedAt": null
    }
  }
}
More request examples(3)
Text message (open 24-hour window)
{
  "to": "+919876543210",
  "type": "text",
  "text": "Your order is on its way! 🚚"
}
Image message
{
  "to": "+919876543210",
  "type": "image",
  "mediaId": "cm4m3d14000001a2s3d4f5g6h",
  "caption": "New arrivals are here"
}
Template by id
{
  "to": "+919876543210",
  "type": "template",
  "template": {
    "id": "cm4t3mpl4t30001b2c3d4e5f6",
    "variables": {
      "body": [
        "Ananya",
        "A-1042",
        "shipped"
      ],
      "buttons": [
        {
          "index": 0,
          "subType": "url",
          "value": "A-1042"
        }
      ]
    }
  }
}

Errors

  • 400BAD_REQUEST

    The media file can't be sent as this message type (e.g. a PDF as image).

  • 404NOT_FOUND

    The account, template or media id doesn't exist in this workspace.

  • 422INVALID_PHONE

    to is not a valid phone number.

  • 422WINDOW_CLOSED

    Text/media outside the 24-hour customer service window. Send a template instead.

  • 422CONTACT_BLOCKED

    The contact is blocked in the panel.

  • 422CONTACT_UNSUBSCRIBED

    Marketing template to a contact who stopped offers (utility templates are still allowed).

  • 422CONTACT_NO_MESSAGES

    The contact asked for no messages at all; only an authentication (login code) template can be sent.

  • 422TEMPLATE_NOT_APPROVED

    The template exists but isn't approved yet.

  • 422TEMPLATE_ACCOUNT_MISMATCH

    The template belongs to a different WhatsApp account.

  • 422TEMPLATE_VARIABLES_MISSING

    Not enough variable values for the template.

  • 422HEADER_MEDIA_REQUIRED

    The template has a media header and no media was given.

  • 422NO_WHATSAPP_ACCOUNT

    The workspace has no WhatsApp account yet.

  • 422SEND_FAILED

    WhatsApp rejected the message. details.message holds the stored message with errorCode / errorMessage. Returned as 502 with details.retryable: true for temporary errors.

  • 502SEND_OUTCOME_UNKNOWN

    WhatsApp did not answer the send (no answer in time, a server error, a dropped connection), so whether it was delivered is unknown. details.retryable is false and details.message holds the stored message (errorCode SEND_UNCONFIRMED): do not send it again — it may have been delivered. GET /messages/{id} shows what the panel recorded. Whether a later delivery confirmation can be matched to the message depends on how the panel is set up, and error.message says which: where it cannot, the record never changes.

  • Delivery and read receipts arrive later from WhatsApp; a message can still turn FAILED after this call succeeds (e.g. an undeliverable number).
  • Only retry a send when the error says details.retryable: true. A send WhatsApp never answered (SEND_OUTCOME_UNKNOWN) is never safe to repeat.
  • Send an Idempotency-Key header with every send: if your request times out on your side, send it again with the same key and you get the first answer back instead of a second message.
GET/api/v1/messages/{id}

Get message status

Permission:messages:read

Returns the current delivery status of a message sent through the API, a campaign, an automation or the inbox.

Path parameters

  • idrequired

    string

    Message id returned when sending.

Request

curl "https://app.ezreach.in/api/v1/messages/cm4m3ss4g30001h8j2k4l6m8n" \
  -H "Authorization: Bearer $EZREACH_API_KEY"

Response

200 OK
{
  "data": {
    "id": "cm4m3ss4g30001h8j2k4l6m8n",
    "conversationId": "cm4c0nv000001p1q2r3s4t5u6",
    "contactId": "cm4c0nt4ct0001x7k2p9q3r8s",
    "accountId": "cm4acc0unt0001v7w8x9y0z1a",
    "to": "+919876543210",
    "direction": "OUTBOUND",
    "type": "template",
    "status": "READ",
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNkQ0RjBBQ0Y0RTRCRjBFMzZBAA==",
    "errorCode": null,
    "errorTitle": null,
    "errorMessage": null,
    "campaignId": null,
    "automationId": null,
    "timestamps": {
      "createdAt": "2026-09-16T10:30:00.000Z",
      "sentAt": "2026-09-16T10:30:00.412Z",
      "deliveredAt": "2026-09-16T10:30:02.000Z",
      "readAt": "2026-09-16T10:31:15.000Z",
      "failedAt": null
    }
  }
}

Errors

  • 404NOT_FOUND

    No message with this id in the workspace.

  • status is one of PENDING, SENT, DELIVERED, READ, FAILED (RECEIVED for inbound messages). When FAILED, errorCode, errorTitle and errorMessage explain why.
  • errorCode SEND_UNCONFIRMED: WhatsApp never answered the send, so it may still have been delivered — deliveredAt / readAt may be filled in later if WhatsApp's confirmation can be matched (the status stays FAILED). Never send it again automatically.
  • conversationId and contactId are null for a message kept only as a record after its person was deleted or erased (its text is removed; it stays so a late delivery is still accounted for).