Messages

Before sending, the token must be paired and live-connected:

{
  "paired": true,
  "connected": true
}

If a token is paired but connected is false, call POST /api/v1/sessions/{sessionId}/connect first. This reconnects the same linked device.

Send text

POST /api/v1/sessions/{sessionId}/messages
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <unique-message-key>

{
  "to": "15551234567",
  "content": {
    "type": "text",
    "text": "Your order is ready."
  }
}

Message options

Most send endpoints accept an optional options object:

{
  "options": {
    "quote": {
      "remoteJid": "[email protected]",
      "id": "3EB0A1B2C3D4E5F6",
      "fromMe": false
    },
    "mentions": ["[email protected]"],
    "forward": true
  }
}

Use quote for replies, mentions for group tags, forward to mark content as forwarded, and viewOnce on image, video, or audio sends.

Send media

Images, videos, audio, voice notes, documents, and stickers can be sent by URL with JSON or by uploading multipart/form-data.

POST /api/v1/sessions/{sessionId}/messages/image
Authorization: Bearer <api_key>
Content-Type: application/json
Idempotency-Key: <unique-message-key>

{
  "to": "15551234567",
  "content": {
    "type": "image",
    "mediaUrl": "https://example.com/receipt.jpg",
    "mimetype": "image/jpeg",
    "caption": "Receipt copy"
  }
}

For voice notes, call POST /api/v1/sessions/{sessionId}/messages/audio and set voice to true. For documents, call POST /api/v1/sessions/{sessionId}/messages/document and include fileName. For stickers, call POST /api/v1/sessions/{sessionId}/messages/sticker with WebP media. Or upload a file in the request body:

POST /api/v1/sessions/{sessionId}/messages/image
Authorization: Bearer <api_key>
Content-Type: multipart/form-data
Idempotency-Key: <unique-message-key>

Multipart fields:

Field	Required	Notes
`to`	Yes	Recipient phone number with country code.
`media`	Yes	Uploaded image file.
`mimetype`	No	Defaults to the uploaded file MIME type.
`caption`	No	Optional image caption.
`fileName`	No	Document filename.
`voice`	No	Set to `true` for voice notes on audio sends.

Send location or contact

POST /api/v1/sessions/{sessionId}/messages/location
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "to": "15551234567",
  "content": {
    "type": "location",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "Market Street"
  }
}

{
  "to": "15551234567",
  "content": {
    "type": "contact",
    "displayName": "Jane Doe",
    "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Jane Doe\nTEL:+15551234567\nEND:VCARD"
  }
}

Polls and reactions

POST /api/v1/sessions/{sessionId}/messages/poll
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "to": "[email protected]",
  "content": {
    "type": "poll",
    "name": "Lunch?",
    "options": ["Pizza", "Sushi"],
    "selectableCount": 1
  }
}

React to a message:

POST /api/v1/sessions/{sessionId}/messages/react
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "to": "15551234567",
  "target": {
    "remoteJid": "[email protected]",
    "id": "3EB0A1B2C3D4E5F6",
    "fromMe": false
  },
  "emoji": "👍"
}

Use an empty emoji string to remove your reaction.

Message actions

Use these endpoints to edit, revoke, pin, unpin, keep, unkeep, or delete a message for your linked device:

Action	Endpoint
Edit a sent text message	`PATCH /api/v1/sessions/{sessionId}/messages/edit`
Delete for everyone	`POST /api/v1/sessions/{sessionId}/messages/revoke`
Pin or unpin a message	`POST /api/v1/sessions/{sessionId}/messages/pin` or `/unpin`
Keep or unkeep disappearing content	`POST /api/v1/sessions/{sessionId}/messages/keep` or `/unkeep`
Delete for me	`POST /api/v1/sessions/{sessionId}/messages/delete-for-me`

Download incoming media

When your webhook or event stream receives an incoming image, video, audio, document, or sticker message, pass the message object back to WADial to download the encrypted attachment:

POST /api/v1/sessions/{sessionId}/media/download
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "message": {
    "imageMessage": {
      "mimetype": "image/jpeg",
      "directPath": "/v/t62.7118-24/...",
      "mediaKey": "..."
    }
  },
  "maxBytes": 16777216
}

The response includes metadata and base64-encoded bytes:

{
  "data": {
    "mediaType": "image",
    "mimetype": "image/jpeg",
    "fileLength": 184204,
    "sizeBytes": 184204,
    "base64": "..."
  }
}

List outgoing messages

GET /api/v1/sessions/{sessionId}/messages
Authorization: Bearer <api_key>

Each message includes contentType, receipt timestamps, idempotency key, and media metadata when present.

Get started

Guides

Build with the API

API Reference

Send text

Message options

Send media

Send location or contact

Polls and reactions

Message actions

Download incoming media

List outgoing messages

​Send text

​Message options

​Send media

​Send location or contact

​Polls and reactions

​Message actions

​Download incoming media

​List outgoing messages

Send text

Message options

Send media

Send location or contact

Polls and reactions

Message actions

Download incoming media

List outgoing messages