📤 Send messages

We consider that you’ve run docker container and authenticated the session with QR code.

If you haven’t yet - please follow the steps from ⚡ Quick Start.

Features

WEBJSNOWEBGOWS
POST /api/sendText✔️✔️✔️
POST /api/sendSeen✔️✔️✔️
PUT /api/{session}/chats/{chatId}/messages/{messageId}✔️✔️
DELETE /api/{session}/chats/{chatId}/messages/{messageId}✔️✔️
POST /api/sendImage✔️✔️✔️
POST /api/sendFile✔️✔️✔️
POST /api/sendVoice✔️✔️✔️
POST /api/sendVideo✔️✔️✔️
POST /api/sendButtons✔️
POST /api/sendPoll#189✔️
POST /api/forwardMessage✔️
#588
✔️
POST /api/sendLocation✔️✔️
POST /api/sendLinkPreview✔️
POST /api/startTyping✔️✔️✔️
POST /api/stopTyping✔️✔️✔️
POST /api/{session}/presence✔️✔️✔️
POST /api/reaction✔️✔️✔️
POST /api/star✔️✔️
GET /api/sendContactVcard✔️
GET /api/messages✔️✔️¹
GET /api/checkNumberStatus✔️✔️

  1. NOWEB - you need to Enable Store to get chats, contacts and messages

If you see the feature is not available in the above list, please create a feature request or leave “+1” comment on the existing one.


Fields

There are common fields that you can find in almost all requests:

{
  "session": "default",
  "chatId": "12132132130@c.us",
  "file": "..."
}

session

session - a session name from which account you’re sending the message. We use default in the examples.

  • Core version supports only default session.
  • Plus allows you to run multiple sessions inside one container to save your memory and CPU resources!

Read more about multiple sessions →

chatId

chatId - it’s a phone number or Group identifier where you’re sending the message.

  • 123123123@c.us Phone numbers accounts - international phone number without + at the start and add @c.us at the end. For phone number 12132132131 the chatId is 12132132131@c.us
  • 123123123@s.whatsapp.net can also appear in internal data for NOWEB, just convert it to @c.us to work with that properly. Kindly don’t use it in chatId when sending messages
  • 12312312123133@g.us - Groups uses random number with @g.us at the end.
  • 123123123@lid - is a hidden user ID, each user has a regular ID along with a hidden one. WhatsApp added that type of ID along with communities functionality.
  • 123123123@newsletter - for 📰 WhatsApp Channels.

👉 To get the actual chatId for 🇧🇷 Brazilian phone number - use chatId field from Check phone number exists response.

Read more about error sending text to half of Brazilian numbers (every number registered before 2012) ->

file

When sending media (images, voice, files) you can either use:

See the list of engines that support the feature ->.

reply_to

You can add reply_to field in order to reply on certain message.

{
  "chatId": "11111111111@c.us",
  ...
  "reply_to": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA"
}

reply_to is available in all messages:

Send seen

If you get a new message via 🔄 Webhooks and want to reply to that message, you need to first send that you’ve seen the message (double green tick) - ⚠️ How to Avoid Blocking

POST /api/sendSeen

Send seen for direct message:

Body
{
  "session": "default",
  "chatId": "11111111111@c.us",
  "messageId": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA"
}

Send seen for Group Message you need to provide participant field:

Body
{
  "session": "default",
  "chatId": "11111111111@g.us",
  "messageId": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "participant": "33333333333@c.us"
}

Send text

Use API to send text messages to the chat.

POST /api/sendText
Body
{
  "session": "default",
  "chatId": "12132132130@c.us",
  "text": "Hi there!",
  "linkPreview": true
}

Here’s some additional options:

  • reply_to: false_1111@c.us_AAA - to reply on a message
  • mentions - to mention a contact in a group
  • linkPreview: false - to disable preview generation for links in the message

Reply on message

To reply on a message - add reply_to field:

Body
{
  "session": "default",
  "chatId": "11111111111@c.us",
  "reply_to": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "text": "Reply text"
}

Mention contact

If you send a message in a group and want to mention a participant in the message - use mentions field for that in POST /api/sendText request.

Please note that you MUST mention a number in the text as well in the format @2132132130 and also mention it in mentions in format 2132132130@c.us

Body
{
  "session": "default",
  "chatId": "12132132130@c.us",
  "text": "Hi there! @2132132130",
  "mentions": [
    "2132132130@c.us"
  ]
}

Send image

Use API to send images to the chat.

POST /api/sendImage

You can send images in two ways:

  1. Provide a URL for the image.
  2. Encode the whole file content into BASE64 and send it in the request body.

Send voice

Use API to send voice messages to the chat.

POST /api/sendVoice

Convert file before sending

Make sure your file has OPUS encoding and packed in OGG container. You can convert to this using ffmpeg ( there’s many libs for that in popular languages).

ffmpeg -i input.mp3 -c:a libopus -b:a 32k -ar 48000 -ac 1 output.opus

