Send outbound messages to contacts via the Waply API

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

string

Unique identifier for the message, prefixed with msg_.

string

ID of the conversation this message belongs to.

string

Either inbound (received from a contact) or outbound (sent by your team or via the API).

string

Message type. One of text, template, image, or document.

string

The text body of the message. Present for text and template types.

string

Delivery status of an outbound message. One of sent, delivered, read, or failed.

string

ISO 8601 timestamp of when the message was created.

Message status values

Status	Meaning
`sent`	The message has been accepted by the messaging provider.
`delivered`	The message has been delivered to the recipient’s device.
`read`	The recipient has read the message.
`failed`	Delivery 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.

string

required

ID of the contact to send the message to.

string

required

The channel to send the message on. One of whatsapp, instagram, messenger, or webchat.

string

required

Message type. One of text, template, image, or document.

string

The text body of the message. Required when type is text.

string

The name of the approved WhatsApp message template to use. Required when type is template.

string[]

Ordered array of parameter values to substitute into the template’s variable placeholders. Required when the template contains variables.

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!"
  }'

const response = await fetch('https://api.waply.io/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact_id: 'con_01HXYZ',
    channel: 'whatsapp',
    type: 'text',
    content: 'Hi Jane, your order #4521 has shipped and is on its way!',
  }),
});
const message = await response.json();

import requests, os

response = requests.post(
    'https://api.waply.io/v1/messages/send',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={
        'contact_id': 'con_01HXYZ',
        'channel': 'whatsapp',
        'type': 'text',
        'content': 'Hi Jane, your order #4521 has shipped and is on its way!',
    },
)
message = response.json()

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"]
  }'

const response = await fetch('https://api.waply.io/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact_id: 'con_01HXYZ',
    channel: 'whatsapp',
    type: 'template',
    template_name: 'order_shipped',
    template_params: ['Jane', '4521', '2 business days'],
  }),
});
const message = await response.json();

import requests, os

response = requests.post(
    'https://api.waply.io/v1/messages/send',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={
        'contact_id': 'con_01HXYZ',
        'channel': 'whatsapp',
        'type': 'template',
        'template_name': 'order_shipped',
        'template_params': ['Jane', '4521', '2 business days'],
    },
)
message = response.json()

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"
  }'

const response = await fetch('https://api.waply.io/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact_id: 'con_01HXYZ',
    channel: 'whatsapp',
    type: 'image',
    media_url: 'https://cdn.yourapp.com/images/invoice-4521.png',
  }),
});
const message = await response.json();

import requests, os

response = requests.post(
    'https://api.waply.io/v1/messages/send',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={
        'contact_id': 'con_01HXYZ',
        'channel': 'whatsapp',
        'type': 'image',
        'media_url': 'https://cdn.yourapp.com/images/invoice-4521.png',
    },
)
message = response.json()

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"
  }'

const response = await fetch('https://api.waply.io/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contact_id: 'con_01HXYZ',
    channel: 'whatsapp',
    type: 'document',
    media_url: 'https://cdn.yourapp.com/docs/invoice-4521.pdf',
  }),
});
const message = await response.json();

import requests, os

response = requests.post(
    'https://api.waply.io/v1/messages/send',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={
        'contact_id': 'con_01HXYZ',
        'channel': 'whatsapp',
        'type': 'document',
        'media_url': 'https://cdn.yourapp.com/docs/invoice-4521.pdf',
    },
)
message = response.json()

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.

​The Message object

​Message status values

​Send a message

​POST /messages/send

​Send a text message

​Send a template message

​Send an image

​Send a document

The Message object

Message status values

Send a message

POST /messages/send

Send a text message

Send a template message

Send an image

Send a document