Messages

Send messages on every channel WhautoChat connects to (WhatsApp, Telegram, Instagram, TikTok, Messenger and website live chat) and read a contact's message history. All paths are under /v1/messages. Send your key in the x-api-key header and send bodies as JSON with Content-Type: application/json. A missing or revoked key gets 401 { "message": "Unauthorized" }. See REST API for how to get a key.

How sending works

Queued, not instant. Every send is queued and delivered in the background, straight away or at scheduleDateTime. 200 { "success": true } means the message is queued, not that it was delivered. Follow delivery with Webhooks or read it back with message history.
Choose who receives it. Send either contact with the WhautoChat contact id, or recepient with the channel's identifier (a phone number, username or user ID, depending on the channel). See addressing.
The field really is spelled recepient. That is the name the API reads; recipient is ignored.
Choose the workspace. workspace.id is required on every send and must be a workspace in your account. The message goes out from that workspace's connected channel.

History

GET/v1/messages/{contactId}List messages for a contact

POST/v1/messages/telegram/sendtextSend a text message POST/v1/messages/telegram/sendmediaSend an image, video or document POST/v1/messages/telegram/sendtemplateSend a message with buttons

Instagram

POST/v1/messages/instagram/sendtextSend a text message POST/v1/messages/instagram/sendmediaSend an image, video or document POST/v1/messages/instagram/sendtemplateSend a generic template

TikTok

POST/v1/messages/tiktok/sendtextSend a text message POST/v1/messages/tiktok/sendmediaSend an image POST/v1/messages/tiktok/sendqabuttoncardSend a Q&A button card POST/v1/messages/tiktok/sendqatextlinkcardSend a Q&A text link card

Messenger

POST/v1/messages/messenger/sendtextSend a text message POST/v1/messages/messenger/sendmediaSend an image, video or document POST/v1/messages/messenger/sendtemplateSend a generic template

Website live chat

POST/v1/messages/website/sendtextSend a text message POST/v1/messages/website/sendmediaSend an image, video or document POST/v1/messages/website/sendtemplateSend a message with buttons

The contact, recepient and workspace objects

Every send names one recipient (contact or recepient) and one workspace.

Attributes

contactobjector recepient

An existing WhautoChat contact.

recepientobjector contact

The channel's own identifier for the person. Which field you send depends on the channel.

workspaceobjectrequired

The workspace whose connected channel sends the message. It must be in your account.

scheduleDateTimestring

ISO 8601 date and time to send later, for example 2026-11-02T09:30:00Z. Leave it out to send now.

Channel	Address with	Notes
WhatsApp	`contact.id` or `recepient.phoneNumber`	If no contact has that number yet, the send creates one, named after `recepient.name` (or the number).
Telegram	`contact.id`	The contact exists once the person messages your Telegram bot.
Instagram	`contact.id` or `recepient.username`	The contact exists once the person messages your Instagram account.
TikTok	`contact.id` or `recepient.tikTokUserId`	The contact exists once the person messages your TikTok account.
Messenger	`contact.id` (or `recepient.messengerId` on `sendtemplate`)	The contact exists once the person messages your Facebook Page.
Website live chat	`contact.id`	Visitors who have chatted with you through your website widget.

On Instagram, TikTok and Messenger, a recepient that matches no contact returns 400 asking you to get the contact to start the conversation first.

Address by contact id
{
  "contact": { "id": "Xk82LmQp4T" },
  "workspace": { "id": "Wk7Hs2Pq9L" },
  "scheduleDateTime": "2026-11-02T09:30:00Z"
}

Address by WhatsApp number
{
  "recepient": { "phoneNumber": "+12025550188", "name": "Maria Lopez" },
  "workspace": { "id": "Wk7Hs2Pq9L" }
}

Sending rules

These apply to every POST endpoint on this page.

