Mensageria — API Zyron Connect Suite

Module

Messaging

Unified WhatsApp API: send, track, mark as read and query text, templates, media, location, contacts, interactive messages and reactions.

POST/messages/messages POST/messages/messages POST/messages/messages POST/messages/messages POST/messages/messages GET/messages/messages GET/messages/:id/messages/:id POST/messages/:id/read/messages/:id/read

POST/messagesScope: writeOfficial + Basic

Send a typed WhatsApp message.

Use conversation_id to reply or connection_id plus recipient to start. Recipient accepts phone, contact, BSUID, parent BSUID or username and is never inferred. type defaults to text — the only type the Basic plan connection accepts; every other type requires an Official connection and the Official/Agency plan. Authorization with the API key is the only required credential. Idempotency-Key is optional and recommended for retries.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`Idempotency-Key`optional	header	Optional and recommended for idempotent retries (8–128 characters).
`text`optional	string	Message text; required when type=text.
`type`optional	text \| template \| image \| video \| audio \| document \| sticker \| location \| contacts \| interactive \| reaction	Message type. Defaults to text.
`template`optional	object	For template: name, language and optional components.
`media`optional	object	For media: link or id; caption and filename are optional.
`interactive`optional	object	Native Meta interactive object (button, list or flow).
`reply_to_message_id`optional	string	WAMID of the message being replied to.
`biz_opaque_callback_data`optional	string	Correlation returned by Meta in status events (max 512).
`conversation_id`optional	uuid	Use to reply to an existing conversation.
`connection_id`optional	uuid	Connection used to start a new conversation.
`recipient`optional	object	To start: phone, contact_id, business_scoped_user_id, parent_business_scoped_user_id or username.
`to`optional	string	Legacy: equivalent to recipient.phone.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "text",
  "text": "Ola, Maria. Posso te ajudar?"
}'

Responses

202	Meta accepted the send; track delivery through history or webhook.
404	Conversation or connection not found.
422	Missing text or incomplete target.

Response example

{
  "data": {
    "conversation_id": "<CONVERSATION_ID>",
    "provider_message_id": "wamid.HBgM...",
    "type": "text",
    "recipient": { "phone": "5511999998888", "business_scoped_user_id": "BR.4389531741319467" },
    "accepted": true,
    "delivery_status": "pending"
  }
}

POST/messagesScope: writeOfficial (Meta)Requires Official or Agency plan

Send image, video, document or sticker.

Use media.id from POST /media or a public media.link.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`connection_id`required	uuid	Official sending number.
`recipient.phone`required	string	Phone with country code.
`type`required	image \| video \| document \| sticker	File type.
`media.id`optional	string	ID from POST /media; preferred.
`media.link`optional	URL	Public alternative to media.id.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "image",
  "media": { "id": "<MEDIA_ID>", "caption": "Proposta em anexo" }
}'

Responses

202	File accepted; track the wamid.

POST/messagesScope: writeOfficial (Meta)Requires Official or Agency plan

Send audio or voice message.

Upload first and use media.id. Audio has no caption.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`media.id`required	string	ID returned by upload.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "audio",
  "media": { "id": "<MEDIA_ID>" }
}'

Responses

202	Audio accepted.

POST/messagesScope: writeOfficial (Meta)Requires Official or Agency plan

Send an approved Meta template.

Use outside the 24-hour window; inspect GET /templates first.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`template.name`required	string	Exact Meta-approved name.
`template.components`optional	array	Template parameters.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "connection_id": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "template",
  "template": { "name": "NOME_DO_TEMPLATE", "language": "pt_BR", "components": [] }
}'

Responses

202	Template accepted.

POST/messagesScope: writeOfficial (Meta)Requires Official or Agency plan

Send buttons, list, location, contacts or reaction.

Change type and its native object.

Path parameters

No additional parameters.

Query parameters

No additional parameters.

Body fields

Field	Type	Description
`interactive \| location \| contacts \| reaction`optional	object	Native content for the selected type.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "conversation_id": "<CONVERSATION_ID>",
  "type": "location",
  "location": { "latitude": -22.879, "longitude": -43.104, "name": "Local do atendimento" }
}'

Responses

202	Special message accepted.

GET/messagesScope: readOfficial + Basic

List messages and provider states.

Filter by connection, conversation, contact, direction, status or WAMID.

Path parameters

No additional parameters.

Query parameters

Field	Type	Description
`connection_id`optional	uuid	WhatsApp connection.
`conversation_id`optional	uuid	Internal conversation.
`provider_message_id`optional	string	WAMID/provider message ID.
`limit`optional	number	Records per page. Default 50; maximum 200 on most list endpoints.
`offset`optional	number	Initial page index. Use pagination.next_offset to fetch the next page.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/messages?connection_id=<CONNECTION_ID>&provider_message_id=wamid.HBgM..." \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Paginated messages.

GET/messages/:idScope: readOfficial + Basic

Get one message with provider payload.

Read media/interactive metadata without losing the original payload.

Path parameters

Field	Type	Description
`id`required	integer	Internal log ID.

Query parameters

No additional parameters.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X GET "https://connect.zyronstack.com/api/v1/messages/42" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Message returned.

POST/messages/:id/readScope: writeOfficial (Meta)

Mark an inbound message as read.

Available for Official connections; uses the WAMID stored in history.

Path parameters

Field	Type	Description
`id`required	integer	Inbound log ID.

Query parameters

No additional parameters.

Body fields

This endpoint does not receive a JSON body.

Ready examples

curl -X POST "https://connect.zyronstack.com/api/v1/messages/42/read" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Responses

200	Read confirmed.
422	Connection does not support mark-read.