Documentação · API

Conversas e pausa

Leia as conversas e o histórico de cada uma, baixe os arquivos e pause a IA numa conversa para o seu sistema responder.

Permissão da chaveconversationsPacoteIntegrações (R$ 49 por mês, por conta). Sem ele, a API responde 403 plan_not_allowed.

Rota	O que faz
`GET /v1/conversations`	As conversas, a mais recente primeiro, com filtros.
`GET /v1/conversations/{id}/messages`	O histórico, com direção, origem, status e arquivos.
`POST /v1/conversations/{id}/pause`	Pausa a IA nesta conversa para o seu sistema responder.
`POST /v1/conversations/{id}/resume`	Devolve a conversa para a IA.
`GET /v1/media/{id}`	Baixa o arquivo de uma mensagem.

GET/v1/conversations

Listar as conversas

curl "https://boavoz.com/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY"

Resposta · 200

{
  "data": [
    {
      "id": "conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f",
      "bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "channel": "whatsapp",
      "contact": {
        "id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"
      },
      "status": "ai",
      "started_at": "2026-10-19T14:58:02.117Z",
      "last_message_at": "2026-10-19T15:02:11.481Z",
      "message_count": 6,
      "ai_paused_until": null,
      "agent": null,
      "sector": null,
      "snoozed_until": null,
      "ticket": null
    }
  ],
  "next_cursor": "MjAyNi0xMC0xOVQxNTowMjoxMS40ODFafDBlOGY1YTNj"
}

Parâmetro	Regra	Erro
`limit`	De 1 a 100 (padrão 50).	400 `limit`
`cursor`	O `next_cursor` da resposta anterior (null na última página).	400 `cursor`
`bot_id`	Só as conversas deste chatbot (do escopo da chave).	`403 forbidden_scope`
`channel`	`widget`, `whatsapp` ou `instagram`.	400 `channel`
`status`	`ai` (a IA responde), `ai_paused` (pausada pela integração, até `ai_paused_until`), `waiting_human` (pediu atendente e ninguém assumiu) ou `human` (alguém da equipe assumiu: vem em `agent`). Cada conversa traz também o `sector` {id, name} (ou null) o `snoozed_until` (adiada pela equipe na Caixa de entrada até essa data, ou null) e o `ticket` {protocol, status, subject} quando a conversa é um chamado aberto no chat do site (ou null).	400 `status`
`since`	Só as que tiveram mensagem desde a data (ISO 8601, ex.: `2026-10-01T00:00:00Z`).	400 `since`
`contact`	Só as de um contato (endereço).	400 `contact`

GET/v1/conversations/{id}/messages

Da mais antiga para a mais nova, com limit e cursor. Cada mensagem traz a direção (inbound do contato, outbound para ele), a origem (source: contact, ai, human, api, campaign ou phone_app), quem mandou (agent), o status e o arquivo, se houver.

No WhatsApp e no Instagram, reply_to é o id da mensagem citada (o contato ou a equipe respondeu em cima dela; null sem citação) e reactions {contact, agent} traz o emoji que o contato e a empresa deixaram na mensagem (null sem reação). A reação não vira mensagem nova. Mensagem apagada pelo contato vem com deleted true e sem texto.

O histórico de uma conversa

curl "https://boavoz.com/api/v1/conversations/conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f/messages?limit=50" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY"

Resposta · 200

