Schedule message

Send or schedule a WhatsApp message to the chat named in the URL path (`{chatId}` — a phone number in E.164 format, e.g. `+15551234567`, or a WhatsApp chat id like `12345@c.us` / `1234567890@g.us` / `12345@newsletter`).

Omit sendAt to send immediately; set it (RFC 3339, ≥10s and ≤365d in the future) to defer delivery.

The body is a FLAT object — set the type field to one of text, media, or poll; type selects which top-level fields are relevant.

Variants:

type: "text" — required text (1–4096 chars). A rich link-preview card is attached automatically when the text contains a URL. Example:

curl -X POST "https://api.blueticks.co/v1/scheduled-messages/+15551234567" \
  -H "Authorization: Bearer $BLUETICKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"hello"}'

type: "media" — provide the media as mediaUrl (HTTPS) or mediaBase64 (base64 / data: URL); mediaUrl wins if both are sent. The bytes are uploaded server-side and only a URL is sent on to the engine. Optional mediaKind (image · video · audio · document · sticker · voice · gif; auto-detected when omitted), text (caption), mediaFilename. You can also upload a file as multipart/form-data with the bytes in a mediaFile part.
type: "poll" — required pollQuestion and pollOptions (2–12 items). Optional pollAllowMultiple (default false).

All variants accept optional sendAt (defer) and replyTo (wire key of a prior message to quote). Pass an Idempotency-Key header to make retries safe (at most one send per key). Requires messages:write.

See Sending messages for runnable Python / Node / PHP / cURL examples per variant.

Request

curl -X POST "https://api.blueticks.co/v1/scheduled-messages/" \  -H "Content-Type: application/json" \  -d '{    "type": "text",    "text": ""  }'

{
  "success": true,
  "data": {
    "id": "string",
    "waMessageKey": {
      "fromMe": true,
      "remote": "string",
      "id": "string",
      "_serialized": "string",
      "participant": "string"
    },
    "to": "string",
    "type": "text",
    "text": "string",
    "mediaUrl": "string",
    "mediaKind": "image",
    "pollQuestion": "string",
    "pollOptions": [
      "string"
    ],
    "pollAllowMultiple": true,
    "status": "pending",
    "sendAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "confirmedAt": "2019-08-24T14:15:22Z",
    "receivedAt": "2019-08-24T14:15:22Z",
    "readAt": "2019-08-24T14:15:22Z",
    "playedAt": "2019-08-24T14:15:22Z",
    "failedAt": "2019-08-24T14:15:22Z",
    "failureReason": "string",
    "secret": "string",
    "linkPreview": {
      "title": "string",
      "description": "string",
      "canonicalUrl": "string",
      "thumbnail": "string"
    }
  }
}

{
  "success": true,
  "data": {
    "id": "string",
    "waMessageKey": {
      "fromMe": true,
      "remote": "string",
      "id": "string",
      "_serialized": "string",
      "participant": "string"
    },
    "to": "string",
    "type": "text",
    "text": "string",
    "mediaUrl": "string",
    "mediaKind": "image",
    "pollQuestion": "string",
    "pollOptions": [
      "string"
    ],
    "pollAllowMultiple": true,
    "status": "pending",
    "sendAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "confirmedAt": "2019-08-24T14:15:22Z",
    "receivedAt": "2019-08-24T14:15:22Z",
    "readAt": "2019-08-24T14:15:22Z",
    "playedAt": "2019-08-24T14:15:22Z",
    "failedAt": "2019-08-24T14:15:22Z",
    "failureReason": "string",
    "secret": "string",
    "linkPreview": {
      "title": "string",
      "description": "string",
      "canonicalUrl": "string",
      "thumbnail": "string"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "requestId": "string",
    "details": [
      {
        "path": "string",
        "code": "string",
        "message": "string"
      }
    ]
  }
}

Path Parameters

chatId*string

Header Parameters

Idempotency-Key?string

Optional key for safe retries — guarantees a request runs at most once, so a network timeout + retry never double-sends. Reuse the same key to retry: an identical body replays the original response (HTTP 200 instead of 201, no second message); a different body with the same key returns 409 Conflict. Keys are scoped per workspace (max 64 chars). This is the request-level dedup control — distinct from the body secret field, which is only a correlation tag and does NOT prevent duplicate sends.

Lengthlength <= 64

Request Body

application/json

type*string

Value in"text" | "media" | "poll"

replyTo?string

Wire key of a prior message to quote-reply (from MessageResponse.key). Empty string = no reply.

Lengthlength <= 256

text?string

Text body (required for type=text) or optional media caption (type=media). Up to 4096 chars. Mention a contact inline with @[Display Name](<jid>), e.g. Hi @[Jon Daw](xxxxxxxxxxxx@c.us).

Lengthlength <= 4096

mediaUrl?string

Media source URL (https only). One of mediaUrl or mediaBase64 is required for media sends; mediaUrl wins when both are present.

Lengthlength <= 2048

mediaBase64?string

Raw media bytes, base64-encoded (or a data: URL). Used when mediaUrl is absent. For a file upload, send multipart/form-data with a mediaFile part instead — it is converted to this.

Lengthlength <= 15728640

mediaKind?string

Media kind (image · video · audio · document · sticker · voice · gif). Optional — auto-detected from the URL / content-type when omitted.

mediaFilename?string

Filename shown on the attachment (type=media). Optional — derived from the URL / uploaded file when omitted.

Length1 <= length <= 255

pollQuestion?string

Poll question (type=poll). Required for poll sends.

Length1 <= length <= 255

pollOptions?array<>

Poll options (type=poll). 2–12 items.

pollAllowMultiple?boolean

Allow selecting multiple poll options (type=poll). Default false.

secret?string

Opaque correlation token you choose to tag this message with. It is stored on the message and carried into WhatsApp's messageSecret, so you can match it back to your own records later. NOT a deduplication key: sending the same secret twice creates two separate messages. To make retries safe (at-most-once send), use the Idempotency-Key header instead. When omitted, the API encodes the internal message id here for delivery-status matching — only set this if you have your own correlation scheme.

Length1 <= length <= 256

sendAt?string

Formatdate-time

Schedule message

Request

Path Parameters

Header Parameters

Request Body

Response

Response Body

`application/json`

`application/json`

`application/json`

Schedule message

Request

Path Parameters

Header Parameters

Request Body

Response

Response Body

200application/json

201application/json

Error codesapplication/json

`application/json`

`application/json`

`application/json`