Skip to main content
The messages API lets you send outbound messages to contacts programmatically. Messages are always sent within a conversation — Waply creates a new conversation automatically if one does not already exist for the contact and channel combination. You can send plain text, approved WhatsApp template messages, images, and documents.

​
The Message object

​
id
string
Unique identifier for the message, prefixed with msg_.
​
conversation_id
string
ID of the conversation this message belongs to.
​
direction
string
Either inbound (received from a contact) or outbound (sent by your team or via the API).
​
type
string
Message type. One of text, template, image, or document.
​
content
string
The text body of the message. Present for text and template types.
​
status
string
Delivery status of an outbound message. One of sent, delivered, read, or failed.
​
created_at
string
ISO 8601 timestamp of when the message was created.

​
Message status values

StatusMeaning
sentThe message has been accepted by the messaging provider.
deliveredThe message has been delivered to the recipient’s device.
readThe recipient has read the message.
failedDelivery failed. Check the conversation for error details.
Status updates from sent to delivered and read are delivered asynchronously via webhooks. Subscribe to the message.delivered and message.read events to track status changes in real time.

​
Send a message

​
POST /messages/send

Sends an outbound message to a contact. The type field determines which other body fields are required.
​
contact_id
string
required
ID of the contact to send the message to.
​
channel
string
required
The channel to send the message on. One of whatsapp, instagram, messenger, or webchat.
​
type
string
required
Message type. One of text, template, image, or document.
​
content
string
The text body of the message. Required when type is text.
​
template_name
string
The name of the approved WhatsApp message template to use. Required when type is template.
​
template_params
string[]
Ordered array of parameter values to substitute into the template’s variable placeholders. Required when the template contains variables.
​
media_url
string
Publicly accessible URL of the media file to send. Required when type is image or document.

​
Send a text message

curl --request POST \
  --url https://api.waply.io/v1/messages/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contact_id": "con_01HXYZ",
    "channel": "whatsapp",
    "type": "text",
    "content": "Hi Jane, your order #4521 has shipped and is on its way!"
  }'
Response 
{
  "id": "msg_01HSTU",
  "conversation_id": "conv_01HABC",
  "direction": "outbound",
  "type": "text",
  "content": "Hi Jane, your order #4521 has shipped and is on its way!",
  "status": "sent",
  "created_at": "2026-04-16T10:30:00Z"
}

​
Send a template message

WhatsApp requires pre-approved message templates for outbound messages sent outside the 24-hour customer service window. Provide the template name and an array of parameter values in the order they appear in the template.
Template messages must be approved in WhatsApp Business Manager before you can send them. You can view your approved templates in Waply under Settings > Message Templates.
curl --request POST \
  --url https://api.waply.io/v1/messages/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contact_id": "con_01HXYZ",
    "channel": "whatsapp",
    "type": "template",
    "template_name": "order_shipped",
    "template_params": ["Jane", "4521", "2 business days"]
  }'
Response 
{
  "id": "msg_01HVWX",
  "conversation_id": "conv_01HABC",
  "direction": "outbound",
  "type": "template",
  "content": "Hi Jane, your order #4521 has shipped. Expected delivery: 2 business days.",
  "status": "sent",
  "created_at": "2026-04-16T10:35:00Z"
}

​
Send an image

curl --request POST \
  --url https://api.waply.io/v1/messages/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contact_id": "con_01HXYZ",
    "channel": "whatsapp",
    "type": "image",
    "media_url": "https://cdn.yourapp.com/images/invoice-4521.png"
  }'
Response 
{
  "id": "msg_01HYYY",
  "conversation_id": "conv_01HABC",
  "direction": "outbound",
  "type": "image",
  "content": null,
  "status": "sent",
  "created_at": "2026-04-16T10:40:00Z"
}

​
Send a document

curl --request POST \
  --url https://api.waply.io/v1/messages/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contact_id": "con_01HXYZ",
    "channel": "whatsapp",
    "type": "document",
    "media_url": "https://cdn.yourapp.com/docs/invoice-4521.pdf"
  }'
Response 
{
  "id": "msg_01HZZZ",
  "conversation_id": "conv_01HABC",
  "direction": "outbound",
  "type": "document",
  "content": null,
  "status": "sent",
  "created_at": "2026-04-16T10:45:00Z"
}
The media_url must be publicly accessible at the time of sending. Waply fetches the file and forwards it to the messaging provider. Signed URLs with short expiry times may cause delivery failures.