Scheduling. scheduleDateTime is optional. Send an ISO 8601 date and time (for example 2026-11-02T09:30:00Z) to send later, or leave it out to send now.
Media. For mediaUrl, give a public URL that WhautoChat can download. WhautoChat downloads and stores the file when you call the API, so the URL only needs to work at that moment. If the download fails you get 400 { "error": "Error downloading file from the URL" }. Most channels send image/jpeg and image/png as images, video/mp4 and video/3gpp as videos, and anything else as a document.
Personalisation. Text in textMessage (and in the list, button and header text that the channel supports) goes through the same contact personalisation as messages sent from the app.
WhatsApp 24-hour window. WhatsApp only delivers free-form messages (text, media, interactive and product messages) to people who messaged you in the last 24 hours. To start a conversation, or after the window has closed, use a template. The API queues the message either way, so a free-form message outside the window fails at delivery, not at the API call.
Errors. Error bodies have an error field with the reason (except 401). A 500 means the request could not be completed; retry, and contact support if it keeps happening.

The message object

Attributes

idstring

Message id

contactobject

The contact the message belongs to.

channelstring

whatsapp, telegram, instagram, tiktok, messenger or website

isIncomingboolean

true for messages from the contact, false for messages you sent

fromstring

Incoming messages only: the sender's name

sentBystring

Outgoing messages only: the team member's first and last name, or the workspace name followed by "Bot" for automated messages

replyToMessageobject

Present when the message replies to another message: { "id": "..." }

mediaUrlstring

Present when the message has an attachment

type, status, errorMessage, headerText, caption, text, footerText, optionsvarious

Message details

timestamp, createdAt, updatedAtstring

Timestamps

Fields that do not apply are left out.

The message object
{
  "id": "a1B2c3D4e5",
  "contact": {
    "id": "Xk82LmQp4T",
    "channel": "whatsapp",
    "phoneNumber": "12025550188"
  },
  "channel": "whatsapp",
  "isIncoming": true,
  "type": "text",
  "from": "Maria Lopez",
  "timestamp": "2026-10-12T14:05:11.000Z",
  "status": "read",
  "text": "Hi, can I move my booking to Friday?",
  "createdAt": "2026-10-12T14:05:12.310Z",
  "updatedAt": "2026-10-12T14:06:40.902Z"
}

List messages for a contact

GET/v1/messages/{contactId}

Returns one contact's messages, newest first.

Path parameters

contactIdstringrequired

Contact id

Query parameters

pageintegerdefault 1

Page number, starting at 1

limitintegerdefault 10

Messages per page. Max 100.

searchTextstring

Only messages that contain this text (not case sensitive)

200 OK: a plain JSON array of messages.

Errors

Status	Body	When
`404`	`{ "error": "Contact not found" }`	The contact is not in your account
`500`	`{ "error": "Could not retrieve Chat Messages" }`	The request could not be completed

Request
curl "https://api.whauto.chat/v1/messages/Xk82LmQp4T?page=1&limit=20" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
[
  {
    "id": "a1B2c3D4e5",
    "contact": { "id": "Xk82LmQp4T", "channel": "whatsapp", "phoneNumber": "12025550188" },
    "channel": "whatsapp",
    "isIncoming": true,
    "type": "text",
    "from": "Maria Lopez",
    "timestamp": "2026-10-12T14:05:11.000Z",
    "status": "read",
    "text": "Hi, can I move my booking to Friday?",
    "createdAt": "2026-10-12T14:05:12.310Z",
    "updatedAt": "2026-10-12T14:06:40.902Z"
  }
]

Send a WhatsApp text message

POST/v1/messages/whatsapp/sendtext

Body parameters

contactobjector recepient

