POST/v1/send

Send a message

Sends text, media, a location or a poll from this device to one or many recipients. Authenticate with the device token — an account token cannot send. The response arrives as soon as the messages are queued, so a 200 means accepted, not delivered: follow each id with GET /v1/messages/{id} or wait for the message.status webhook.

AuthenticationDevice token

One rule the field table cannot show

No single field is required on its own. A request must carry a recipient — either target or a data batch whose every element has one — and something to send: a message, media, a location or a poll. Exactly one content kind per message.

Request

shell

curl -X POST https://api.sapa.tokoaplikasi.id/v1/send \
  -H "Authorization: Bearer $WA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"628123456789","message":"wa is wired up."}'

Body

Field	Type	Description
target	string	SEND-01/02 — one or more recipients, comma-separated. Each entry is a phone number, optionally followed by `\|`-separated values for the message template: the first fills `{name}`, the rest fill `{var1}`, `{var2}`, … For example `628123456789\|Budi\|40192, 08129999888\|Ani`. A number starting with `0` is expanded using `countryCode`. Required unless `data` is given.
message	string	The text to send, or the caption when `url` or a file upload is present. Supports the `{name}` and `{var1}`…`{varN}` placeholders filled from `target`; an unmatched placeholder is left as written. Cannot be combined with `location` or `choices`.
url	string	SEND-10 — a publicly reachable URL the gateway fetches once and sends as media. Max 4 MB. Private, loopback and link-local addresses are refused (`url invalid`). Mutually exclusive with a multipart file upload, `location` and `choices`.
filename	string	The name the recipient sees for a document. Ignored for image, video and audio.
schedule	integer	SEND-05 — send at this unix timestamp (seconds) instead of now. The message is stored with status `waiting`; check, cancel or move it with the `/v1/messages/{id}` endpoints. A timestamp in the past sends immediately.
delay	string	SEND-04 — seconds to wait between consecutive targets, overriding the device pacing range. `"5"` is a fixed gap; `"5-100"` draws a random gap in that range for each target. Each bound is at most 600. The first target of a request never waits.
countryCode	string = 62	SEND-02 — the country code that replaces a leading `0` in a target, without the `+`. Defaults to `62` (Indonesia). Pass `"0"` to disable expansion, which requires every target to already be fully qualified.
location	string	SEND-11 — send a location pin instead of text, as `"latitude,longitude"` in decimal degrees, e.g. `"-6.2088,106.8456"`. Cannot be combined with `message`.
typing	boolean	SEND-13 — show the composing indicator to the recipient for `duration` seconds before the message lands. Accepts a boolean, or `"true"` / `"false"` from a form-encoded caller.
duration	integer	How long the typing indicator shows, in seconds (1–600). Only meaningful with `typing`. Accepts a number, or a digit string from a form-encoded caller.
choices	string	SEND-12 — send a poll instead of text. Comma-separated options, 2 to 12 of them, e.g. `"yes, no, maybe"`. Requires `pollname`. Cannot be combined with `message`.
select	string	Whether a poll accepts one answer or several. Defaults to `single`. One of single · multiple.
pollname	string	The poll question. Required whenever `choices` is given.
file	string	Read-only echo of an uploaded file name. Set by the gateway when the request arrives as `multipart/form-data` with a `file` part; a JSON caller that sets it without uploading anything is refused. Send media as a file part or as `url`, never both.
connectOnly	boolean	Refuse the request with `device disconnected` when the device is not connected, instead of queueing the message until it reconnects. Defaults to true.
sequence	boolean	SEND-06 — send to the targets strictly in the order given, one after the other, rather than letting the pacing worker interleave them.
preview	boolean	Accepted for Fonnte compatibility and ignored. Link previews are not generated.
inboxid	string	MSG-08 — the id of a message this device received, to send this one as a reply quoting it. Must belong to the same device and the same chat.
data	string	SEND-09 — a JSON string holding an array of send objects, for addressing many recipients with different content in one request. Each element takes the same fields as this body except `data` and a file upload, and each must carry its own `target`. When `data` is given the top-level `target` is ignored.

Response

200 — Accepted. Every valid target has a queued message and an id; delivery has not happened yet.

json

{
  "status": true,
  "id": [
    ""
  ],
  "target": [
    ""
  ],
  "process": "pending",
  "requestid": "",
  "detail": ""
}

Field	Type	Description
status	true	Always true on an accepted request.
id	string[]	One message id per accepted target, in the same order as `target`. Poll each with GET /v1/messages/{id}, or wait for the `message.status` webhook.
target	string[]	The normalized recipients, digits only, one per accepted message.
process	"pending"	Always `pending`. The request was accepted and the messages are queued — delivery is asynchronous and this is not a delivery confirmation.
requestid	string	Correlation id for this request. It travels with every message it created, through the queue and into each webhook delivery — quote it when reporting a problem.
detail	string	Present when something about the request needs explaining — targets dropped as invalid, or messages held back by the device warm-up ceiling.

Failure modes

Every failure answers with the same envelope: { "status": false, "reason": "…" }. Match on reason, never on the status alone — the full vocabulary is on the Errors page.

Field	Type	Description
400	error	The request could not be understood — a malformed body, a `data` batch that is not JSON, no recipient, no content, or more than one content kind.
401	error	The token is missing, malformed or revoked.
403	error	An account token was used; sending needs the device token.
404	error	The token's device no longer exists.
429	error	Too many requests for this token. Wait the seconds in `retryAfter`.