Mensageria

Módulo

API WhatsApp unificada: envie, acompanhe, marque como lido e consulte texto, template, mídia, localização, contatos, interativos e reações.

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/messagesEscopo: writeOficial + Básico

Envia uma mensagem WhatsApp tipada.

Para responder use conversation_id; para iniciar use connection_id + recipient. Recipient aceita telefone, contato, BSUID, parent BSUID ou username e nunca é inferido. type padrão é text — o único tipo aceito pela conexão do plano Básico; os demais tipos exigem conexão Oficial e plano Oficial/Agency. Authorization com a API key é a única credencial exigida. Idempotency-Key é opcional e recomendada: com a mesma chave, retries devolvem a mesma resposta; sem ela, o servidor gera uma chave interna única.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`Idempotency-Key`opcional	header	Opcional e recomendada para retries idempotentes (8–128 caracteres).
`text`opcional	string	Texto da mensagem; obrigatório quando type=text.
`type`opcional	text \| template \| image \| video \| audio \| document \| sticker \| location \| contacts \| interactive \| reaction	Tipo de mensagem. Padrão text.
`template`opcional	object	Para template: name, language e components opcionais.
`media`opcional	object	Para mídia: link ou id; caption e filename são opcionais.
`interactive`opcional	object	Objeto interativo nativo da Meta (button, list ou flow).
`reply_to_message_id`opcional	string	WAMID da mensagem que será respondida.
`biz_opaque_callback_data`opcional	string	Correlação devolvida pela Meta nos status (máximo 512).
`conversation_id`opcional	uuid	Use para responder uma conversa existente.
`connection_id`opcional	uuid	Conexão usada para iniciar uma nova conversa.
`recipient`opcional	object	Para iniciar: phone, contact_id, business_scoped_user_id, parent_business_scoped_user_id ou username.
`to`opcional	string	Legado: equivalente a recipient.phone.

Exemplos prontos

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?"
}'

Respostas

202	Meta aceitou o envio; acompanhe delivery_status no histórico ou webhook.
404	Conversa ou conexão não encontrada.
422	text ausente ou destino incompleto.

Exemplo de resposta

{
  "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/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia imagem, vídeo, documento ou figurinha.

Envie media.id retornado por POST /media ou media.link público. O bloco Mídia explica upload e download.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Número Oficial que envia.
`recipient.phone`obrigatório	string	Telefone com DDI.
`type`obrigatório	image \| video \| document \| sticker	Tipo do arquivo.
`media.id`opcional	string	ID de POST /media; prefira a ele.
`media.link`opcional	URL	Alternativa pública ao media.id.

Exemplos prontos

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" }
}'

Respostas

202	Arquivo aceito; acompanhe pelo wamid.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia áudio ou mensagem de voz.

Faça upload antes e use media.id. Áudio não recebe legenda.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`media.id`obrigatório	string	ID retornado pelo upload.

Exemplos prontos

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>" }
}'

Respostas

202	Áudio aceito.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia template aprovado pela Meta.

Use para iniciar conversa fora da janela de 24 h; consulte GET /templates antes.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`template.name`obrigatório	string	Nome exato aprovado na Meta.
`template.components`opcional	array	Parâmetros do template.

Exemplos prontos

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": [] }
}'

Respostas

202	Template aceito.

POST/messagesEscopo: writeOficial (Meta)Requer plano Oficial ou Agency

Envia botões, lista, localização, contatos ou reação.

Troque type e seu objeto: interactive, location, contacts ou reaction. Os objetos nativos são preservados.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`interactive \| location \| contacts \| reaction`opcional	object	Conteúdo nativo do tipo escolhido.

Exemplos prontos

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" }
}'

Respostas

202	Mensagem especial aceita.

GET/messagesEscopo: readOficial + Básico

Lista mensagens e estados do provider.

Filtre por connection_id, conversation_id, contact_id, direction, status ou provider_message_id (WAMID).

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Conexão WhatsApp.
`conversation_id`opcional	uuid	Conversa interna.
`provider_message_id`opcional	string	WAMID/ID retornado pelo provider.
`limit`opcional	number	Quantidade de registros por página. Padrão 50; máximo 200 na maioria das listas.
`offset`opcional	number	Índice inicial da página. Use pagination.next_offset para buscar a próxima página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

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"

Respostas

200	Mensagens paginadas.

GET/messages/:idEscopo: readOficial + Básico

Consulta uma mensagem com payload do provider.

Use para ler metadados de mídia, interativos e eventos recebidos sem perder o payload original.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	integer	ID interno do log.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

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

Respostas

200	Mensagem retornada.

POST/messages/:id/readEscopo: writeOficial (Meta)

Marca uma mensagem inbound como lida.

Disponível para conexão Oficial; usa o WAMID salvo no histórico.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	integer	ID interno do log inbound.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

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

Respostas

200	Leitura confirmada.
422	Tipo de conexão não suporta leitura.