POST/v1/quick-messagesbeta

Create a quick message

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 — every check runs with ?dry_run=true, nothing changes
Undo: Delete it with Delete a quick message.

Creates a quick message your team can insert in the inbox by typing /code. TEXT needs text; IMAGE, VIDEO and DOCUMENT need a public media_url (text becomes the caption).

It is private to the key's user unless visibility is team (with team_id) or company. The code must be unique in your workspace.

Try it

Edit as JSON

coderequiredstring

Shortcut code, unique, no spaces, e.g. `thanks`.

titlerequiredstring

Title shown in the picker.

descriptionoptionalstring

A note for your team.

typeoptionalstring

`TEXT` (default), `IMAGE`, `VIDEO` or `DOCUMENT`.

textoptionalstring

The message (`TEXT`), or the caption of a media message. Variables such as `{{contact.name}}` are allowed.

media_urloptionalstring

Public https URL of the file (media types).

file_nameoptionalstring

`DOCUMENT`: the file name the customer sees.

visibilityoptionalstring

`private` (default), `team` or `company`.

team_idoptionalstring

The team, with `visibility: team`.

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/quick-messages?dry_run=true' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "code": "thanks",
  "title": "Thank you",
  "text": "Thanks for your order, {{contact.name}}!",
  "visibility": "company"
}'

The code reads your key from $API_KEY.

Body

Body fields
Field	Type	What it is
coderequired	string	Shortcut code, unique, no spaces, e.g. `thanks`.pattern `^\S+$` · 1–60 characters
titlerequired	string	Title shown in the picker.1–120 characters
description	string	A note for your team.0–500 characters
type	string	`TEXT` (default), `IMAGE`, `VIDEO` or `DOCUMENT`.one of: `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` · default `"TEXT"`
text	string	The message (`TEXT`), or the caption of a media message. Variables such as `{{contact.name}}` are allowed.0–4096 characters
media_url	string	Public https URL of the file (media types).uri · 0–2000 characters
file_name	string	`DOCUMENT`: the file name the customer sees.0–200 characters
visibility	string	`private` (default), `team` or `company`.one of: `private`, `team`, `company`
team_id	string	The team, with `visibility: team`.0–20 characters

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 quick message.

Response fields
Field	Type	What it is
idrequired	string
coderequired	string or null	Shortcut agents type after "/" in the inbox.
titlerequired	string or null
typerequired	string or null	TEXT, IMAGE, VIDEO, DOCUMENT, TEMPLATE, INTERACTIVE …
textrequired	string or null	Text body, or the media caption.
media_urlrequired	string or null
template_namerequired	string or null
visibilityrequired	string or null
team_idrequired	string or null
favoriterequired	boolean
can_editrequired	boolean
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 code is already taken, or a field the type needs is missing. 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.
409	conflict	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.
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 thank-you reply for the whole team

Request body

{
  "code": "thanks",
  "title": "Thank you",
  "text": "Thanks for your order, {{contact.name}}!",
  "visibility": "company"
}

Response 201

{
  "id": "12",
  "code": "thanks",
  "title": "Thank you",
  "type": "TEXT",
  "text": "Thanks for your order, {{contact.name}}!",
  "media_url": null,
  "template_name": null,
  "visibility": "company",
  "team_id": null,
  "favorite": false,
  "can_edit": true,
  "updated_at": "2026-09-02T10:00:00Z"
}

Operation path

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