Mensageria

Módulo

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

POSTEnviar texto/messages/text POSTEnviar imagem, vídeo ou documento/messages/media POSTEnviar áudio/messages/media POSTEnviar template/messages/template POSTEnviar botões e listas/messages/interactive POSTEnviar localização, contato ou reação/messages GETListar mensagens/messages GETConsultar mensagem/messages/:id POSTMarcar como lida/messages/:id/read

POST/messages/textEscopo: writeOficial + Básico

Envia uma mensagem de texto.

Para responder use conversation_id; para iniciar use connection_id + recipient. connection_id aceita o UUID da conexão ou o número da instância (o mesmo valor pode ir em from). Recipient aceita telefone, contato, BSUID, parent BSUID ou username e nunca é inferido. Texto é o único tipo aceito pela conexão do plano Básico.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`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 \| phone	Conexão que envia: UUID de GET /connections ou o número da instância (ex.: 556293663491). Aceita o número formatado e com ou sem o nono dígito.
`from`opcional	uuid \| phone	Apelido de connection_id, para quem prefere pensar em número remetente.
`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/text" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "from": "556293663491",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "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.
409	O número informado corresponde a mais de uma conexão; a resposta traz candidates para você escolher o connection_id.
422	text ausente ou destino incompleto.

Exemplo de resposta

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

POST/messages/mediaEscopo: 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 \| phone	Número Oficial que envia: UUID ou o próprio número. Também aceito como from.
`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/media" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "from": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "image",
  "media": { "id": "<MEDIA_ID>", "caption": "Proposta em anexo" }
}'

Respostas

202	Arquivo aceito; acompanhe pelo wamid.
422	type fora do conjunto de mídia — os demais tipos usam a rota específica ou POST /messages.

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

Envia áudio ou mensagem de voz.

Mesma rota da mídia, com type=audio. 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/media" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "from": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "type": "audio",
  "media": { "id": "<MEDIA_ID>" }
}'

Respostas

202	Áudio aceito.

POST/messages/templateEscopo: 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. O campo type é implícito nesta rota.

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/template" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "from": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "template": { "name": "NOME_DO_TEMPLATE", "language": "pt_BR", "components": [] }
}'

Respostas

202	Template aceito.

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

Envia botões, listas e demais formatos interativos.

O objeto interactive nativo da Meta é preservado como veio. O campo type é implícito nesta rota. Localização, contatos e reação usam POST /messages.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`interactive`obrigatório	object	Objeto interativo nativo da Meta (button, list ou flow).

Exemplos prontos

curl -X POST "https://connect.zyronstack.com/api/v1/messages/interactive" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "from": "<CONNECTION_ID>",
  "recipient": { "phone": "<TELEFONE_COM_DDI>" },
  "interactive": {
    "type": "button",
    "body": { "text": "Podemos seguir?" },
    "action": { "buttons": [{ "type": "reply", "reply": { "id": "sim", "title": "Sim" } }] }
  }
}'

Respostas

202	Mensagem interativa aceita.

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

Rota genérica: aceita qualquer type, inclusive location, contacts e reaction.

É o formato histórico da API e continua válido para todos os tipos — as rotas por tipo apenas deixam o caminho explícito. Localização, contatos e reação só existem aqui: troque type e o objeto correspondente.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`type`obrigatório	location \| contacts \| reaction \| …	Qualquer tipo suportado pelo WhatsApp.
`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 \| phone	Conexão WhatsApp: UUID ou número da instância.
`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.