Skip to main content

Messages

Send various types of messages through WhatsApp.

Send Text Message​

POST /api/v1/sessions/{session_id}/messages/text

Request Body​

{
  "to": "628123456789",
  "text": "Hello from WA-RS!"
}

Response​

{
  "message_id": "3EB0ABC123...",
  "timestamp": 1700000000,
  "to": "628123456789@s.whatsapp.net"
}

Example​

curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/text \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "text": "Hello!"
  }'

Send Image​

POST /api/v1/sessions/{session_id}/messages/image

Request Body​

{
  "to": "628123456789",
  "image": {
    "url": "https://example.com/image.jpg"
  },
  "caption": "Check this out!"
}

Or with base64:

{
  "to": "628123456789",
  "image": {
    "data": "/9j/4AAQSkZJRg...",
    "mimetype": "image/jpeg"
  },
  "caption": "Check this out!"
}

Send Video​

POST /api/v1/sessions/{session_id}/messages/video

Request Body​

{
  "to": "628123456789",
  "video": {
    "url": "https://example.com/video.mp4"
  },
  "caption": "Watch this!"
}

Send Audio​

POST /api/v1/sessions/{session_id}/messages/audio

Request Body​

{
  "to": "628123456789",
  "audio": {
    "url": "https://example.com/audio.mp3"
  },
  "ptt": true
}
FieldDescription
pttPush-to-talk (voice note) if true

Send Document​

POST /api/v1/sessions/{session_id}/messages/document

Request Body​

{
  "to": "628123456789",
  "document": {
    "url": "https://example.com/document.pdf"
  },
  "filename": "report.pdf"
}

Send Sticker​

POST /api/v1/sessions/{session_id}/messages/sticker

Request Body​

{
  "to": "628123456789",
  "sticker": {
    "url": "https://example.com/sticker.webp"
  }
}

Send Location​

POST /api/v1/sessions/{session_id}/messages/location

Request Body​

{
  "to": "628123456789",
  "latitude": -6.2088,
  "longitude": 106.8456,
  "name": "Jakarta",
  "address": "Jakarta, Indonesia"
}

Send Contact​

POST /api/v1/sessions/{session_id}/messages/contact

Request Body​

{
  "to": "628123456789",
  "contact": {
    "display_name": "John Doe",
    "phones": [
      {
        "number": "+628123456789",
        "phone_type": "CELL"
      }
    ]
  }
}

Send Poll​

Create a poll with multiple options.

POST /api/v1/sessions/{session_id}/messages/poll

Request Body​

{
  "to": "628123456789",
  "name": "What's your favorite color?",
  "options": ["Red", "Blue", "Green", "Yellow"],
  "selectable_count": 1
}
FieldTypeRequiredDescription
tostringYesRecipient JID
namestringYesPoll question
optionsarrayYesList of poll options
selectable_countnumberNoMax selectable options (0 = unlimited)
reply_tostringNoMessage ID to reply to

Example​

curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/poll \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "name": "What is your favorite color?",
    "options": ["Red", "Blue", "Green"],
    "selectable_count": 1
  }'

Send Buttons​

Send a message with interactive buttons.

POST /api/v1/sessions/{session_id}/messages/buttons

Request Body​

