Send messages | Tusk WhatsApp API

Send a text message

POST/v1/whatsapp/sessions/{sessionId}/messages/send-text

Sends a text message.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`text`required	string	The message text.
`mentions`	string[]	Chat ids to @mention. The text must also contain the `@number` token.
`linkPreview`	boolean	Whether to attach a preview for links in the text.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-text" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "text": "Hello from Tusk WhatsApp!"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send an image

POST/v1/whatsapp/sessions/{sessionId}/messages/send-image

Sends an image. Provide the file as a public url or as base64.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`url`	string	A public URL of the image. Send either `url` or `base64`.
`base64`	string	The image as a base64 string. Send either `url` or `base64`.
`mimetype`	string	The media type, for example image/jpeg. Recommended with base64.
`filename`	string	A file name.
`caption`	string	Text shown with the media.
`mentions`	string[]	Chat ids to @mention. The text must also contain the `@number` token.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-image" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "url": "https://example.com/photo.jpg",
  "caption": "Your order"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a video

POST/v1/whatsapp/sessions/{sessionId}/messages/send-video

Sends a video. Provide the file as a public url or as base64.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`url`	string	A public URL of the video. Send either `url` or `base64`.
`base64`	string	The video as a base64 string. Send either `url` or `base64`.
`mimetype`	string	The media type, for example image/jpeg. Recommended with base64.
`filename`	string	A file name.
`caption`	string	Text shown with the media.
`mentions`	string[]	Chat ids to @mention. The text must also contain the `@number` token.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-video" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "url": "https://example.com/clip.mp4",
  "caption": "Your order"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send an audio or voice message

POST/v1/whatsapp/sessions/{sessionId}/messages/send-audio

Sends an audio file or a voice message. Provide the file as a public url or as base64.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`url`	string	A public URL of the audio. Send either `url` or `base64`.
`base64`	string	The audio as a base64 string. Send either `url` or `base64`.
`mimetype`	string	The media type, for example image/jpeg. Recommended with base64.
`filename`	string	A file name.
`caption`	string	Text shown with the media.
`mentions`	string[]	Chat ids to @mention. The text must also contain the `@number` token.
`quotedMessageId`	string	Send as a reply to this message id.
`ptt`	boolean	Send as a voice note (push to talk).

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-audio" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "url": "https://example.com/voice.ogg"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a document

POST/v1/whatsapp/sessions/{sessionId}/messages/send-document

Sends a document or any file. Provide the file as a public url or as base64.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`url`	string	A public URL of the file. Send either `url` or `base64`.
`base64`	string	The file as a base64 string. Send either `url` or `base64`.
`mimetype`	string	The media type, for example image/jpeg. Recommended with base64.
`filename`	string	A file name.
`caption`	string	Text shown with the media.
`mentions`	string[]	Chat ids to @mention. The text must also contain the `@number` token.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-document" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf",
  "caption": "Your order"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a location

POST/v1/whatsapp/sessions/{sessionId}/messages/send-location

Sends a map location.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`latitude`required	number	Latitude in degrees.
`longitude`required	number	Longitude in degrees.
`description`	string	A name for the place.
`address`	string	A street address.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-location" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "latitude": -1.2921,
  "longitude": 36.8219,
  "description": "Our shop",
  "address": "Nairobi, Kenya"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a contact card

POST/v1/whatsapp/sessions/{sessionId}/messages/send-contact

Sends a contact card.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`contactName`required	string	The name on the card.
`contactNumber`required	string	The phone number on the card.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-contact" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "contactName": "Support",
  "contactNumber": "254700000003"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a poll

POST/v1/whatsapp/sessions/{sessionId}/messages/send-poll

Sends a native WhatsApp poll.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`name`required	string	The poll question.
`options`required	string[]	The answer options.
`allowMultipleAnswers`	boolean	Let people pick more than one option.
`quotedMessageId`	string	Send as a reply to this message id.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-poll" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "name": "Pick a delivery slot",
  "options": [
    "Morning",
    "Afternoon"
  ],
  "allowMultipleAnswers": false
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Send a template

POST/v1/whatsapp/sessions/{sessionId}/messages/send-template

Renders one of your stored templates and sends it as a text message. Give templateId or templateName.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The recipient chat id.
`templateId`	string	The template id. Send this or templateName.
`templateName`	string	The template name. Send this or templateId.
`vars`	object	Values for the `{{placeholder}}` tokens in the template.
`mentions`	string[]	Chat ids to @mention.
`linkPreview`	boolean	Whether to attach a link preview.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-template" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "templateName": "order-confirmation",
  "vars": {
    "customer": "Amina",
    "orderId": "1001"
  }
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Reply to a message

POST/v1/whatsapp/sessions/{sessionId}/messages/reply

Sends a text that quotes an earlier message.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The chat the message is in.
`quotedMessageId`required	string	The id of the message to reply to.
`text`required	string	The reply text.
`mentions`	string[]	Chat ids to @mention.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/reply" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "quotedMessageId": "3EB0A1B2C3D4E5F60789",
  "text": "Sure, on its way."
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Forward a message

