Conversas

Módulo

Leia conversas do Inbox e o histórico completo de mensagens.

GETListar conversas/conversations GETMensagens da conversa/conversations/:id/messages GETResolver por número/conversations/resolve GETConsultar conversa/conversations/:id PATCHAtualizar conversa/conversations/:id

GET/conversationsEscopo: readOficial + Básico

Lista conversas do Inbox.

Retorna última mensagem, status, conexão e dados básicos do contato.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`opcional	uuid	Filtra por conexão de WhatsApp.
`contact_id`opcional	uuid	Filtra pelas conversas de um contato.
`phone`opcional	string	Filtra pelo telefone do contato (com DDI).
`status`opcional	open \| closed \| pending	Filtra por status da conversa.
`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/conversations?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversas retornadas.

Exemplo de resposta

{
  "data": [
    {
      "id": "<CONVERSATION_ID>",
      "connection_id": "<CONNECTION_ID>",
      "contact_id": "<CONTACT_ID>",
      "status": "open",
      "last_message_text": "Quero saber mais",
      "last_message_at": "2026-06-15T12:30:00.000Z",
      "unread_count": 2,
      "contacts": {
        "name": "Maria Silva",
        "phone": "5511999998888"
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 41,
    "next_offset": 20
  }
}

GET/conversations/:id/messagesEscopo: readOficial + Básico

Lista mensagens de uma conversa.

O limite padrão é 100 e o máximo é 500. A ordenação é crescente por created_at.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

Parâmetros de query

Campo	Tipo	Descrição
`limit`opcional	number	Quantidade de mensagens. Padrão 100; máximo 500.
`offset`opcional	number	Índice inicial da página.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>/messages?limit=100&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Mensagens retornadas.
404	Conversa não encontrada.

Exemplo de resposta

{
  "data": [
    {
      "id": "41a9fa77-6b9d-4d94-a48d-74d036c54121",
      "direction": "in",
      "body": "Quero saber mais",
      "created_at": "2026-06-15T12:30:00.000Z"
    },
    {
      "id": "d38adf37-0f2a-477f-8d8a-238caab12411",
      "direction": "out",
      "body": "Claro, vou te explicar.",
      "created_at": "2026-06-15T12:31:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "next_offset": null
  }
}

GET/conversations/resolveEscopo: readOficial + Básico

Resolve uma conversa por número.

Evita depender de UUID prévio: use connection_id + phone, BSUID, parent BSUID ou username. O webhook Zyron já entrega este UUID pronto.

Parâmetros de caminho

Sem parâmetros adicionais.

Parâmetros de query

Campo	Tipo	Descrição
`connection_id`obrigatório	uuid	Conexão do WhatsApp.
`phone`opcional	string	Telefone com DDI.
`business_scoped_user_id`opcional	string	Identidade BSUID da Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID da Meta.
`username`opcional	string	Usuário externo persistido no contato.

Campos do corpo

Este endpoint não recebe corpo JSON.

Exemplos prontos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/resolve?connection_id=<CONNECTION_ID>&phone=5511999998888" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversa resolvida.
404	Contato ou conversa não encontrado.

Exemplo de resposta

{
  "data": {
    "id": "<CONVERSATION_ID>",
    "connection_id": "<CONNECTION_ID>",
    "status": "open",
    "last_inbound_at": "2026-07-13T13:28:28.347Z",
    "contact": { "id": "<CONTACT_ID>", "phone": "5511999998888" }
  }
}

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

Detalhe operacional da conversa.

Retorna status, tags, atendente, nota interna, last_inbound_at (janela de 24h) e identidades do contato.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

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/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respostas

200	Conversa retornada.
404	Conversa não encontrada.

PATCH/conversations/:idEscopo: writeOficial + Básico

Atualiza estado operacional da conversa.

Fecha, reabre, deixa pendente, atribui atendente e atualiza tags/notas internas.

Parâmetros de caminho

Campo	Tipo	Descrição
`id`obrigatório	uuid	ID da conversa.

Parâmetros de query

Sem parâmetros adicionais.

Campos do corpo

Campo	Tipo	Descrição
`status`opcional	open \| closed \| pending	Estado da conversa.
`tags`opcional	string[]	Etiquetas operacionais (até 30).
`assignee_name`opcional	string	Atendente responsável.
`internal_note`opcional	string	Nota interna da equipe, até 4000 caracteres.

Exemplos prontos

curl -X PATCH "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "status": "pending",
  "tags": ["lead-quente", "n8n"],
  "assignee_name": "Time comercial"
}'

Respostas

200	Conversa atualizada.