POST/v1/short-linksbeta

Create a short link

Needs: Send WhatsApp messages; manage templates, quick messages and WhatsApp short links (messaging:write)
Plan: Any plan with API access
Limits: 60 a minute per key
Dry run: Yes — a full preview with ?dry_run=true
Undo: Delete it with Delete a short link.

Creates a WhatsApp click-to-chat short link: a https://wa.me/message/… link that opens a chat with one of your connected WhatsApp numbers with message already typed (the customer can edit it before sending). A QR code image of the link comes with it, PNG unless you ask for SVG or NONE.

message: 1–140 characters of plain text (an emoji counts as 2). New lines, emoji and links are fine; do not URL-encode it.
The number: channel_id or phone. Needed only when several numbers are connected (400, reason: channel_ambiguous, with the choices).
A second link with the same message on the same number is refused with 409 (reason: duplicate, existing_id) unless allow_duplicate is true.

The QR image is hosted by WhatsApp and its URL can expire: download it and keep your own copy for print. Run it with ?dry_run=true (a test key always does): every check runs and the answer names the number, but nothing is created.

Try it

Edit as JSON

messagerequiredstring

The text the customer finds typed: 1–140 characters, plain text (an emoji counts as 2).

channel_idoptionalstring

The WhatsApp channel the link opens a chat with. Needed only when several numbers are connected.

phoneoptionalstring

Instead of `channel_id`: the connected WhatsApp number, in any format.

qr_formatoptionalstring

`PNG` (default), `SVG`, or `NONE` for no QR image.

allow_duplicateoptionalboolean

`true` = create even when the number already has a link with this exact message.

Idempotency-Keyneeded for live runs — made for you if empty

Protects against doing it twice if you retry: a retry with the same key gets the first answer back instead of running again.

Test mode (dry run): nothing will change

Run liveTurns test mode off for this page only. It switches back when you leave the page.

curl -X POST 'https://mcp.wa-api.cloud/v1/short-links?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "message": "Hi! I'\''d like to order 🍕",
  "channel_id": "301"
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
messagerequired	string	The text the customer finds typed: 1–140 characters, plain text (an emoji counts as 2).0–1000 characters
channel_id	string	The WhatsApp channel the link opens a chat with. Needed only when several numbers are connected.0–64 charactersSigned in? Pick one from your data with “My data”.
phone	string	Instead of `channel_id`: the connected WhatsApp number, in any format.0–32 characters
qr_format	string	`PNG` (default), `SVG`, or `NONE` for no QR image.one of: `PNG`, `SVG`, `NONE` · default `"PNG"`
allow_duplicate	boolean	`true` = create even when the number already has a link with this exact message.

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`
Idempotency-Keyrequired	header	Required here. Any unique string (8–128 characters), e.g. your order id plus the step. Kept 24 hours. Not needed with `dry_run=true`.pattern `^[A-Za-z0-9._:-]+$` · 8–128 characters

Response `201`

The new short link (a dry run: `id`, `code` and `url` are null, `dry_run` is true).

Response fields
Field	Type	What it is
idrequired	string or null
coderequired	string or null
urlrequired	string or null
messagerequired	string or null	The text the customer finds already typed; they can edit it before sending.
qr_image_urlrequired	string or null	QR code image of the link, hosted by WhatsApp. The link can expire: download and keep your own copy for print.
qr_image_formatrequired	string or null	PNG or SVG; null when there is no image or its format is not known.one of: `PNG`, `SVG`
channelrequired	object or null	The WhatsApp number it belongs to.
idrequired	string	Workspace channel id (as `GET /v1/channels` lists it).
namerequired	string or null
phonerequired	string or null	The WhatsApp number the link opens a chat with.
created_atrequired	string or null
updated_atrequired	string or null
dry_run	boolean	`true` when this was a dry run: every check ran and nothing changed.

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field. The message breaks a rule (`reason`: `message_empty`, `message_too_long`, `message_control_chars`, `message_url_encoded`), or several numbers are connected and none was chosen (`reason: channel_ambiguous`). Also returned when the Idempotency-Key header is missing, or was used before with a different body.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
404	not_found	The channel or phone is not a WhatsApp number of your workspace.
409	conflict	The number is not connected (`reason: channel_not_connected`), or it already has a link with this message (`reason: duplicate`). Also returned while a request with the same Idempotency-Key is still running.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds. WhatsApp is rate limiting short-link changes. Retry after `Retry-After`.
502	upstream_error	WhatsApp refused the link (`reason: refused_by_whatsapp`).
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.
504	timeout	The change did not finish in time. Retry with the same Idempotency-Key: it never runs twice.

Examples

A link that starts an order

Request body

{
  "message": "Hi! I'd like to order 🍕",
  "channel_id": "301"
}

Response 201

{
  "id": "sl-12",
  "code": "4PZQX7M2LCKHA1",
  "url": "https://wa.me/message/4PZQX7M2LCKHA1",
  "message": "Hi! I'd like to order 🍕",
  "qr_image_url": "https://scontent-bom5-2.xx.fbcdn.net/m1/v/t6/An9_qr4PZQX7M2LCKHA1?ccb=10-5&oe=66F00000",
  "qr_image_format": "PNG",
  "channel": {
    "id": "301",
    "name": "Main WhatsApp",
    "phone": "+1 555-555-0100"
  },
  "created_at": "2026-09-12T10:00:00.000Z",
  "updated_at": "2026-09-12T10:00:00.000Z"
}

Operation path

The same operation is also at POST /v1/ops/messaging_create_short_link, with every field in the JSON body.