{
  "conversation": {
    "id": "conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f",
    "bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "channel": "whatsapp",
    "contact": {
      "id": "ctc_9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"
    },
    "status": "ai",
    "started_at": "2026-10-19T14:58:02.117Z",
    "last_message_at": "2026-10-19T15:02:11.481Z",
    "message_count": 2,
    "ai_paused_until": null,
    "agent": null,
    "sector": null,
    "snoozed_until": null,
    "ticket": null
  },
  "data": [
    {
      "id": "msg_48209",
      "conversation_id": "conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f",
      "direction": "inbound",
      "source": "contact",
      "text": "Meu pedido já saiu?",
      "media": null,
      "agent": null,
      "status": "received",
      "error": null,
      "deleted": false,
      "edited": false,
      "reply_to": null,
      "reactions": {
        "contact": null,
        "agent": null
      },
      "created_at": "2026-10-19T14:58:02.117Z"
    },
    {
      "id": "msg_48210",
      "conversation_id": "conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f",
      "direction": "outbound",
      "source": "ai",
      "text": "Saiu sim! A previsão é hoje, até as 20h.",
      "media": null,
      "agent": null,
      "status": "read",
      "error": null,
      "deleted": false,
      "edited": false,
      "reply_to": null,
      "reactions": {
        "contact": "👍",
        "agent": null
      },
      "created_at": "2026-10-19T14:58:05.902Z"
    }
  ],
  "next_cursor": null
}

Arquivos e fotos

Mensagem com arquivo traz media {id, type, mime, size, filename, transcript, reading, url, url_expires_at}. O url vale 1 hora; depois, baixe por GET /v1/media/{id}. Áudio vem com a transcrição em transcript.

Foto que a IA leu (WhatsApp e Instagram, em chatbot com tamanho de IA) vem com reading {type, description, text}. Com type comum, description diz o que a foto mostra e text traz o texto escrito nela, sem links, e-mails nem números longos. Os outros tipos não são lidos e vêm sem descrição: comprovante (comprovante de pagamento: a IA nunca confirma pagamento e avisa a equipe), documento (documento pessoal ou cartão), saude (exame, receita ou foto de saúde), impropria e ilegivel. Foto que a IA não leu (modo dados sensíveis, equipe atendendo) vem com reading null.

POST/v1/conversations/{id}/pause

A pausa é da integração: a equipe não é avisada. A IA volta pelo resume, pelo painel, quando alguém da equipe assume ou quando a pausa vence, e responde a última mensagem do contato se ela ficou sem resposta.

Pausar a IA (24 horas, com o anúncio da Ana)

curl -X POST "https://boavoz.com/api/v1/conversations/conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f/pause" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{
  "announce": true,
  "agent_name": "Ana"
}'

Resposta · 200

{
  "ai_paused_until": "2026-10-20T15:05:00.000Z"
}

Pausar por um prazo fixo

curl -X POST "https://boavoz.com/api/v1/conversations/conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f/pause" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{
  "minutes": 10
}'

Resposta · 200

{
  "ai_paused_until": "2026-10-19T15:15:00.000Z"
}

Campo	Regra	Erro
`minutes`	Sem ele, a pausa dura 24 horas e se renova a cada mensagem que você manda pela API nessa conversa. Com ele, de 1 a 10.080 (7 dias), sem renovar.	400 `minutes`
`announce`	`true`: a primeira mensagem da API sai com a apresentação de quem assumiu, e a volta da IA, com o “Voltei!”.	400 `announce`
`agent_name`	O nome na apresentação (até 80 caracteres).	400 `agent_name`

POST/v1/conversations/{id}/resume

Devolve a conversa para a IA na hora (announce opcional, como na pausa). Sai o webhook handoff.returned com reason api.

Devolver a conversa para a IA

curl -X POST "https://boavoz.com/api/v1/conversations/conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f/resume" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{}'

Resposta · 200

{
  "ai_paused_until": null
}

GET/v1/media/{id}

O arquivo decifrado, com Content-Type e Content-Disposition. Depois do prazo de guarda (ou da exclusão dos dados), 410 media_gone.

Baixar o arquivo de uma mensagem

curl "https://boavoz.com/api/v1/media/med_6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -o arquivo

Resposta · 200

(o arquivo, com Content-Type e Content-Disposition)

Aceite do negócio

No WhatsApp e no Instagram, as conversas de um negócio só saem pela API depois que ele fez o aceite do canal (na conexão). Antes disso: 403 feature_suspended com details.feature business_acceptance.

Mensagens →

Responda na conversa pausada.

Webhooks →

message.received e handoff.* em tempo real.