You can send voice messages in two ways:

  1. Provide a URL for the voice.
  2. Encode the whole file content into BASE64 and send it in the request body.

Send video

POST /api/sendVideo

Convert file before sending

Make sure your file has mp4 using libx264 format.

ffmpeg -i input_video.mp4 -c:v libx264 -map 0 -movflags +faststart output_video.mp4

-map 0 -movflags +faststart options required for thumbnail generation.

WEBJS - use :chrome image

If you’re using WEBJS (default engine) - make sure to use devlikeapro/waha-plus:chrome docker image.

Read more about Docker images and engines →.

Use API to send a video to a chat.

You can send video messages in two ways:

  1. Provide a URL for the file and the API will download it and send it in the request body.
  2. Provide the file as a BASE64 string in the request body.

Send file

Use API to send a file (as a document/attachment) to a chat.

POST /api/sendFile

You can send files in two ways:

  1. Provide a URL for the file.
  2. Encode the whole file content into BASE64 and send it in the request body.

Forward Message

You can forward a message to another chat (that you chatted before, otherwise it may fail):

POST /api/forwardMessage
Body
{
  "chatId": "11111111111@c.us",
  "messageId": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "session": "default"
}

Edit message

You can edit text messages or “caption” in media messages.

PUT /api/{session}/chats/{chatId}/messages/{messageId}

👉 Remember to escape @ in chatId and messageId with %40.

So if you want to edit true_123@c.us_AAA message in 123@c.us chat you need to send request to:

PUT /api/{session}/chats/123%40c.us/messages/true_123%40c.us_AAA
Body
{
  "text": "Hello, world!",
  "linkPreview": true
}
  • linkPreview: false - to disable preview generation for links in the message

Delete message

You can delete messages from the chat.

DELETE /api/{session}/chats/{chatId}/messages/{messageId}

👉 Remember to escape @ in chatId and messageId with %40.

So if you want to delete true_123@c.us_AAA message in 123@c.us chat you need to send request to:

DELETE /api/{session}/chats/123%40c.us/messages/true_123%40c.us_AAA

Send poll

We have a dedicated page 📶 Polls!

alt

POST /api/sendPoll

The request body is pretty simple:

Body
{
  "session": "default",
  "chatId": "123123123@c.us",
  "poll": {
    "name": "How are you?",
    "options": [
      "Awesome!",
      "Good!",
      "Not bad!"
    ],
    "multipleAnswers": false
  }
}

Add a reaction

Use API to add a reaction to a message.

PUT /api/reaction

Use PUT method

Reaction API uses PUT, not POST request! Please make sure you send right request.

Body
{
  "messageId": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "reaction": "👍",
  "session": "default"
}

To remove reaction from a message - send empty string in the reaction request:

Body
{
  "messageId": "false_11111111111@c.us_AAAAAAAAAAAAAAAAAAAA",
  "reaction": "",
  "session": "default"
}

Star and unstar message

Use API to star or unstar a message.

PUT /api/star

Use PUT method

Star API uses PUT, not POST request! Please make sure you send right request.

Star:

Body
{
  "messageId": "false_71111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "chatId": "71111111111@c.us",
  "star": true,
  "session": "default"
}

Unstar:

Body
{
  "messageId": "false_71111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "chatId": "71111111111@c.us",
  "star": false,
  "session": "default"
}

Send contact (vcard)

Use to send contact (vcard)

POST /api/sendContactVcard

You can send contacts in ways:

Send location

POST /api/sendLocation
{
  "chatId": "11111111111@c.us",
  "latitude": 38.8937255,
  "longitude": -77.0969763,
  "title": "Our office",
  "session": "default"
}

Send Status (aka stories)

You can send statuses (aka stories)!

Check out 🟢 Status page.

Send messages to Channels

You can send messages to channels!

Check out 📢 Channels page.

Send Buttons

Buttons do not work at the moment!

Buttons are fragile creatures and may not work as expected. Please consider adding fallback logic using text/poll messages.

alt

You can send interactive message (aka buttons) using

POST /api/sendButtons
{
  "chatId": "11111111111@c.us",
  "header": "How are you?",
  "headerImage": {
    "mimetype": "image/jpeg",
    "filename": "filename.jpg",
    "url": "https://github.com/devlikeapro/waha/raw/core/examples/waha.jpg"
  },
  "body": "Tell us how are you please 🙏",
  "footer": "If you have any questions, please send it in the chat",
  "buttons": [
    {
      "type": "reply",
      "text": "I am good!"
    },
    {
      "type": "call",
      "text": "Call us",
      "phoneNumber": "+1234567890"
    },
    {
      "type": "copy",
      "text": "Copy code",
      "copyCode": "4321"
    },
    {
      "type": "url",
      "text": "How did you do that?",
      "url": "https://waha.devlike.pro"
    }
  ],
  "session": "default"
}

👉 headerImage is available only in ➕ WAHA Plus

Buttons

Here’s available buttons you can use in buttons: