Documentação · API

API do BoaVoz

Enviar mensagens e campanhas, ler conversas, contatos e leads, pausar a IA numa conversa, ligar contatos às contas do seu sistema e cuidar da cobrança dos chatbots. Esta página tem o que vale para todas as rotas; cada assunto tem a página dele, com os exemplos.

Endereço e chave

Base: https://boavoz.com/api/v1 (a API não responde no domínio próprio das agências). Toda requisição leva a chave no cabeçalho Authorization: Bearer. Nos exemplos, a chave fica na variável de ambiente BOAVOZ_API_KEY.

bash

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

As chaves ficam em Integrações → Chaves de API (dono ou administrador). A chave começa com bv_live_ e aparece uma vez só; o painel mostra só o começo dela. Cada chave tem:

Escopo: todos os chatbots da agência, os de um cliente ou chatbots escolhidos. Fora do escopo, a API responde 404, como se não existisse.
Permissões, uma por assunto:

Permissão	Abre
`messages`	Enviar mensagens, ler uma mensagem e listar os modelos do número.
`conversations`	Listar conversas e mensagens, baixar arquivos, pausar e devolver a IA.
`contacts`	Contatos, leads, etiquetas, idade e o pedido de exclusão do titular.
`campaigns`	Campanhas e lembretes, e registrar o aceite de novidades.
`pairing`	Pareamento: ligar o contato à conta dele no seu sistema.
`sources`	Fontes de conhecimento: texto, planilha CSV, página ou PDF, com o contexto de cada cliente.
`provisioning`	Clientes e chatbots a partir de um modelo, com o contexto e os dados de cada loja, links de conexão, canais e pausa (pacote Plataforma).
`members`	A equipe do portal de cada cliente. Vem desmarcada: o portal mostra e exporta conversas.
`billing`	Uso, tamanho e excedente de cada chatbot, e o crédito da conta. Pode cobrar no cartão da assinatura: só o dono da conta cria chave com ela.

Dê a cada integração só as permissões e o escopo de que ela precisa, e nunca use a chave no navegador ou num app: ela vale para tudo o que o escopo alcança.

A API é do pacote Integrações (R$ 49 por mês, por conta). Sem ele, a chave continua guardada e toda rota responde 403 plan_not_allowed.

Convenções

JSON nos dois sentidos; corpo de até 32 KB.
Ids com prefixo: bot_, cli_, conv_, ctc_ (contato), msg_, med_ (arquivo), lead_, cmp_ (campanha), lnk_ (vínculo), mbr_ (pessoa da equipe).
Limite: 50 requisições a cada 5 segundos por chave. Passou disso: 429 rate_limited com Retry-After.
Registro: cada chamada com chave válida fica 30 dias em Integrações → Logs, com a chave, o caminho, o status, o código do erro e a duração. O corpo e a query não ficam guardados, e o endereço do contato no caminho aparece como {contact}.
Paginação: limit de 1 a 100 (padrão 50) e cursor = o next_cursor da resposta anterior (null na última página).
Idempotency-Key (opcional nos envios; obrigatória em campanhas, na criação de chatbot, na troca de tamanho e na compra de crédito): vale 24 horas por chave de API. A mesma chave com o mesmo corpo devolve a resposta guardada, sem fazer de novo, com o cabeçalho Idempotent-Replayed: true; com outro corpo, 409 idempotency_conflict. Erro de validação, 429 e 5xx não ficam guardados: dá para repetir com a mesma chave.

Endereço do contato

Onde a rota pede um contato (to, {contact}, contact), vale qualquer um destes formatos:

Formato	Quem
`ctc_…`	O id do contato no BoaVoz.
`phone:5511999990000`	O número no WhatsApp (com o 55).
`wa:<BSUID>`	O id de usuário do WhatsApp, quando a Meta não manda o telefone.
`ig:<id>`	O id da pessoa no Instagram (IGSID).
`ext:<id>`	O id da pessoa no seu sistema (depois do pareamento). No envio, pede `channel`.

Erros

Todo erro vem no mesmo formato. details.field aponta o campo com problema; cada página da API lista as regras e os erros dos campos das rotas dela.

json

{
  "error": {
    "code": "invalid_request",
    "message": "to inválido: use ctc_…, phone:5511999999999, wa:<BSUID>, ig:<id> ou ext:<id externo>.",
    "details": { "field": "to" }
  }
}

HTTP	code	Quando
400	`invalid_request`	Campo com problema; `details.field` aponta qual.
401	`invalid_api_key`	Chave ausente, inválida ou revogada.
402	`payment_required`, `payment_overdue`	O cartão da assinatura recusou a cobrança (`details.invoice_url` é a fatura para pagar; vale quando ela for paga), ou o último pagamento da assinatura está em aberto.
403	`forbidden_scope`	A chave não tem a permissão da rota, o chatbot está fora do escopo dela (ou, no crédito e na criação de cliente, ela não vale para a conta inteira).
403	`field_locked`	O campo do chatbot é travado pelo modelo dele (só os campos que o modelo libera aceitam valor próprio).
403	`plan_not_allowed`, `feature_suspended`	A conta não tem o pacote do recurso (a API e a identificação são do pacote Integrações; clientes e chatbots pela API, do Plataforma), ele está suspenso na conta, o canal está suspenso, ou o negócio ainda não fez o aceite do canal.
404	`not_found`	Não existe ou está fora do escopo da chave.
409	`idempotency_conflict`, `conflict`	Idempotency-Key repetida com outro corpo (ou a primeira ainda está em andamento); ou uma subida anterior do chatbot acabou de ser paga (confira e mande de novo).
410	`media_gone`	O arquivo passou do prazo de guarda ou foi apagado.
422	`outside_messaging_window`, `channel_not_connected`, `bot_paused`, `bot_without_size`, `contact_suppressed`, `contact_opted_out`, `no_marketing_consent`, `template_category_mismatch`, `empty_audience`, `channel_rejected`	Regra do canal ou do contato: o BoaVoz confere antes de chamar a Meta e diz o motivo.
422	`subscription_required`, `custom_quota`, `overage_not_available`, `first_week_credit_limit`	Cobrança: a conta ainda não tem assinatura (a primeira é feita no painel), o chatbot tem cota sob medida combinada com a BoaVoz, o excedente pedido num chatbot sem tamanho de IA, ou a compra de crédito passou dos R$ 100 da primeira semana da assinatura.
422	`prohibited_content`	O portão barrou o texto ou um título (a API nunca edita). `details` traz o motivo, os trechos e o canal.
429	`rate_limited`	Limite da chave ou do número; espere o `Retry-After`.
503	`channel_unavailable`	O WhatsApp ou o Instagram está instável; tente de novo depois do `Retry-After`.

Os assuntos

Mensagens →

Texto, modelo, imagem e documento no WhatsApp, no Instagram e no site.

Conversas e pausa →

Conversas, histórico, arquivos, e pausar a IA para o seu sistema responder.

Contatos e leads →

Sincronizar contatos, etiquetas, idade, leads e o pedido do titular.

Campanhas e aceite →

Campanhas de novidades, lembretes e o aceite de novidades.

Pareamento →

Ligar o contato à conta dele no seu sistema.

Fontes →

Texto, página ou PDF, e o documento de cada cliente com o contexto.

Lojas pela API →

Clientes e chatbots a partir de um modelo, pelo seu sistema.

Cobrança →

Uso do mês, tamanho, excedente e crédito.

Prefere testar no Postman? Baixe a coleção e o ambiente (preencha api_key, bot_id e phone). Os exemplos destas páginas saem da mesma fonte da coleção.