{
  "to": "628123456789",
  "content_text": "Please choose an option",
  "footer": "Powered by WA-RS",
  "buttons": [
    {
      "button_id": "btn_1",
      "display_text": "Option 1"
    },
    {
      "button_id": "btn_2",
      "display_text": "Option 2"
    }
  ],
  "header_text": "Main Menu"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
content_textstringYesBody text
footerstringNoFooter text
buttonsarrayYesList of buttons (max 3)
header_textstringNoHeader text
reply_tostringNoMessage ID to reply to

Send List​

Send a message with a selectable list menu.

POST /api/v1/sessions/{session_id}/messages/list

Request Body​

{
  "to": "628123456789",
  "title": "Main Menu",
  "description": "Please select an option",
  "button_text": "View Options",
  "sections": [
    {
      "title": "Category 1",
      "rows": [
        {
          "row_id": "row_1",
          "title": "Item 1",
          "description": "Description for item 1"
        },
        {
          "row_id": "row_2",
          "title": "Item 2",
          "description": "Description for item 2"
        }
      ]
    }
  ],
  "footer": "Powered by WA-RS"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
titlestringYesList title
descriptionstringYesBody text
button_textstringYesButton label to open the list
sectionsarrayYesList sections with rows
footerstringNoFooter text
reply_tostringNoMessage ID to reply to

Send Interactive​

Send a native flow interactive message.

POST /api/v1/sessions/{session_id}/messages/interactive

Request Body​

{
  "to": "628123456789",
  "body_text": "Choose an action",
  "footer_text": "Powered by WA-RS",
  "buttons": [
    {
      "name": "quick_reply",
      "button_params_json": "{\"display_text\":\"Click Me\",\"id\":\"btn1\"}"
    }
  ]
}
FieldTypeRequiredDescription
tostringYesRecipient JID
body_textstringYesBody text
footer_textstringNoFooter text
buttonsarrayYesNative flow button items
reply_tostringNoMessage ID to reply to

Send Newsletter Admin Invite​

Send a newsletter admin invitation.

POST /api/v1/sessions/{session_id}/messages/newsletter-admin-invite

Request Body​

{
  "to": "628123456789",
  "newsletter_jid": "120363000000000000@newsletter",
  "newsletter_name": "My Newsletter",
  "caption": "Join as admin!",
  "invite_expiration": 1700000000
}
FieldTypeRequiredDescription
tostringYesRecipient JID
newsletter_jidstringYesNewsletter JID
newsletter_namestringYesNewsletter name
captionstringNoInvitation message
invite_expirationnumberNoExpiration timestamp
reply_tostringNoMessage ID to reply to

Send Newsletter Follower Invite​

Send a newsletter follower invitation.

POST /api/v1/sessions/{session_id}/messages/newsletter-follower-invite

Request Body​

{
  "to": "628123456789",
  "newsletter_jid": "120363000000000000@newsletter",
  "newsletter_name": "My Newsletter",
  "caption": "Follow this newsletter!"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
newsletter_jidstringYesNewsletter JID
newsletter_namestringYesNewsletter name
captionstringNoInvitation message
reply_tostringNoMessage ID to reply to

Send Order​

Send a business order message.

POST /api/v1/sessions/{session_id}/messages/order

Request Body​

{
  "to": "628123456789",
  "order_id": "ORD-001",
  "item_count": 3,
  "status": "inquiry",
  "message": "I'd like to order these items",
  "order_title": "My Order",
  "total_amount_1000": 50000000,
  "total_currency_code": "USD"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
order_idstringYesOrder ID
item_countnumberNoNumber of items
statusstringNoinquiry, accepted, declined
messagestringNoOrder message text
order_titlestringNoOrder title
seller_jidstringNoSeller JID
tokenstringNoOrder token
total_amount_1000numberNoTotal amount * 1000
total_currency_codestringNoISO 4217 currency code
reply_tostringNoMessage ID to reply to

Send Invoice​

Send a business invoice message.

POST /api/v1/sessions/{session_id}/messages/invoice

Request Body​

{
  "to": "628123456789",
  "note": "Invoice for services rendered",
  "token": "inv-token-123",
  "attachment_type": "pdf",
  "attachment_mimetype": "application/pdf"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
notestringNoInvoice note
tokenstringNoInvoice token
attachment_typestringNoimage or pdf
attachment_mimetypestringNoMIME type of attachment
reply_tostringNoMessage ID to reply to

Send Payment Invite​

Send a payment service invitation.

POST /api/v1/sessions/{session_id}/messages/payment-invite

Request Body​

{
  "to": "628123456789",
  "service_type": 0
}
FieldTypeRequiredDescription
tostringYesRecipient JID
service_typenumberNoPayment service type (integer)
reply_tostringNoMessage ID to reply to

Pin Message​

Pin or unpin a message in a chat.

POST /api/v1/sessions/{session_id}/messages/pin

Request Body​

{
  "chat": "628123456789@s.whatsapp.net",
  "message_id": "3EB0ABC123...",
  "duration_seconds": 86400
}
FieldTypeRequiredDescription
chatstringYesChat JID
message_idstringYesMessage ID to pin
duration_secondsnumberNoPin duration (default: 86400)

Pin Durations​

ValueDuration
0Unpin
8640024 hours
6048007 days
259200030 days

Example​

# Pin for 24 hours
curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/pin \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat": "628123456789@s.whatsapp.net",
    "message_id": "3EB0ABC123...",
    "duration_seconds": 86400
  }'

# Unpin
curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/pin \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat": "628123456789@s.whatsapp.net",
    "message_id": "3EB0ABC123...",
    "duration_seconds": 0
  }'

Forward Message​

Forward a message to another chat.

POST /api/v1/sessions/{session_id}/messages/forward

Request Body​

{
  "to": "628987654321@s.whatsapp.net",
  "text": "Forwarded content here"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
textstringYesText content to forward
reply_tostringNoMessage ID to reply to

Edit Message​

POST /api/v1/sessions/{session_id}/messages/edit

Request Body​

{
  "to": "628123456789",
  "message_id": "3EB0ABC123...",
  "text": "Edited message text"
}

Send Reaction​

POST /api/v1/sessions/{session_id}/messages/react

Request Body​

{
  "to": "628123456789",
  "message_id": "3EB0ABC123...",
  "emoji": "👍"
}

To remove reaction, send empty emoji:

{
  "to": "628123456789",
  "message_id": "3EB0ABC123...",
  "emoji": ""
}

Revoke Message​

Delete a message for everyone in the chat.

POST /api/v1/sessions/{session_id}/messages/revoke

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "message_id": "3EB0ABC123..."
}

To revoke another user's message as a group admin:

{
  "to": "123456789-1234567890@g.us",
  "message_id": "3EB0ABC123...",
  "original_sender": "628987654321@s.whatsapp.net"
}

Example​

curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/revoke \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789@s.whatsapp.net",
    "message_id": "3EB0ABC123..."
  }'

Mark as Read​

Send read receipts for messages.

POST /api/v1/sessions/{session_id}/messages/read

Request Body​

{
  "chat_jid": "628123456789@s.whatsapp.net",
  "message_ids": ["3EB0ABC123...", "3EB0DEF456..."]
}

For group messages, include the sender:

{
  "chat_jid": "123456789-1234567890@g.us",
  "sender": "628987654321@s.whatsapp.net",
  "message_ids": ["3EB0ABC123..."]
}

Example​

curl -X POST http://localhost:3451/api/v1/sessions/my-session/messages/read \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_jid": "628123456789@s.whatsapp.net",
    "message_ids": ["3EB0ABC123..."]
  }'

Send Poll Update (Vote)​

Submit a vote on an existing poll.

POST /api/v1/sessions/{session_id}/messages/poll-update

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "poll_message_id": "3EB0ABC123...",
  "selected_options": ["sha256-hash-of-option"],
  "enc_iv": "base64-encoded-iv",
  "enc_payload": "base64-encoded-payload"
}
FieldTypeRequiredDescription
tostringYesChat JID where the poll was created
poll_message_idstringYesMessage ID of the poll
selected_optionsarrayYesSHA-256 hashes of selected option texts
enc_ivstringNoEncryption IV (base64)
enc_payloadstringNoEncryption payload (base64)