{ "id": "..." }. See addressing.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }: the workspace whose WhatsApp number sends it

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact` or `recepient`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+12025550188", "name": "Maria Lopez" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Hi Maria, your order has shipped and will arrive on Thursday."
  }'

Response 200
{ "success": true }

Send WhatsApp media

POST/v1/messages/whatsapp/sendmedia

Sends an image, video or document. See media for how files are fetched.

Body parameters

contactobjector recepient

{ "id": "..." }. See addressing.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the file

mimeTypestringrequired

For example image/jpeg, video/mp4 or application/pdf

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+12025550188" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/files/invoice-1042.pdf",
    "mimeType": "application/pdf"
  }'

Response 200
{ "success": true }

Send a WhatsApp template

POST/v1/messages/whatsapp/sendtemplate

Sends an approved WhatsApp template. Use it to start a conversation or after the 24-hour window has closed. The template is looked up by template.name and template.language in the workspace you send from. List your templates with the WhatsApp templates API.

Body parameters

contactobjector recepient

{ "id": "..." }. See addressing.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

templateobjectrequired

The template to send.

headerMediaUrlstring

Image, video or document URL for a media header

headerTextParametersstring[]

Values for the variables in the header text

bodyTextParametersstring[]

Values for the variables in the body, in order

buttonUrlParametersstring[]

Values for dynamic URL buttons

locationParametersobject

For a location header.

flowParametersobject

For a template that opens a WhatsApp Flow.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact` or `recepient`, `workspace.id`, `template.name` or `template.language` is missing, or `locationParameters` or `flowParameters` is incomplete
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`404`	`{ "error": "Invalid WhatsApp Template" }`	No template with that name and language in the workspace
`500`	`{ "error": "Could not send WhatsApp Template Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendtemplate" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+447700900123", "name": "James Carter" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "template": { "name": "appointment_reminder", "language": "en_US" },
    "bodyTextParameters": ["James", "Friday 14 November", "10:30"],
    "scheduleDateTime": "2026-11-13T09:00:00Z"
  }'

Response 200
{ "success": true }

Send WhatsApp reply buttons

POST/v1/messages/whatsapp/sendinteractivebuttons

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

buttonsstring[]required

Reply button titles. WhatsApp allows up to 3.

headerTypestring

TEXT, image, video or document

headerTextMessagestringwith headerType TEXT

Header text

mediaUrlstringwith a media headerType

Public URL of the header file

mimeTypestringwith mediaUrl

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Interactive Button Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendinteractivebuttons" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Xk82LmQp4T" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "headerType": "TEXT",
    "headerTextMessage": "Your appointment",
    "textMessage": "Can you still make it on Friday at 10:30?",
    "buttons": ["Yes, confirm", "Reschedule", "Cancel"]
  }'

Response 200
{ "success": true }

Send a WhatsApp list message

POST/v1/messages/whatsapp/sendinteractivelist

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

listButtonTitlestringrequired

The label on the button that opens the list

buttonsobject[]required

The list rows.

listSectionTitlestring

Title shown above the rows

headerTypestring

Only TEXT is accepted

headerTextMessagestringwith headerType

Header text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Interactive List Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendinteractivelist" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Xk82LmQp4T" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Pick a time that suits you.",
    "listButtonTitle": "See times",
    "listSectionTitle": "Friday",
    "buttons": [
      { "id": "fri-0930", "title": "09:30", "description": "Morning" },
      { "id": "fri-1400", "title": "14:00", "description": "Afternoon" }
    ]
  }'

Response 200
{ "success": true }

Send a WhatsApp link button

POST/v1/messages/whatsapp/sendinteractivectaurl

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

buttonTitlestringrequired

The link button label

buttonUrlstringrequired

The URL the button opens

headerTypestring

image, video or document for a media header

mediaUrlstringwith a media headerType

Public URL of the header file

mimeTypestringwith mediaUrl

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Interactive CTA URL Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendinteractivectaurl" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Xk82LmQp4T" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Your order is on its way.",
    "buttonTitle": "Track order",
    "buttonUrl": "https://example.com/track/1042"
  }'

Response 200
{ "success": true }

Send a WhatsApp catalog

POST/v1/messages/whatsapp/sendcatalog

Sends your WhatsApp catalog with a message.

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Catalog Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendcatalog" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+12025550188" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Browse our new season collection."
  }'

Response 200
{ "success": true }

Send a WhatsApp product

POST/v1/messages/whatsapp/sendproduct

Sends one product from your catalog.

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

productobjectrequired

The product to send.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Product Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendproduct" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+12025550188" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Back in stock in your size.",
    "product": { "catalogId": "184467290011", "productRetailerId": "TEE-BLUE-M" }
  }'

Response 200
{ "success": true }

Send a WhatsApp product list

POST/v1/messages/whatsapp/sendproductlist

Sends several products from your catalog.

Body parameters

contactobjector recepient

{ "id": "..." }. The contact must belong to the workspace you send from.

recepientobjector contact

{ "phoneNumber": "...", "name": "..." }. Creates the contact if the number is new.

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

headerTextMessagestringrequired

Header text

productListobject[]required

At least one item. The catalog of the first item is used.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing or `productList` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in that workspace
`404`	`{ "error": "Invalid workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send WhatsApp Product List Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/whatsapp/sendproductlist" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "phoneNumber": "+12025550188" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "headerTextMessage": "New this week",
    "textMessage": "Here are three picks we think you will like.",
    "productList": [
      { "catalogId": "184467290011", "productRetailerId": "TEE-BLUE-M" },
      { "catalogId": "184467290011", "productRetailerId": "TEE-GREY-M" },
      { "catalogId": "184467290011", "productRetailerId": "CAP-BLK" }
    ]
  }'