POST/v1/whatsapp/sessions/{sessionId}/messages/forward

Forwards a message to another chat.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`fromChatId`required	string	The chat the message is in.
`toChatId`required	string	The chat to forward it to.
`messageId`required	string	The message to forward.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/forward" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fromChatId": "[email protected]",
  "toChatId": "[email protected]",
  "messageId": "3EB0A1B2C3D4E5F60789"
}'

201 Created

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

React to a message

POST/v1/whatsapp/sessions/{sessionId}/messages/react

Adds a reaction to a message, or removes it.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The chat the message is in.
`messageId`required	string	The message to react to.
`emoji`required	string	The reaction emoji. Send an empty string to remove your reaction.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/react" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "messageId": "3EB0A1B2C3D4E5F60789",
  "emoji": "👍"
}'

200 OK

{
  "success": true
}

Edit a sent message

POST/v1/whatsapp/sessions/{sessionId}/messages/edit

Edits the text of a message your number sent.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The chat the message is in.
`messageId`required	string	The message to edit.
`body`required	string	The new text.
`mentions`	string[]	Chat ids to @mention.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/edit" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "messageId": "3EB0A1B2C3D4E5F60789",
  "body": "Corrected text"
}'

200 OK

{
  "message_id": "3EB0A1B2C3D4E5F60789",
  "chat_id": "[email protected]",
  "timestamp": 1768469400
}

Delete a message

POST/v1/whatsapp/sessions/{sessionId}/messages/delete

Deletes a message.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`chatId`required	string	The chat the message is in.
`messageId`required	string	The message to delete.
`forEveryone`	boolean	Delete for everyone in the chat, not just for you.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/delete" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chatId": "[email protected]",
  "messageId": "3EB0A1B2C3D4E5F60789",
  "forEveryone": true
}'

200 OK

{
  "success": true
}

Send in bulk

POST/v1/whatsapp/sessions/{sessionId}/messages/send-bulk

Queues up to 100 messages to different recipients as one asynchronous batch and returns at once with 202 Accepted. Messages are sent one at a time with a pause between them. Poll the batch for progress, or cancel it.

Body
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`messages`required	object[]	Up to 100 items. Each has `chatId`, a `type` (`text`, `image`, `video`, `audio` or `document`), and `content`: `text` for text, or an object such as `image` with `url` or `base64`, plus an optional `caption` (up to 1024 characters). Text is up to 4096 characters. Optional `variables` are substituted into the text. Exact duplicate items are collapsed.
`batchId`	string	Your own batch id. Generated if omitted.
`options.delayBetweenMessages`	integer	Pause between messages in milliseconds, 1000 to 60000. Defaults to 3000.
`options.randomizeDelay`	boolean	Add a random 0 to 2 seconds to each pause. Defaults to true.
`options.stopOnError`	boolean	Stop the batch at the first failure. Defaults to false.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/send-bulk" \
  -H "X-API-Key: $TUSK_WA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "chatId": "[email protected]",
      "type": "text",
      "content": {
        "text": "Your order 1001 is ready."
      }
    },
    {
      "chatId": "[email protected]",
      "type": "text",
      "content": {
        "text": "Your order 1002 is ready."
      }
    }
  ],
  "options": {
    "delayBetweenMessages": 3000
  }
}'

202 Accepted

{
  "batchId": "batch_01",
  "status": "pending",
  "totalMessages": 2,
  "estimatedCompletionTime": "2026-01-15T09:31:00Z"
}

Get a batch's status

GET/v1/whatsapp/sessions/{sessionId}/messages/batch/{batchId}

Returns the progress of a bulk batch and the result for each recipient.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`batchId`required	path	The batch id returned by send-bulk.

curl "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/batch/batch_01" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "batchId": "batch_01",
  "status": "processing",
  "progress": {
    "total": 2,
    "sent": 1,
    "failed": 0,
    "pending": 1,
    "cancelled": 0
  },
  "results": [
    {
      "chatId": "[email protected]",
      "status": "sent",
      "messageId": "3EB0A1B2C3D4E5F60789",
      "sentAt": "2026-01-15T09:30:03Z"
    },
    {
      "chatId": "[email protected]",
      "status": "pending"
    }
  ],
  "startedAt": "2026-01-15T09:30:00Z"
}

Batch status is pending, processing, completed, cancelled or failed. Each result is pending, sent, failed or cancelled.

Cancel a batch

POST/v1/whatsapp/sessions/{sessionId}/messages/batch/{batchId}/cancel

Cancels a running batch. Messages already sent stay sent.

Parameters
Name	Type	Description
`sessionId`required	path	The session id from the sessions endpoints.
`batchId`required	path	The batch to cancel.

curl -X POST "https://api.tuskmail.africa/v1/whatsapp/sessions/$SESSION_ID/messages/batch/batch_01/cancel" \
  -H "X-API-Key: $TUSK_WA_KEY"

200 OK

{
  "batchId": "batch_01",
  "status": "cancelled",
  "progress": {
    "total": 2,
    "sent": 1,
    "failed": 0,
    "pending": 0,
    "cancelled": 1
  }
}