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
Send a message
messages:sendIdempotency-KeyCounts as a sendSends 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
torequiredstring
Recipient phone number in international format, e.g. +919876543210.
typerequired"template" | "text" | "image" | "document" | "video" | "audio"
Kind of message.
accountIdstring
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.
templateobject
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.headerMediaIdstring
Media library id for IMAGE / VIDEO / DOCUMENT headers (defaults to the template's sample media).
textstring
Required for type text. Up to 4096 characters.
previewUrlboolean
Show a link preview for text messages (auto-detected when omitted).
mediaIdstring
Required for media types: id of a file uploaded to the Media library (the
{id}in its file URL/api/media/{id}/file).captionstring
Caption for image, video and document messages (max 1024 characters).
filenamestring
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
{
"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)
{
"to": "+919876543210",
"type": "text",
"text": "Your order is on its way! 🚚"
}{
"to": "+919876543210",
"type": "image",
"mediaId": "cm4m3d14000001a2s3d4f5g6h",
"caption": "New arrivals are here"
}{
"to": "+919876543210",
"type": "template",
"template": {
"id": "cm4t3mpl4t30001b2c3d4e5f6",
"variables": {
"body": [
"Ananya",
"A-1042",
"shipped"
],
"buttons": [
{
"index": 0,
"subType": "url",
"value": "A-1042"
}
]
}
}
}Errors
- 400
BAD_REQUESTThe media file can't be sent as this message type (e.g. a PDF as
image). - 404
NOT_FOUNDThe account, template or media id doesn't exist in this workspace.
- 422
INVALID_PHONEtois not a valid phone number. - 422
WINDOW_CLOSEDText/media outside the 24-hour customer service window. Send a template instead.
- 422
CONTACT_BLOCKEDThe contact is blocked in the panel.
- 422
CONTACT_UNSUBSCRIBEDMarketing template to a contact who stopped offers (utility templates are still allowed).
- 422
CONTACT_NO_MESSAGESThe contact asked for no messages at all; only an authentication (login code) template can be sent.
- 422
TEMPLATE_NOT_APPROVEDThe template exists but isn't approved yet.
- 422
TEMPLATE_ACCOUNT_MISMATCHThe template belongs to a different WhatsApp account.
- 422
TEMPLATE_VARIABLES_MISSINGNot enough variable values for the template.
- 422
HEADER_MEDIA_REQUIREDThe template has a media header and no media was given.
- 422
NO_WHATSAPP_ACCOUNTThe workspace has no WhatsApp account yet.
- 422
SEND_FAILEDWhatsApp rejected the message.
details.messageholds the stored message with errorCode / errorMessage. Returned as 502 withdetails.retryable: truefor temporary errors. - 502
SEND_OUTCOME_UNKNOWNWhatsApp did not answer the send (no answer in time, a server error, a dropped connection), so whether it was delivered is unknown.
details.retryableis false anddetails.messageholds 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, anderror.messagesays 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-Keyheader 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 message status
messages:readReturns the current delivery status of a message sent through the API, a campaign, an automation or the inbox.
Path parameters
idrequiredstring
Message id returned when sending.
Request
curl "https://app.ezreach.in/api/v1/messages/cm4m3ss4g30001h8j2k4l6m8n" \
-H "Authorization: Bearer $EZREACH_API_KEY"Response
{
"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
- 404
NOT_FOUNDNo 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).

