Skip to main content
POST
cURL
Send a message to an existing conversation on behalf of your agent.

Message Types

You can send two main types of messages:
  • Unified messages — Sent rich text messages with images, videos, audio, documents, buttons, and more
  • Template messages — Pre-approved messages that can initiate or re-engage conversations
You can additionally send cta and text speicic messages, though these are deprecated and will be removed in the future. We will be adding support for other specific message types, such as contacts, location and call requests in the future.
Check conversation status first! You can only send regular (non-template) messages to active conversations. Use the Get Conversation endpoint to verify the conversation is active before sending.
Billing: Template messages are billed by Meta according to their pricing tiers. Regular messages within the 24-hour customer service window are free.

Service window closed

Sending anything other than a template after the 24-hour window has closed returns:
Match on code, not the text. To act before this happens, check active and chatWindowRemainingTime on the conversation, or subscribe to the subscription.service_window.expiring and .closed webhook events.

Media URLs

unified.media.url must be reachable when you call this endpoint. We download the file straight away and host our own copy, so short-lived pre-signed URLs are fine. We check the file type with a HEAD request, falling back to a one-byte GET for URLs that only allow GET, such as S3 and GCS pre-signed URLs. The Content-Type must be one WhatsApp supports.

Template variables

  • body and header take a list for positional ({{1}}) templates, or an object keyed by variable name for named templates. An image header takes { "link": "https://..." }.
  • buttons is only needed when the template has a dynamic button (a URL with a variable, or a flow). Then pass one value per button, in order. Values for static buttons, such as quick replies, are ignored. Templates with only static buttons can leave buttons out.
  • The template is looked up by name. Keep one language per template name.

Reactions

React to a message in the conversation, or remove your reaction, using the message’s Wassist ID:
Send "emoji": null or leave it out to remove the reaction. Reactions follow the same 24-hour rule as other non-template messages. Customer reactions arrive as the message.reaction.updated webhook event.

Quoted replies

To reply to a specific message, so it shows quoted above your reply in WhatsApp, add replyTo with the message’s Wassist ID. This is the same message.id you get on message.received webhook events. It works on text and unified messages:
The sent message comes back with replyTo set. Errors:

Idempotency

Send an Idempotency-Key header (any unique string up to 255 characters, such as a UUID) to make retries safe. Keys are scoped to your API key and kept for 24 hours. POST /api/v1/conversations/ supports the same header.

Authorizations

X-API-Key
string
header
required

API key authentication. Pass your API key in the X-API-Key header.

Path Parameters

id
string
required

Body

application/json

Unified input for sending text, template, or CTA URL messages.

type
enum<string>
required

The type of message to send: 'text', 'template', 'cta', or 'unified'.

  • text - text
  • template - template
  • cta - cta
  • unified - unified
Available options:
text,
template,
cta,
unified
text
object
template
object
cta
object
unified
object
replyTo
string<uuid> | null

The Wassist ID of the message to quote, as sent on webhooks. Only for 'text' and 'unified' messages.

Response

201 - application/json
id
string<uuid>
required
read-only
role
string
required
read-only
type
string
required
read-only
status
string | null
required
createdAt
string<date-time>
required
replyTo
string
required
read-only
source
string
required
supportHandoff
string
required
read-only
text
string
required
read-only
image
string
required
read-only
cta
string
required
read-only
listSelection
string
required
read-only
template
string
required
read-only
unified
string
required
read-only
quickReply
string
required
read-only
toolExecutions
string
required
read-only
referral
object | null
required

Click-to-WhatsApp ad referral attached to an inbound message.

Shared by the REST API and outbound webhooks.