Send Buttons Response​

Send a response to a buttons message.

POST /api/v1/sessions/{session_id}/messages/buttons-response

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "selected_button_id": "btn_1",
  "selected_display_text": "Option 1"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
selected_button_idstringYesID of the selected button
selected_display_textstringYesDisplay text of the selected button
reply_tostringNoMessage ID to reply to

Send List Response​

Send a response to a list message.

POST /api/v1/sessions/{session_id}/messages/list-response

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "title": "Category 1",
  "selected_row_id": "row_1",
  "description": "Description for the selection"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
titlestringYesTitle of the selection
selected_row_idstringYesID of the selected row
descriptionstringNoDescription of the selection
reply_tostringNoMessage ID to reply to

Send Interactive Response​

Send a response to a native flow interactive message.

POST /api/v1/sessions/{session_id}/messages/interactive-response

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "body_text": "Response body",
  "name": "quick_reply",
  "params_json": "{\"id\":\"btn1\"}",
  "version": 3
}
FieldTypeRequiredDescription
tostringYesRecipient JID
body_textstringNoResponse body text
namestringYesNative flow response name
params_jsonstringYesResponse parameters (JSON string)
versionnumberNoNative flow version (default: 3)
reply_tostringNoMessage ID to reply to

Send Highly Structured Message (HSM)​

Send a highly structured message (template).

POST /api/v1/sessions/{session_id}/messages/highly-structured

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "namespace": "your_namespace",
  "element_name": "template_name",
  "params": ["param1", "param2"],
  "fallback_lg": "en",
  "fallback_lc": "US"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
namespacestringYesTemplate namespace
element_namestringYesTemplate element name
paramsarrayNoTemplate parameters
fallback_lgstringNoFallback language
fallback_lcstringNoFallback locale
reply_tostringNoMessage ID to reply to

Send Template Button Reply​

Send a reply to a template button message.

POST /api/v1/sessions/{session_id}/messages/template-button-reply

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "selected_id": "btn_1",
  "selected_display_text": "Option 1",
  "selected_index": 0
}
FieldTypeRequiredDescription
tostringYesRecipient JID
selected_idstringYesID of the selected template button
selected_display_textstringYesDisplay text of the selected button
selected_indexnumberNoIndex of the selected button
reply_tostringNoMessage ID to reply to