Response 200
{ "success": true }

Send a Telegram text message

POST/v1/messages/telegram/sendtext

The contact must already exist in WhautoChat, which happens when the person messages your Telegram bot.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing Telegram contact

workspaceobjectrequired

{ "id": "..." }: the workspace whose Telegram bot sends it

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact.id`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Telegram Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/telegram/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tg93NcWe1R" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Thanks for reaching out. A team member will reply shortly."
  }'

Response 200
{ "success": true }

Send Telegram media

POST/v1/messages/telegram/sendmedia

Sends an image, video or document to an existing Telegram contact.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing Telegram contact

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the file

mimeTypestringrequired

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Telegram Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/telegram/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tg93NcWe1R" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/images/menu.png",
    "mimeType": "image/png"
  }'

Response 200
{ "success": true }

Send a Telegram message with buttons

POST/v1/messages/telegram/sendtemplate

Sends a message with buttons and an optional media header to an existing Telegram contact.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing Telegram contact

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

buttonsarrayrequired

At least one button

headerTypestring

Set it to add a media header

mediaUrlstringwith headerType

Public URL of the header file

mimeTypestringwith headerType

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Telegram Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/telegram/sendtemplate" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tg93NcWe1R" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Your order has shipped.",
    "buttons": [
      { "type": "web_url", "title": "Track order", "url": "https://example.com/track/1042" }
    ]
  }'

Response 200
{ "success": true }

Send an Instagram text message

POST/v1/messages/instagram/sendtext

The contact must already exist in WhautoChat, which happens when the person messages your Instagram account.

Body parameters

contactobjector recepient

{ "id": "..." }. See addressing.

recepientobjector contact

{ "username": "..." }: the contact's Instagram username

workspaceobjectrequired

{ "id": "..." }: the workspace whose Instagram account sends it

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact` or `recepient`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No Instagram contact has that username. Get the contact to start the conversation first.
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Instagram Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/instagram/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "username": "maria.lopez.studio" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Hi Maria, your class pass is ready to use."
  }'

Response 200
{ "success": true }

Send Instagram media

POST/v1/messages/instagram/sendmedia

Sends an image, video or document to an existing Instagram contact.

Body parameters

contactobjector recepient

{ "id": "..." }

recepientobjector contact

{ "username": "..." }

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the file

mimeTypestringrequired

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No Instagram contact has that username
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Instagram Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/instagram/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "username": "maria.lopez.studio" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/images/timetable.jpg",
    "mimeType": "image/jpeg"
  }'

Response 200
{ "success": true }

Send an Instagram generic template

POST/v1/messages/instagram/sendtemplate

Body parameters

contactobjector recepient

{ "id": "..." }

recepientobjector contact

{ "username": "..." }

workspaceobjectrequired

{ "id": "..." }

elementsarrayrequired

At least one element. Passed to Instagram as the elements of a generic template.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing or `elements` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No Instagram contact has that username
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Instagram Template Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/instagram/sendtemplate" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Ig27PwQs5N" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "elements": [
      {
        "title": "Spring yoga retreat",
        "subtitle": "Three days, from USD 450",
        "image_url": "https://example.com/images/retreat.jpg",
        "buttons": [
          { "type": "web_url", "url": "https://example.com/retreat", "title": "Book now" }
        ]
      }
    ]
  }'

Response 200
{ "success": true }

Send a TikTok text message

POST/v1/messages/tiktok/sendtext

The contact must already exist in WhautoChat, which happens when the person messages your TikTok account.

Body parameters

contactobjector recepient

