Send messages
Send text
Send a text message with POST /v1/messages over WhatsApp, Instagram or Messenger, with link preview, reply, typing indicator and delay.
POST /v1/messages with type: "text" sends a free-form text message. It works on WhatsApp, Instagram and Messenger.
Before you start
Section titled “Before you start”- An API key with the
sendpermission (see Authentication). - An Active connection for the channel you will use.
- Free-form messages only go out within 24 hours of the contact’s last message (see Windows). Outside it, use a template.
Send a text
Section titled “Send a text”curl https://api.messajo.com/v1/messages \ -H "Authorization: Bearer $MESSAJO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Hi! Your order is out for delivery." } }'import { Messajo } from "@messajo/sdk";
const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });
const sent = await messajo.messages.send({ connection_id: "conn_...", to: "5511999999999", type: "text", text: { body: "Hi! Your order is out for delivery." },});n8n HTTP Request node settings
- Method:
POST - URL:
https://api.messajo.com/v1/messages - Authentication: Generic Credential Type, then Header Auth. Name:
Authorization; Value:Bearer mj_... - Headers: turn on Send Headers and add
Idempotency-Key(a unique value per item) - Body: turn on Send Body; Body Content Type: JSON; Specify Body: Using JSON
{ "connection_id": "conn_...", "to": "5511999999999", "type": "text", "text": { "body": "Hi! Your order is out for delivery." }}Replace mj_... with your API key.
Response
Section titled “Response”The response is 201:
{ "id": "msg_...", "external_id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjQ", "status": "queued", "meta_status": "accepted", "conversation_id": "cnv_...", "contact_id": "ctc_...", "created_at": "2026-11-09T12:00:00.000Z"}idis the Messajo message id (msg_…);external_idis Meta’s.statuscomes back asqueued. Delivery and read arrive later, in themessage.statusevent.meta_statusisaccepted,held_for_quality_assessment,pausedornull.
Link preview
Section titled “Link preview”On WhatsApp, text.preview_url: true asks for the link in the message to show a preview.
{ "type": "text", "text": { "body": "Track it at https://example.com/order/123", "preview_url": true } }Reply to a message
Section titled “Reply to a message”reply_to quotes an earlier message. It accepts the Messajo id (msg_…) or the Meta id. A msg_… that does not exist returns 404 not_found.
Typing and delay
Section titled “Typing and delay”typing: trueshows the typing indicator before the message goes out.delay_mswaits 0 to 20000 milliseconds before sending (default 0).
typing also spends one token from the number’s bucket (see Limits).
Common fields
Section titled “Common fields”They apply to every send page.
| Field | Description |
|---|---|
connection_id |
Connection that sends. Optional with a connection key (mjc_…); required with an organization key (mj_…). |
to |
Recipient. WhatsApp: phone with country code (only digits count), BSUID, ctc_… (contact) or grp_… (group). Instagram: IGSID or ctc_…. Messenger: PSID or ctc_…. |
type |
Message type. Here, text. |
reply_to |
Quoted message: msg_… or Meta id. |
typing |
true shows the typing indicator before sending. Default false. |
delay_ms |
Wait before sending, 0 to 20000. Default 0. |
biz_opaque_callback_data |
WhatsApp: text of up to 512 characters returned with the status. |
tag |
"human_agent", Instagram and Messenger only. On WhatsApp it returns 422 tag_not_supported_by_channel. |
Idempotency-Key header |
Prevents duplicate sends when you repeat the call; valid for 24 hours (see Idempotency). |
An unknown field in the body is rejected with 400 validation_failed.
Limits and channels
Section titled “Limits and channels”| Channel | Text length |
|---|---|
| 1 to 4096 characters | |
| up to 1,000 bytes | |
| Messenger | up to 2,000 characters |
On Instagram and Messenger, text.quick_replies takes 1 to 13 items { "title", "payload" }, with title up to 20 and payload up to 1000 characters. text.preview_url is WhatsApp only.
Groups
Section titled “Groups”With to: "grp_…", WhatsApp accepts text, media and template. See Groups.
Common errors
Section titled “Common errors”outside_service_window(422): outside the 24 hours. The window end is indetails[0].message.connection_rate_limited(429): no token left in the number’s bucket. Wait forRetry-After(orretry_after_ms) and retry.pair_rate_limited(429): too many messages to the same contact in a short time.recipient_unavailable(422): Meta could not deliver to that recipient.type_not_supported_by_channel(422): the channel does not accept this type.meta_unknown_outcome(502): it is unknown whether the message went out. Do not resend blindly; check first.connection_needs_reconnect(409): the connection lost access and must be reconnected.