Send Comment​

Send a comment on a message in a group or newsletter.

POST /api/v1/sessions/{session_id}/messages/comment

Request Body​

{
  "to": "120363000000000000@g.us",
  "text": "This is my comment",
  "target_message_id": "3EB0ABC123...",
  "target_chat_jid": "120363000000000000@g.us"
}
FieldTypeRequiredDescription
tostringYesGroup/newsletter JID
textstringYesComment text
target_message_idstringYesMessage ID being commented on
target_chat_jidstringNoChat JID of the target message

Send Scheduled Call​

Schedule a voice or video call in a group.

POST /api/v1/sessions/{session_id}/messages/scheduled-call

Request Body​

{
  "to": "120363000000000000@g.us",
  "scheduled_timestamp_ms": 1700000000000,
  "call_type": "voice",
  "title": "Weekly Team Sync"
}
FieldTypeRequiredDescription
tostringYesGroup JID
scheduled_timestamp_msnumberYesScheduled time (Unix ms)
call_typestringNovoice or video (default: voice)
titlestringNoCall title

Edit Scheduled Call​

Cancel or edit a scheduled call.

POST /api/v1/sessions/{session_id}/messages/scheduled-call-edit

Request Body​

{
  "to": "120363000000000000@g.us",
  "scheduled_call_message_id": "3EB0ABC123...",
  "edit_type": "cancel"
}
FieldTypeRequiredDescription
tostringYesGroup JID
scheduled_call_message_idstringYesMessage ID of the scheduled call
edit_typestringNocancel (default: cancel)

Send Payment​

Send a payment to a contact.

POST /api/v1/sessions/{session_id}/messages/send-payment

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "note": "Payment for services",
  "request_message_id": "3EB0ABC123...",
  "transaction_data": "{\"key\":\"value\"}"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
notestringNoPayment note
request_message_idstringNoOriginal payment request message ID
transaction_datastringNoTransaction data (JSON string)

Request Payment​

Send a payment request to a contact.

POST /api/v1/sessions/{session_id}/messages/request-payment

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "currency_code": "USD",
  "amount1000": 50000000,
  "note": "Payment for invoice #123",
  "expiry_timestamp": 1700086400
}
FieldTypeRequiredDescription
tostringYesRecipient JID
currency_codestringYesISO 4217 currency code
amount1000numberYesAmount in smallest unit * 1000
notestringNoPayment request note
expiry_timestampnumberNoRequest expiration timestamp

Cancel Payment Request​

Cancel a previously sent payment request.

POST /api/v1/sessions/{session_id}/messages/cancel-payment

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "request_message_id": "3EB0ABC123..."
}
FieldTypeRequiredDescription
tostringYesRecipient JID
request_message_idstringYesMessage ID of the payment request

Decline Payment Request​

Decline a received payment request.

POST /api/v1/sessions/{session_id}/messages/decline-payment

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "request_message_id": "3EB0ABC123..."
}
FieldTypeRequiredDescription
tostringYesRecipient JID
request_message_idstringYesMessage ID of the payment request

Send Newsletter Forward​

Forward a newsletter message to a contact or group.

POST /api/v1/sessions/{session_id}/messages/newsletter-forward

Request Body​

{
  "to": "628123456789@s.whatsapp.net",
  "text": "Check out this newsletter post",
  "newsletter_jid": "120363000000000000@newsletter",
  "server_message_id": 42,
  "newsletter_name": "My Newsletter",
  "content_type": "update"
}
FieldTypeRequiredDescription
tostringYesRecipient JID
textstringYesText content
newsletter_jidstringYesNewsletter JID
server_message_idnumberYesServer message ID from newsletter
newsletter_namestringNoNewsletter name
content_typestringNoupdate, update_card, link_card

Media Data Format​

All media endpoints accept either URL or base64:

URL Format​

{
  "url": "https://example.com/file.jpg"
}

Base64 Format​

{
  "data": "base64-encoded-data...",
  "mimetype": "image/jpeg"
}

Uploaded Format​

If you've already uploaded via the /media/upload endpoint:

{
  "url": "https://mmg.whatsapp.net/...",
  "direct_path": "/v/t62.7...",
  "media_key": "base64-key",
  "file_sha256": "base64-sha256",
  "file_enc_sha256": "base64-enc-sha256",
  "file_length": 12345,
  "mimetype": "image/jpeg"
}

Supported MIME Types​

TypeMIME Types
Imageimage/jpeg, image/png, image/webp
Videovideo/mp4, video/3gpp
Audioaudio/mpeg, audio/ogg, audio/wav
DocumentAny
Stickerimage/webp