{ "id": "..." }. See addressing.

recepientobjector contact

{ "tikTokUserId": "..." }: the contact's TikTok user ID

workspaceobjectrequired

{ "id": "..." }: the workspace whose TikTok account sends it

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact` or `recepient`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No TikTok contact has that user ID. Get the contact to start the conversation first.
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send TikTok Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/tiktok/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tt51RbVz8K" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Thanks for your message. Your discount code is SPRING15."
  }'

Response 200
{ "success": true }

Send a TikTok image

POST/v1/messages/tiktok/sendmedia

Sends an image. The file is always sent to TikTok as an image.

Body parameters

contactobjector recepient

{ "id": "..." }

recepientobjector contact

{ "tikTokUserId": "..." }

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the image

mimeTypestringrequired

For example image/jpeg or image/png

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No TikTok contact has that user ID
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send TikTok Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/tiktok/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tt51RbVz8K" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/images/size-guide.png",
    "mimeType": "image/png"
  }'

Response 200
{ "success": true }

Send a TikTok Q&A button card

POST/v1/messages/tiktok/sendqabuttoncard

Sends a Q&A card: a question with options the person can tap, shown as buttons. To show the options as text links, use the text link card.

Body parameters

contactobjector recepient

{ "id": "..." }

recepientobjector contact

{ "tikTokUserId": "..." }

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The question or message text

buttonsstring[]required

The option labels. At least one.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing or `buttons` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No TikTok contact has that user ID
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send TikTok Q&A Button Card" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/tiktok/sendqabuttoncard" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Tt51RbVz8K" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "What can we help you with?",
    "buttons": ["Order status", "Returns", "Talk to a person"]
  }'

Response 200
{ "success": true }

Send a TikTok Q&A text link card

POST/v1/messages/tiktok/sendqatextlinkcard

Same as the button card, with the same body, but the options are shown as text links.

Body parameters

contactobjector recepient

{ "id": "..." }

recepientobjector contact

{ "tikTokUserId": "..." }

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The question or message text

buttonsstring[]required

The option labels. At least one.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing or `buttons` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No TikTok contact has that user ID
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send TikTok Q&A Text Link Card" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/tiktok/sendqatextlinkcard" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recepient": { "tikTokUserId": "7312450098812345678" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Which size are you looking for?",
    "buttons": ["Small", "Medium", "Large"]
  }'

Response 200
{ "success": true }

Send a Messenger text message

POST/v1/messages/messenger/sendtext

The contact must already exist in WhautoChat, which happens when the person messages your Facebook Page.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing Messenger contact

workspaceobjectrequired

{ "id": "..." }: the workspace whose Facebook Page sends it

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact.id`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Messenger Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/messenger/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Ms40JdKa7F" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Your table for two is booked for 19:30 tonight."
  }'

Response 200
{ "success": true }

Send Messenger media

POST/v1/messages/messenger/sendmedia

Sends an image, video or document to an existing Messenger contact.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing Messenger contact

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the file. image/gif is sent as an image on Messenger.

mimeTypestringrequired

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Messenger Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/messenger/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Ms40JdKa7F" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/images/dinner-menu.jpg",
    "mimeType": "image/jpeg"
  }'

Response 200
{ "success": true }

Send a Messenger generic template

POST/v1/messages/messenger/sendtemplate

Body parameters

contactobjector recepient

{ "id": "..." }: an existing Messenger contact

recepientobjector contact

{ "messengerId": "..." }: the contact's Messenger ID, used instead of contact

workspaceobjectrequired

{ "id": "..." }

elementsarrayrequired

At least one element. Passed to Messenger as the elements of a generic template.

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing or `elements` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Contact not found in WhautoChat, ..." }`	No Messenger contact matches `recepient.messengerId`. Get the contact to start the conversation first.
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Messenger Template Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/messenger/sendtemplate" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Ms40JdKa7F" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "elements": [
      {
        "title": "Weekend brunch",
        "subtitle": "Saturday and Sunday, 10:00 to 14:00",
        "image_url": "https://example.com/images/brunch.jpg",
        "buttons": [
          { "type": "web_url", "url": "https://example.com/book", "title": "Book a table" }
        ]
      }
    ]
  }'

