Reply to the customer
POST/response/reply/:token
Sends a message to the customer in the conversation the token belongs to.
Use the responseUrl from the inbound notification, which already contains the token.
A reply is either plain text or a structured message — reply buttons, a list, a URL button and so on. Structured messages are supported on WhatsApp and Viber only.
Interactive messages
Set type to interactive and put the payload in interactive. The payload follows
WhatsApp's own interactive message format, so an existing WhatsApp payload can be used
as-is. Every payload carries its own type — the subtype — plus body.text and an
action:
| Subtype | What the customer sees |
|---|---|
button | Up to three tappable reply buttons |
list | A menu of rows, grouped into sections, opened from a single button |
cta_url | A single button that opens a URL |
location_request_message | A prompt asking the customer to share their location |
call_permission_request | A prompt asking the customer's permission to be called |
voice_call | An offer to start a WhatsApp voice call |
flow | Launches a WhatsApp Flow |
Either interactive.body.text or a top-level message must be present — that text is
what is stored against the conversation and shown in the agent console.
Subtypes are not validated by this API; they are passed through to the channel. Which
ones you can actually send depends on the channel and on your WhatsApp Business account.
For a subtype without an example below, such as flow, build the payload to WhatsApp's
own spec and send it in the same envelope.
On Viber a URL button uses the button subtype with the same parameters, and has no
name and no footer.
Template messages
Set type to template and put the payload in template. template.type must be one
of buttons, confirm, carousel or image_carousel, and template.altText is
required — it is the fallback text where the template cannot be rendered, and the text
stored against the conversation. Template support varies by channel; check with 8x8 that
your channel account can send templates before building against this.
Reply errors
Returned as 400 with the reason in error:
| Condition | error |
|---|---|
No message and no type | Message in request body is required |
interactive or template sent without type | type is required when an interactive or template payload is provided |
type is not interactive or template | type must be 'interactive' or 'template' |
type set but the matching payload object missing | interactive is required when type is 'interactive' / template is required when type is 'template' |
| The payload has no subtype | interactive.type is required / template.type is required |
template without altText | template.altText is required |
template.type not one of the four | template.type must be one of buttons, confirm, carousel, image_carousel |
type: interactive with neither message nor interactive.body.text | interactive.body.text or message is required |
type set on a channel other than WhatsApp or Viber | interactive and template messages are only supported on WhatsApp and Viber |
The channel check is the only one of these made after the token is used, so a structured reply sent to the wrong channel consumes a token use. The others are returned before the token is touched. Either way the 15-minute window stays open, so the call can be corrected and retried.
Request
Responses
- 200
- 400
- 403
- 404
- 500
- 502
The request was accepted and carried out.
A required field is missing or invalid.
The token is invalid, or expired. Either the 48-hour lifetime has elapsed, or the 15-minute window opened by the first call has closed.
The conversation referenced by the token no longer exists.
The request could not be completed.
A lookup required to complete the request failed.