Messages

Overview

Send messages to a customer. One endpoint covers text, media, sticker and template sends — the type field selects which. Sends are limited to WhatsApp and Instagram; Web Chat, Telegram and TikTok Shop conversations are readable through the API but not addressable from here.

1 endpoint. Requires chats.reply on the token.

Method	Path	What it does
POST	/messages	Send a message

Endpoints

POST /messages

Send a message

Send a text, media, sticker, or template message via WhatsApp or Instagram. Use `channel` to select the channel type and `channelId` to target a specific OrgChannel instance. If no active session exists (WhatsApp), an `agentId` must be provided to start one.

Requires the chats.reply permission.

Request body

Field	Type	Required	Description
to	string	required	Recipient identifier — phone number for WhatsApp, igId for Instagram
channelId	string	optional	OrgChannel ID. If omitted, inferred from existing chat or org default.
channel	WHATSAPP · INSTAGRAM	optional	Channel type. Defaults to WHATSAPP. Defaults to "WHATSAPP".
agentId	string	optional	Agent user ID. Required if no active session exists (WhatsApp only).
takeOver	boolean	optional	Set true to force reassignment if contact has session with another agent
type	text · image · document · video · audio · sticker · template	required	Message type
text	string	optional	Text content (required for type text)
mediaId	string	optional	WhatsApp media ID (required for media/sticker types)
mediaUrl	string	optional	Media URL (alternative to mediaId)
caption	string	optional	Media caption
fileName	string	optional	Document filename
templateName	string	optional	Template name (required for type template)
templateLanguage	string	optional	Template language code (required for type template)
templateComponents	array of any	optional	Template variable components
previewUrl	boolean	optional	Enable URL preview in text messages
contextId	string	optional	Reply-to message WAMID for threading

Example

curl -X POST "https://orqestra.id/api/v2/messages" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "628123456789",
    "type": "text"
  }'

Responds with 200 · 400 · 401 · 403 · 404 · 409 · 429. Try it in the playground →