Response 200
{ "success": true }

Send a live chat text message

POST/v1/messages/website/sendtext

Website live chat messages go to visitors who have chatted with you through your website widget.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing live chat contact

workspaceobjectrequired

{ "id": "..." }: the workspace that owns the widget

textMessagestringrequired

The message text

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact.id`, `workspace.id` or `textMessage` is missing
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Website Text Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/website/sendtext" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Wb62HtYu3M" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "textMessage": "Thanks for waiting. Your refund was issued today."
  }'

Response 200
{ "success": true }

Send live chat media

POST/v1/messages/website/sendmedia

Sends an image, video or document to an existing live chat contact.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing live chat contact

workspaceobjectrequired

{ "id": "..." }

mediaUrlstringrequired

Public URL of the file

mimeTypestringrequired

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	A required field is missing
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Website Media Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/website/sendmedia" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Wb62HtYu3M" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "mediaUrl": "https://example.com/files/refund-receipt.pdf",
    "mimeType": "application/pdf"
  }'

Response 200
{ "success": true }

Send a live chat message with buttons

POST/v1/messages/website/sendtemplate

Sends a message with buttons and an optional header to an existing live chat contact.

Body parameters

contactobjectrequired

{ "id": "..." }: an existing live chat contact

workspaceobjectrequired

{ "id": "..." }

textMessagestringrequired

The message body

buttonsarrayrequired

At least one button

headerTypestring

The header type

headerTextMessagestring

Header text

mediaUrlstring

Public URL of a header file

mimeTypestringwith mediaUrl

The file's MIME type

scheduleDateTimestring

ISO 8601 date and time to send later

200 OK: { "success": true }, the message is queued.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`contact.id`, `workspace.id` or `textMessage` is missing, or `buttons` is empty
`400`	`{ "error": "Invalid Contact" }`	`contact.id` is not in your account
`400`	`{ "error": "Error downloading file from the URL" }`	WhautoChat could not download `mediaUrl`
`404`	`{ "error": "Invalid Workspace" }`	The workspace is not in your account
`500`	`{ "error": "Could not send Website Template Message" }`	The request could not be completed

Request
curl -X POST "https://api.whauto.chat/v1/messages/website/sendtemplate" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "id": "Wb62HtYu3M" },
    "workspace": { "id": "Wk7Hs2Pq9L" },
    "headerType": "text",
    "headerTextMessage": "Your refund",
    "textMessage": "Was this answer helpful?",
    "buttons": [
      { "type": "web_url", "title": "View order", "url": "https://example.com/orders/1042" }
    ]
  }'

Response 200
{ "success": true }

The contact, recepient and workspace objects​

Sending rules​

The message object​

List messages for a contact​

Send a WhatsApp text message​

Send WhatsApp media​

Send a WhatsApp template​

Send WhatsApp reply buttons​

Send a WhatsApp list message​

Send a WhatsApp link button​

Send a WhatsApp catalog​

Send a WhatsApp product​

Send a WhatsApp product list​

Send a Telegram text message​

Send Telegram media​

Send a Telegram message with buttons​

Send an Instagram text message​

Send Instagram media​

Send an Instagram generic template​

Send a TikTok text message​

Send a TikTok image​

Send a TikTok Q&A button card​

Send a TikTok Q&A text link card​

Send a Messenger text message​

Send Messenger media​

Send a Messenger generic template​

Send a live chat text message​

Send live chat media​

Send a live chat message with buttons​

The contact, recepient and workspace objects

Sending rules

The message object

List messages for a contact

Send a WhatsApp text message

Send WhatsApp media

Send a WhatsApp template

Send WhatsApp reply buttons

Send a WhatsApp list message

Send a WhatsApp link button

Send a WhatsApp catalog

Send a WhatsApp product

Send a WhatsApp product list

Send a Telegram text message

Send Telegram media

Send a Telegram message with buttons

Send an Instagram text message

Send Instagram media

Send an Instagram generic template

Send a TikTok text message

Send a TikTok image

Send a TikTok Q&A button card

Send a TikTok Q&A text link card

Send a Messenger text message

Send Messenger media

Send a Messenger generic template

Send a live chat text message

Send live chat media

Send a live chat message with buttons