Esta é a lista completa das rotas /v1: 189 pares de método e caminho nas tabelas abaixo, mais as 155 rotas do Agente de IA, listadas no guia próprio. As tabelas saem de um inventário verificado contra o código das rotas a cada mudança: rota nova, escopo trocado ou modelo de paginação diferente quebram o teste antes de chegar aqui.
O contrato exato de cada request e response está nos exemplos testados das páginas de guia (Enviar mensagens, Webhooks, Transmissões e limites, entre outras). Cada exemplo roda contra o handler real antes de ser publicado.
Convenções
Base URL de todas as rotas:
https://botozap.com.br/api/v1Toda requisição leva a sua chave de API no header, como X-API-Key ou como Authorization: Bearer. Se os dois vierem, vale o X-API-Key. A conta é derivada da chave, então você nunca passa um id de conta (o isolamento multi-tenant é garantido no servidor). Detalhes em Autenticação.
X-API-Key: $BOTOZAP_KEY
# ou
Authorization: Bearer $BOTOZAP_KEYAs respostas seguem um envelope fixo:
- Sucesso singular:
{ "data": <objeto> }. - Lista por cursor:
{ "data": [...], "paging": {...} }; lista por página:{ "data": [...], "meta": {...} }. Algumas listas curtas (etapas, campos, calendários de uma conexão) vêm inteiras, só comdata. DELETEbem-sucedido costuma responder204sem corpo.- Exceção:
POST /api/v1/messagesresponde direto, semdata:{ id, wamid, to, sent_to, status }, maiswarningsquando há aviso de consentimento esandbox: truecom chave sandbox.
Erros vêm num envelope estruturado com código e mensagem:
{
"error": {
"code": "forbidden_scope",
"message": "Esta chave de API não tem o escopo 'messages:send'."
}
}Os códigos que qualquer rota pode devolver (chave inválida, escopo, sandbox, rate limit, conta em exclusão, acesso ao produto) e o que fazer em cada caso estão em Erros.
Escopos
Cada rota exige um escopo específico (coluna Escopo nas tabelas abaixo). A chave só acessa as rotas cujos escopos ela tem; lista vazia não libera nada. O catálogo completo, agrupado por área, está em Erros e escopos.
Ambiente sandbox
Uma chave bz_sandbox_ só acessa uma allow-list fail-closed de rotas (marcadas "Aceita chave sandbox" nas tabelas). Qualquer outra rota responde 403 sandbox_forbidden. Hoje a lista tem 54 rotas: POST /api/v1/messages, GET /api/v1/messages, GET /api/v1/messages/{id}, GET /api/v1/events, GET /api/v1/templates, POST /api/v1/templates, GET /api/v1/templates/{id}, PATCH /api/v1/templates/{id}, GET /api/v1/contacts, GET /api/v1/conversations, GET /api/v1/conversations/{id}, PATCH /api/v1/conversations/{id}, POST /api/v1/conversations/{id}/read, GET /api/v1/conversations/{id}/assignments, POST /api/v1/conversations/{id}/assignments, GET /api/v1/conversations/{id}/assignments/{assignmentId}, PATCH /api/v1/conversations/{id}/assignments/{assignmentId}, GET /api/v1/conversations/{id}/tools, PATCH /api/v1/conversations/{id}/tools, GET /api/v1/opportunities, POST /api/v1/opportunities, GET /api/v1/opportunities/{id}, PATCH /api/v1/opportunities/{id}, GET /api/v1/opportunities/{id}/activities, GET /api/v1/opportunities/{id}/conversations, POST /api/v1/opportunities/{id}/conversations, DELETE /api/v1/opportunities/{id}/conversations, GET /api/v1/demands, POST /api/v1/demands, GET /api/v1/demands/{id}, PATCH /api/v1/demands/{id}, GET /api/v1/demands/{id}/activities, GET /api/v1/demands/{id}/conversations, POST /api/v1/demands/{id}/conversations, DELETE /api/v1/demands/{id}/conversations, GET /api/v1/radar, GET /api/v1/radar/stage-rules, GET /api/v1/channel_accounts, GET /api/v1/channel_accounts/{id}, GET /api/v1/phone_numbers, GET /api/v1/channel_accounts/{id}/message-rules, POST /api/v1/channel_accounts/{id}/message-rules, GET /api/v1/channel_accounts/{id}/message-rules/{ruleId}, PATCH /api/v1/channel_accounts/{id}/message-rules/{ruleId}, DELETE /api/v1/channel_accounts/{id}/message-rules/{ruleId}, GET /api/v1/channel_accounts/{id}/message-rules/{ruleId}/qr, GET /api/v1/channel_accounts/{id}/comment-rules, POST /api/v1/channel_accounts/{id}/comment-rules, GET /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, GET /api/v1/channel_accounts/{id}/comment-rules/{ruleId}/metrics, PATCH /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, DELETE /api/v1/channel_accounts/{id}/comment-rules/{ruleId}, GET /api/v1/media/{id} e GET /api/v1/media/{id}/download.
Nessas rotas a chave sandbox só enxerga o ambiente dela: números, Contas de canal, contatos, conversas, templates e Eventos sintéticos. O envio aceita qualquer destino e nunca chama a Meta; os números mágicos escolhem o cenário simulado. POST /api/v1/templates cria o template já APPROVED no catálogo sintético. Nas rotas de mídia, só a mídia sintética sandbox-media-0001 responde. No CRM, contato e conversa precisam ser do mesmo ambiente da chave. Veja Sandbox vs. produção.
Paginação
Três modelos coexistem, dependendo do recurso, nunca dois na mesma rota. O rótulo "Paginado por…" em cada linha diz qual vale.
Por cursor
Para coleções grandes e de append. Query params: limit (padrão 20, máximo 100), after e before. A resposta traz:
{
"data": [...],
"paging": {
"cursors": { "before": "...", "after": "..." },
"next": "...",
"previous": "..."
}
}A lista vem do mais novo para o mais antigo. after traz os limit itens imediatamente mais antigos que o cursor (use paging.next); before traz os limit itens imediatamente mais novos que ele, na mesma ordem (use paging.previous).
Rotas por cursor: GET /api/v1/messages, GET /api/v1/broadcasts/{id}/recipients, GET /api/v1/contacts, GET /api/v1/conversations, GET /api/v1/journeys, GET /api/v1/journeys/{id}/runs, GET /api/v1/webhooks, GET /api/v1/webhook_deliveries, GET /api/v1/phone_numbers/{id}/blocked-users, GET /api/v1/team_events, GET /api/v1/api_logs e GET /api/v1/api_logs/meta_hourly.
Por página (offset)
Para coleções pequenas e estáveis. Query params: page e per_page (padrão 20, máximo 100). A resposta traz:
{
"data": [...],
"meta": { "page": 1, "per_page": 20, "total_pages": 3, "total_count": 42 }
}Os mesmos números também vêm nos headers X-Page, X-Per-Page, X-Total-Pages e X-Total. Rotas por página: GET /api/v1/customers, GET /api/v1/customers/{id}/setup_links, GET /api/v1/templates, GET /api/v1/broadcasts, GET /api/v1/conversations/{id}/assignments, GET /api/v1/saved-replies, GET /api/v1/opportunities, GET /api/v1/opportunities/{id}/activities, GET /api/v1/opportunities/{id}/conversations, GET /api/v1/demands, GET /api/v1/demands/{id}/activities, GET /api/v1/demands/{id}/conversations, GET /api/v1/radar, GET /api/v1/appointments, GET /api/v1/appointments/{id}/history, GET /api/v1/appointments/services, GET /api/v1/appointments/schedules, GET /api/v1/appointments/exceptions, GET /api/v1/calendar/connections, GET /api/v1/calendar/jobs, GET /api/v1/channel_accounts, GET /api/v1/phone_numbers, GET /api/v1/channel_accounts/{id}/message-rules, GET /api/v1/channel_accounts/{id}/comment-ai/runs, GET /api/v1/channel_accounts/{id}/comment-rules e GET /api/v1/users.
Cursor de Eventos
Só GET /api/v1/events. A leitura é ascendente e o cursor é um inteiro que cresce por Conta e ambiente: after (padrão 0, exclusivo) e limit (mesmos padrão e máximo do cursor acima). Guarde paging.cursor depois de processar a página e use-o como after na próxima; enquanto os eventos estão guardados, repetir a mesma chamada devolve a mesma página. Cada evento fica 90 dias. Cursor que não é inteiro não negativo responde 422 invalid_cursor.
{
"data": [{ "id": "...", "cursor": "42", "type": "...", ... }],
"paging": { "cursor": "42", "next": null, "has_more": false }
}Mensagens
POST /api/v1/messages envia texto, template ou mídia por link público https (image, video, audio, document, no formato { "link": "https://..." }). Mídia por id não é aceita no envio: responde 422 invalid_request. O media_id de POST /api/v1/media só serve dentro de template.components, no cabeçalho do template.
A resposta 201 traz to (o que você endereçou) e sent_to (o endereço que de fato foi à Meta, depois da normalização). Em template de marketing para contato sem Consentimento registrado (e sem consent_basis no corpo), o envio segue e a resposta traz warnings: [{ code: "consent_unspecified", ... }]; Consentimento revogado recusa com 422 consent_revoked, com ou sem consent_basis: só o contato desfaz a recusa. Em recusas, o erro ganha outcome, retry e next_step (e meta_code quando a Meta respondeu), ver Erros de envio.
Mande o header Idempotency-Key para repetir com segurança: a mesma chave com o mesmo corpo devolve a resposta original, com Idempotency-Replayed: true, sem enviar de novo. Regras e erros em Evitar envio em dobro.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| POST | /api/v1/messages | messages:send | Envia texto, template, mídia por link (image, video, audio, document; audio.voice: true = mensagem de voz do WhatsApp), interactive (botões, lista, botão de link) ou location. reply_to.message_id responde citando uma mensagem da conversa. Responde 201 com id, wamid, to, sent_to, status e, quando houver, reply_to, warnings e sandbox: true. Aceita chave sandbox. |
| GET | /api/v1/messages | messages:read | Lista as mensagens da conta, com reply_to (citada), played_at (voz ouvida) e transcription (áudio recebido já transcrito pela IA). Filtros de canal: channel e channel_account_id. Com conversation_id, a leitura conta como abrir a conversa no registro de atividades (no máximo uma vez a cada 30 minutos por chave). Paginado por cursor. Aceita chave sandbox. |
| GET | /api/v1/messages/{id} | messages:read | Consulta uma mensagem por UUID interno ou wamid. Aceita chave sandbox. |
Contrato detalhado e exemplos em Enviar mensagens.
Eventos
O log durável de Eventos da Conta, o mesmo que alimenta os webhooks, lido em ordem por cursor. Serve para reconciliar depois de uma queda do seu endpoint sem depender de reentrega. Cada ambiente tem o próprio cursor: chave sandbox lê os Eventos sandbox; chave live, os de produção.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/events | events:read | Replay ascendente do log durável de Eventos da Conta, separado por ambiente da chave. after é o último cursor já processado (exclusivo). Paginado pelo cursor de Eventos. Aceita chave sandbox. |
Contrato detalhado e exemplos em Eventos.
Clientes e links de setup
Cada Cliente traz is_self. Com true, é o Cliente que representa o negócio da própria Conta, criado no cadastro (no máximo um por Conta). O campo é só leitura, e nenhuma rota o trata de forma especial; use-o para esconder ou rotular essa camada na sua interface. O DELETE responde 409 customer_in_use enquanto houver conexões ou links de setup vinculados.
O POST de links de setup aceita allowed_connection_types (dedicated e/ou coexistence; padrão dedicated), success_redirect_url, failure_redirect_url e theme_config. Uma lista sem nenhum tipo válido responde 422 invalid_connection_types (tipos desconhecidos ao lado de válidos são ignorados); URL de redirecionamento que não seja https, que traga usuário ou senha ou que passe de 2048 caracteres responde 422 invalid_redirect_url. A resposta traz a url a enviar ao Cliente, status, whatsapp_setup_status (pending, in_progress, completed ou failed), theme_config e expires_at. A página de conexão é sempre em português: language continua aceito por compatibilidade, mas é ignorado (links novos voltam com language: null).
theme_config é a cor de marca da página do link, do WhatsApp e do Instagram: { "primary_color": "#RRGGBB" } no POST e no PATCH. Ela entra nos botões, links e destaques, nos temas claro e escuro. O tom é o da sua marca; a luminosidade só muda o necessário para o texto ficar legível (contraste AA do WCAG) em cada tema. As outras chaves do formato da Kapso (background_color e afins) são aceitas e ignoradas, e não voltam na resposta; a cor volta em minúsculas (#0A66C2 vira #0a66c2). No PATCH, o objeto substitui o tema inteiro: null, {} ou um objeto sem primary_color voltam às cores padrão. Cor fora de #RRGGBB ou valor que não seja objeto responde 422 invalid_theme_config. A janela de autorização da Meta não muda.
Cada link traz connection_billing, que diz o que acontece com a cobrança quando o Cliente conectar. É a mesma conferência que a página de conexão faz antes da janela da Meta, só de leitura: outcome é included (cabe no plano, ou o Cliente já está conectado e só vai somar outro número), occupies_slot (usa um slot adicional vazio que a Conta já tem), creates_slot (cria um slot de R$ 47/mês, com amount_cents: 4700) ou refused. Na recusa, reason diz o motivo: free_cap (Free ou teste grátis: assine o plano), slot_limit (já há 2 slots com fatura em aberto: pague uma) ou billing_customer_required (conta sem cadastro de cobrança: fale com o suporte). message traz o texto pronto para mostrar. Vem null quando não deu para conferir agora; isso nunca significa "incluído".
Cada Cliente traz business_slot: o slot adicional que ele ocupa (slot_id e paused), ou null quando o negócio está no que o plano inclui. Veja Plano e slots adicionais.
O Free permite 1 Cliente, com conexão ou não: criar o segundo responde 402 free_cap. Clientes que já existiam acima do teto (por exemplo, vindos do teste grátis) trazem plan_suspended: true: não conectam canais e não enviam (402 free_cap), mas continuam recebendo. Fica ativo o Cliente com canal conectado há mais tempo ou, sem canal, o mais antigo. Nada é apagado; ao assinar, volta sozinho.
O campo provision_phone_number foi removido em setembro de 2026: o BotoZap não oferece provisionamento de número, e o Cliente conecta o número dele pelo cadastro da Meta. As respostas não trazem mais o campo; se uma integração ainda o enviar, ele é ignorado como qualquer chave desconhecida, sem erro.
Os redirecionamentos acontecem na página de conexão, só em estado final do link. Quando a conexão conclui, a página mostra "Voltando para <host>…" e leva o Cliente para success_redirect_url com status=completed. Confirme se o número está pronto em GET /phone_numbers, porque uma conexão concluída ainda pode ter pendência de registro. Se o link se esgota sem concluir, o destino é failure_redirect_url com status=failed. Nos erros em que dá para tentar de novo, a página oferece "Voltar para <host>", que leva a failure_redirect_url com status=cancelled, e o link continua válido. Todo destino recebe também setup_link_id; os parâmetros que a sua URL já tiver são preservados, e o token do link nunca é enviado. Link expirado ou revogado mostra a página de erro, sem redirecionar. O link do WhatsApp conecta uma vez: depois de gasto (whatsapp_setup_status completed ou failed), também mostra o erro, e o redirecionamento acontece na tentativa que o encerrou.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/customers | customers:read | Lista os seus Clientes. Cada item traz is_self, business_slot (o slot adicional que o Cliente ocupa, ou null) e plan_suspended (true quando o Cliente passou do teto do Free e não conecta nem envia). Paginado por página. |
| POST | /api/v1/customers | customers:write | Cria um Cliente (name, external_customer_id opcional e único na Conta; repetido responde 409 external_id_conflict). Nasce sem Palavra de saída nem de volta. No Free, que permite 1 Cliente, o segundo responde 402 free_cap. |
| GET | /api/v1/customers/{id} | customers:read | Consulta um Cliente, com business_slot (slot_id e paused) ou null, e plan_suspended. |
| PATCH | /api/v1/customers/{id} | customers:write | Atualiza name e/ou external_customer_id (vazio limpa) e as palavras do Cliente: opt_out_keywords (Palavras de saída), opt_in_keywords (Palavras de volta) e os textos opt_out_confirmation e opt_in_confirmation. Não há lista padrão: só valem as palavras cadastradas; a lista enviada substitui a anterior ([] limpa) e a mesma palavra não pode estar nas duas. is_self é só leitura. |
| DELETE | /api/v1/customers/{id} | customers:write | Remove um Cliente sem conexões nem links de setup vinculados; com vínculos responde 409 customer_in_use. O Cliente da própria empresa (is_self: true) não pode ser excluído: 409 self_customer. |
| GET | /api/v1/customers/{id}/setup_links | customers:read | Lista os links de onboarding do Cliente. Cada link traz connection_billing: o que acontece com a cobrança quando o Cliente conectar. Link do WhatsApp com whatsapp_setup_status completed ou failed continua com status active, mas não conecta mais: para conectar de novo, crie outro. Paginado por página. |
| POST | /api/v1/customers/{id}/setup_links | customers:write | Cria um link de onboarding válido por 30 dias, com connection_billing. Cada link conecta um canal: channel omitido vale whatsapp (cadastro da Meta); o outro canal está em Conexão da Conta de canal. A página do link é sempre em português: language é aceito por compatibilidade e ignorado. theme_config ({ primary_color: "#RRGGBB" }) pinta a página com a cor da sua marca; cor inválida responde 422 invalid_theme_config. O link do WhatsApp conecta uma vez: com whatsapp_setup_status completed ou failed, a página mostra o erro de link indisponível, sem redirecionar (o redirecionamento acontece na tentativa que encerrou o link). |
| PATCH | /api/v1/customers/{id}/setup_links/{linkId} | customers:write | Atualiza status (active, expired ou revoked), expires_at ou theme_config (null volta às cores padrão), inclusive para revogar. Não há GET nem DELETE de um link específico. |
Contrato detalhado e exemplos em Quickstart: revenda.
Templates
O POST leva name (minúsculas, números e underscore), language (pt_BR), category (UTILITY, MARKETING ou AUTHENTICATION) e components no formato da Cloud API, além de waba_connection_id ou phone_number_id (os dois saem de GET /phone_numbers). Sem conexão: 422 missing_connection. Payload local inválido: 422 invalid_template. Recusa da Meta: 422 ou 502 meta_error. Em live o 201 volta PENDING; o envio só vale com status APPROVED. Hoje não existe PATCH nem DELETE de template pela API; para editar ou remover, use o painel.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/templates | templates:read | Lista os templates da conta. Com chave sandbox, só os do catálogo sintético. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/templates | templates:write | Cria um template e o submete à Meta. Exige waba_connection_id ou phone_number_id. opt_out_buttons (opcional) lista os textos dos botões de resposta rápida que são de saída. Nome e idioma já no catálogo da conexão: 409 duplicate, sem alterar o existente. Com chave sandbox, nasce APPROVED no catálogo sintético, sem chamar a Meta. Aceita chave sandbox. |
| GET | /api/v1/templates/{id} | templates:read | Consulta um template. Com chave sandbox, só os do catálogo sintético; rejection_reason traz o motivo da Meta quando REJECTED; opt_out_buttons traz os botões marcados como de saída. Aceita chave sandbox. |
| POST | /api/v1/templates/sync | templates:write | Sincroniza com a Meta, como o Sincronizar do painel: status, categoria, conteúdo e rejection_reason de todos os templates das conexões ativas (ou de um Cliente, com customer_id), importa os criados no WhatsApp Manager e remove os excluídos lá. Devolve connections, synced, removed, skipped_without_token e automations_outdated. Autorização recusada pela Meta: 409 reconnect_required. |
| PATCH | /api/v1/templates/{id} | templates:write | Com components (e category opcional), edita o template e o devolve à análise da Meta (status volta a PENDING), como o Editar do painel: nome e idioma não mudam; template em análise responde 409 template_in_review; sem id da Meta, 409 template_not_synced; no sandbox, 422 sandbox_not_supported. Só com opt_out_buttons (textos dos botões; [] limpa), marca quais botões de resposta rápida são de saída, sem alterar o template na Meta; o toque num botão marcado grava a recusa da Finalidade do template. Texto que não é de um botão de resposta rápida do template: 422. Aceita chave sandbox. |
| DELETE | /api/v1/templates/{id} | templates:write | Exclui o template na Meta e aqui, como o Excluir do painel. Com o id da Meta apaga só aquela versão de idioma; sem ele, a Meta apaga todas as do mesmo nome. Não dá para desfazer. Devolve { id, deleted: true }. Só chave de produção. |
Contrato detalhado e exemplos em Templates.
Transmissões
Limites de destinatários por transmissão, quota mensal, rate limit e o messaging limit da Meta são quatro coisas diferentes, detalhadas no guia abaixo.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/broadcasts | broadcasts:read | Lista as transmissões. Paginado por página. |
| POST | /api/v1/broadcasts | broadcasts:write | Cria uma transmissão em rascunho. |
| GET | /api/v1/broadcasts/{id} | broadcasts:read | Consulta uma transmissão, seus contadores de progresso e blocked_reason (por que uma transmissão ativa não avança). |
| PATCH | /api/v1/broadcasts/{id} | broadcasts:write | Transição de estado, não edição de conteúdo: { "status": "stopped" } interrompe uma transmissão sending, scheduled ou warming_up; { "status": "draft" } devolve uma scheduled para rascunho. warming_up só aceita stopped. |
| GET | /api/v1/broadcasts/{id}/recipients | broadcasts:read | Lista os destinatários. Paginado por cursor. |
| POST | /api/v1/broadcasts/{id}/recipients | broadcasts:write | Adiciona destinatários (só em rascunho). |
| DELETE | /api/v1/broadcasts/{id}/recipients | broadcasts:write | Remove todos os destinatários (só em rascunho). |
| POST | /api/v1/broadcasts/{id}/schedule | broadcasts:write | Agenda o envio. |
| POST | /api/v1/broadcasts/{id}/send | broadcasts:write | Dispara o envio (assíncrono, responde 202). |
| POST | /api/v1/broadcasts/{id}/cancel | broadcasts:write | Cancela uma transmissão agendada ou em rascunho. Não interrompe envio em curso nem warming_up; para isso use o PATCH. |
Contrato detalhado e exemplos em Transmissões e limites.
Contatos, etapas e campos
Atenção: DELETE /api/v1/contacts/{id} é síncrono e definitivo. Ele apaga, na mesma chamada, as mensagens, as conversas e os registros de mídia do contato antes do próprio contato. Os arquivos de mídia saem do armazenamento em seguida, em poucos minutos; os que outra mensagem ainda usa permanecem.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/contacts | contacts:read | Lista os contatos. Filtros: metadata[chave]=valor, channel e channel_account_id. Paginado por cursor. Aceita chave sandbox. |
| POST | /api/v1/contacts | contacts:write | Cria um contato. Aceita display_name (nome dado pela sua empresa), metadata e channel_account_id como alternativa a phone_number_id. |
| GET | /api/v1/contacts/{id} | contacts:read | Consulta um contato. |
| PATCH | /api/v1/contacts/{id} | contacts:write | Atualiza profile_name, display_name (null limpa), username, notes, stage_id (null limpa) e metadata (merge raso; null remove a chave). |
| DELETE | /api/v1/contacts/{id} | contacts:write | Apaga o contato na hora, junto com as mensagens, as conversas e os eventos do stream dele. Os arquivos de mídia saem do armazenamento em seguida, em poucos minutos (os que outra mensagem ainda usa ficam). Tudo ou nada: em erro, nada é apagado e dá para repetir. Não há como desfazer. |
| GET | /api/v1/contacts/{id}/consents | contacts:read | Lista o Consentimento vigente e o histórico do Contato. |
| POST | /api/v1/contacts/{id}/consents | contacts:write | Grava Consentimento (canal, Finalidade, estado, evidência; origem api). |
| GET | /api/v1/contact-stages | contacts:read | Lista as Etapas do Funil do Cliente (customer_id), ordenadas por posição. |
| POST | /api/v1/contact-stages | contacts:write | Cria uma Etapa custom (customer_id, label e color). |
| PATCH | /api/v1/contact-stages/{id} | contacts:write | Renomeia, recolore ou define a regra de uma Etapa do Cliente (customer_id, label, color, on_reply_stage_id: para onde o contato vai quando manda mensagem). |
| DELETE | /api/v1/contact-stages/{id} | contacts:write | Exclui uma Etapa custom do Cliente (as de sistema respondem 422). Na mesma transação, os contatos e as oportunidades da etapa ficam sem etapa; cada oportunidade registra a mudança no histórico (crm.opportunity.updated), e as etapas que levavam a ela voltam a não mover (on_reply_stage_id null). |
| PATCH | /api/v1/contact-stages/reorder | contacts:write | Reordena atomicamente todas as Etapas do Cliente (customer_id + stage_ids). |
| GET | /api/v1/contact-fields | contacts:read | Lista os campos personalizados da conta, ordenados por posição. |
| POST | /api/v1/contact-fields | contacts:write | Cria um campo personalizado (label; key e type opcionais, type padrão text). |
| PATCH | /api/v1/contact-fields/{id} | contacts:write | Renomeia ou reordena um campo (label, position; key e type são imutáveis). |
| DELETE | /api/v1/contact-fields/{id} | contacts:write | Exclui a definição do campo (não apaga o dado já gravado no metadata). |
Contrato detalhado e exemplos em Contatos e funil.
Conversas e atribuições
A listagem aceita filtros combináveis: customer_id (as conversas dos números daquele cliente; um customer_id que não seja da sua conta responde 422 invalid_customer, nunca dados de outro tenant), phone_number_id (id da Meta ou UUID interno do número), status (active ou ended, derivado da janela de 24h) e contact (busca parcial por nome, @username, telefone ou wa_id).
include=last_message embute a última mensagem de cada conversa (null quando ainda não há nenhuma), reduzida a id, wamid, direction, type, status, content, event_at, wa_timestamp e created_at. Exemplo testado em Enviar mensagens.
O PATCH da conversa só aceita { "status": "active" | "ended" }. ended encerra a conversa como o painel (preenche closed_at); active a reabre. A janela de 24h não muda: só uma nova mensagem do contato a reabre. Atribuições apontam para membros de GET /users; só uma fica ativa por conversa.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/conversations | conversations:read | Lista as conversas. Filtros: customer_id, phone_number_id, status, contact, channel, channel_account_id e agent_paused=true (só conversas com o agente de IA pausado esperando um humano; outro valor não filtra); expansão include=last_message. Cada conversa traz entry_point (ctwa quando veio de anúncio Click-to-WhatsApp), referral (último clique), fep_expires_at, fep_reply_by e agent_paused_at (ISO ou null). status é ended quando a conversa foi encerrada (closed_at) ou a janela de 24h fechou. Paginado por cursor. Aceita chave sandbox. |
| GET | /api/v1/conversations/{id} | conversations:read | Consulta uma conversa. Ler a conversa grava "conversa aberta" (chave de API e conversa) no registro de atividades, no máximo uma vez a cada 30 minutos por chave. Aceita chave sandbox. |
| PATCH | /api/v1/conversations/{id} | conversations:write | Corpo { "status": "ended" } encerra a conversa como o botão Encerrar do painel (closed_at); "active" a reabre. Nenhum dos dois mexe na janela de 24h. Encerrar também encerra o atendimento da IA: quando o contato escreve de novo, o roteador classifica de novo e a pausa de antes do encerramento sai (agent_paused_at volta a null), salvo envio em andamento ou incerto; active antes disso não zera nada. Mensagem do contato no mesmo instante: 409 conversation_changed. Outro valor: 422 invalid_status. Aceita chave sandbox. |
| POST | /api/v1/conversations/{id}/read | conversations:write | Marca a conversa como lida, como abrir no painel: grava last_read_at e a última mensagem recebida fica como lida para o contato (tiques azuis no WhatsApp, "visto" no Instagram), uma vez por mensagem e por melhor esforço. Sem corpo. Responde 200 com conversation_id e last_read_at. No sandbox, grava sem avisar a Meta. Aceita chave sandbox. |
| DELETE | /api/v1/conversations/{id} | conversations:write | Exclui a conversa na hora, como o Excluir conversa do painel: as mensagens, as notas, o histórico de responsável e o que a IA guardou dela saem; as oportunidades e demandas vinculadas ficam, só sem o vínculo. O contato fica, com a recusa e o consentimento. Os arquivos de mídia saem do armazenamento em seguida, em poucos minutos (os que outra mensagem ainda usa ficam). Responde 204. Tudo ou nada: em erro, nada é apagado e dá para repetir. Conversa de outra Conta ou já excluída: 404. Não há como desfazer. Pelo acesso por OAuth, só Administrador. |
| GET | /api/v1/conversations/{id}/assignments | conversations:read | Lista as atribuições da conversa. Filtro ?active=true|false. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/conversations/{id}/assignments | conversations:write | Atribui a um membro (user_id obrigatório, notes opcional). Desativa a atribuição ativa anterior; disputa simultânea responde 409 assignment_conflict. Aceita chave sandbox. |
| GET | /api/v1/conversations/{id}/assignments/{assignmentId} | conversations:read | Consulta uma atribuição. Aceita chave sandbox. |
| PATCH | /api/v1/conversations/{id}/assignments/{assignmentId} | conversations:write | Altera user_id, notes (null limpa) ou active (false desatribui; true reativa e desativa a outra ativa). Membro inválido: 422 invalid_user. Aceita chave sandbox. |
| POST | /api/v1/conversations/{id}/consent-request | messages:send | Envia o pedido de consentimento com botões, como o composer (botões no WhatsApp, respostas rápidas no Instagram; janela de 24h aberta). Corpo opcional: purposes (marketing e/ou utility; padrão ["marketing"]) e body (até 1024 caracteres). Sai também para quem recusou: o toque no botão desfaz a recusa. Responde 201 com id, wamid (no Instagram, o mid), conversation_id, contact_id, channel, sent_to, purposes e body. Fora da janela: 422 outside_window (WhatsApp) ou 422 window_closed (Instagram). |
| GET | /api/v1/conversations/{id}/pending-sends | conversations:read | Lista os envios manuais do WhatsApp (API e painel) que a Meta não confirmou (timeout ou erro de rede) em cerca de 5 minutos, como o aviso na conversa no painel: id, status (unconfirmed), kind, preview e created_at. Antes desse prazo a confirmação ainda pode chegar, e o envio não aparece; quando a Meta confirma, a mensagem entra no histórico sozinha. Envios da IA, de respostas automáticas, transmissões, réguas e do Instagram têm conciliação própria e não aparecem aqui. |
| POST | /api/v1/conversations/{id}/pending-sends/{sendId} | messages:send | Diz se o envio sem confirmação chegou ao contato, como "Saiu" e "Não saiu" no painel. Corpo { "outcome": "sent" } (saiu: a mensagem entra no histórico, sem o id da Meta) ou { "outcome": "not_sent" } (não saiu: libera para enviar de novo). Nada é reenviado. Responde 200 com id e status. Envio já resolvido: 409 send_not_pending. De outra conversa ou Conta: 404. |
| POST | /api/v1/conversations/{id}/typing | messages:send | Mostra "digitando…" ao contato enquanto a resposta é preparada, como o atendente digitando no painel. Vai na última mensagem recebida, que fica como lida; a Meta tira o indicador quando a resposta sai ou em ~25 s. Sem corpo. Responde 200 com conversation_id, channel, typing e repeated (true quando repetido em menos de 20 s: a Meta não é chamada de novo). Sem mensagem recebida: 409 no_inbound_message. Fora da janela: 422 outside_window (WhatsApp) ou 422 window_closed (Instagram). Canal desconectado: 409 not_connected. Recusa da Meta: 422 meta_error. |
Atendimento: respostas compartilhadas e ferramentas do Inbox
A API não expõe respostas pessoais nem rascunhos. Respostas compartilhadas não aceitam chave sandbox; ferramentas do Inbox respeitam o ambiente da conversa.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/saved-replies | saved_replies:read | Lista as respostas compartilhadas. Paginado por página. |
| POST | /api/v1/saved-replies | saved_replies:write | Cria uma resposta compartilhada; responde 201. |
| GET | /api/v1/saved-replies/{id} | saved_replies:read | Consulta uma resposta compartilhada. |
| PATCH | /api/v1/saved-replies/{id} | saved_replies:write | Edita com expected_updated_at no corpo. |
| DELETE | /api/v1/saved-replies/{id} | saved_replies:write | Exclui com expected_updated_at no corpo. |
| GET | /api/v1/conversations/{id}/tools | inbox:read | Estado, notas e retornos da conversa, com totais separados. Aceita chave sandbox. |
| PATCH | /api/v1/conversations/{id}/tools | inbox:write | Notas, retornos, arquivo e adiamento com controle de versão. Aceita chave sandbox. |
Contrato detalhado e exemplos em Atendimento pela API.
CRM: oportunidades, demandas e Radar
Oportunidades, demandas e o Radar fazem parte do funil, disponível nos planos pagos. Sem esse direito, as rotas respondem 403 feature_unavailable. As listagens exigem customer_id.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/opportunities | crm:read | Lista as oportunidades do Cliente (customer_id obrigatório). Filtros: contact_id, owner_user_id (ou unassigned), stage_id (ou none), status e q. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/opportunities | crm:write | Cria uma oportunidade para um contato do mesmo ambiente da chave; responde 201. Aceita chave sandbox. |
| GET | /api/v1/opportunities/{id} | crm:read | Consulta uma oportunidade. Aceita chave sandbox. |
| PATCH | /api/v1/opportunities/{id} | crm:write | Atualiza uma oportunidade. Aceita chave sandbox. |
| GET | /api/v1/opportunities/{id}/activities | crm:read | Lista o histórico de atividades da oportunidade. Paginado por página. Aceita chave sandbox. |
| GET | /api/v1/opportunities/{id}/conversations | crm:read | Lista as conversas vinculadas. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/opportunities/{id}/conversations | crm:write | Vincula uma conversa (conversation_id no corpo). Aceita chave sandbox. |
| DELETE | /api/v1/opportunities/{id}/conversations | crm:write | Desvincula uma conversa (conversation_id no corpo). Aceita chave sandbox. |
| GET | /api/v1/demands | crm:read | Lista as demandas do Cliente (customer_id obrigatório), com os mesmos filtros das oportunidades. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/demands | crm:write | Cria uma demanda para um contato do mesmo ambiente da chave; responde 201. Aceita chave sandbox. |
| GET | /api/v1/demands/{id} | crm:read | Consulta uma demanda. Aceita chave sandbox. |
| PATCH | /api/v1/demands/{id} | crm:write | Atualiza uma demanda. Aceita chave sandbox. |
| GET | /api/v1/demands/{id}/activities | crm:read | Lista o histórico de atividades da demanda. Paginado por página. Aceita chave sandbox. |
| GET | /api/v1/demands/{id}/conversations | crm:read | Lista as conversas vinculadas. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/demands/{id}/conversations | crm:write | Vincula uma conversa (conversation_id no corpo). Aceita chave sandbox. |
| DELETE | /api/v1/demands/{id}/conversations | crm:write | Desvincula uma conversa (conversation_id no corpo). Aceita chave sandbox. |
| GET | /api/v1/radar | crm:read | Pendências do Radar do Cliente (customer_id obrigatório). Filtros: bucket, entity_type, owner_user_id e reason; meta.counts traz os totais. Paginado por página. Aceita chave sandbox. |
| GET | /api/v1/radar/stage-rules | crm:read | Lista os critérios do Radar por Etapa do Cliente (customer_id). Aceita chave sandbox. |
| PUT | /api/v1/radar/stage-rules/{id} | crm:write | Configura os critérios do Radar de uma Etapa (customer_id e critérios no corpo). Só chave live. |
Contrato detalhado e exemplos em CRM pela API.
Agenda
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/appointments | appointments:read | Lista compromissos. Filtros: customer_id, contact_id, owner_user_id (ou unassigned), service_id, status, date (dia UTC) ou from/to. Paginado por página. |
| POST | /api/v1/appointments | appointments:write | Cria um compromisso (contact_id e scheduled_at obrigatórios). Aceita o header Idempotency-Key; responde 201. |
| GET | /api/v1/appointments/{id} | appointments:read | Consulta um compromisso. |
| PATCH | /api/v1/appointments/{id} | appointments:write | Atualiza um compromisso; expected_revision opcional protege contra edição concorrente. |
| DELETE | /api/v1/appointments/{id} | appointments:write | Exclui um compromisso. Se ele está no Google, cancele e aguarde a sincronização antes (409 calendar_sync_pending). |
| GET | /api/v1/appointments/{id}/history | appointments:read | Histórico de alterações do compromisso. Paginado por página. |
| GET | /api/v1/appointments/availability | appointments:read | Horários livres entre from e to (até 31 dias) para customer_id, owner_user_id e service_id; exclude_id ignora um compromisso ao remarcar. |
| GET | /api/v1/appointments/services | appointments:read | Lista os serviços do Cliente (customer_id). Paginado por página. |
| POST | /api/v1/appointments/services | appointments:write | Cria um serviço; responde 201. |
| PATCH | /api/v1/appointments/services/{id} | appointments:write | Atualiza um serviço (exige expected_revision no corpo). |
| GET | /api/v1/appointments/schedules | appointments:read | Lista as jornadas de atendimento do Cliente (customer_id). Paginado por página. |
| POST | /api/v1/appointments/schedules | appointments:write | Cria a jornada da pessoa no Cliente; responde 201. Uma segunda jornada para a mesma pessoa responde 409 schedule_exists. |
| PATCH | /api/v1/appointments/schedules/{id} | appointments:write | Atualiza uma jornada (exige expected_revision no corpo). |
| GET | /api/v1/appointments/exceptions | appointments:read | Lista as exceções de disponibilidade do Cliente (customer_id). Paginado por página. |
| POST | /api/v1/appointments/exceptions | appointments:write | Cria uma exceção (available ou busy); responde 201. Exceção idêntica (pessoa, dia, intervalo e tipo) responde 409 exception_exists. |
| PATCH | /api/v1/appointments/exceptions/{id} | appointments:write | Atualiza uma exceção (exige expected_revision no corpo). |
| DELETE | /api/v1/appointments/exceptions/{id} | appointments:write | Remove uma exceção; exige expected_revision no corpo. |
Contrato detalhado e exemplos em Agenda pela API.
Google Calendar
A conta Google é conectada pelo painel (em Configurações › Agenda › Calendários). Pela API você lista conexões, escolhe calendários, acompanha a sincronização e resolve conflitos.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/calendar/connections | calendar:read | Lista as contas Google conectadas à Conta. A conexão em si é feita no painel. Paginado por página. |
| DELETE | /api/v1/calendar/connections/{id} | calendar:write | Desconecta uma conta Google. |
| GET | /api/v1/calendar/connections/{id}/calendars | calendar:read | Lista os calendários da conexão e a seleção de cada um. |
| POST | /api/v1/calendar/connections/{id}/refresh | calendar:write | Relê o catálogo de calendários no Google. |
| PATCH | /api/v1/calendar/selections/{id} | calendar:write | Define destination e include_busy de um calendário (exige expected_revision no corpo). |
| GET | /api/v1/calendar/jobs | calendar:read | Lista os jobs de sincronização. Filtro connection_id. Paginado por página. |
| POST | /api/v1/calendar/jobs/{id}/retry | calendar:write | Reenfileira um job de sincronização. |
| POST | /api/v1/calendar/conflicts/{id}/resolve | calendar:write | Resolve o conflito de sincronização de um compromisso ({id} do compromisso) escolhendo choice: "local" ou "remote" (exige expected_revision no corpo). |
Contrato detalhado e exemplos em Agenda pela API.
Réguas
Réguas e acompanhamentos pertencem ao ambiente da chave que os criou. As alterações usam controle de versão: envie a version atual e trate 409 conflict relendo a Régua.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/journeys | journeys:read | Lista as Réguas do ambiente da chave. Filtro customer_id. Paginado por cursor. |
| POST | /api/v1/journeys | journeys:write | Cria uma Régua; responde 201 com a definição completa, com steps. |
| GET | /api/v1/journeys/catalog | journeys:read | Lista os modelos prontos de Régua (os mesmos da galeria do painel), com gatilho, texto do template e exemplos das variáveis. |
| POST | /api/v1/journeys/catalog/{key}/enable | journeys:write | Liga um modelo no Cliente (customer_id): cria e submete o template e cria a Régua (201); se a Régua já existe, responde 200. Se ela está pausada porque a Meta recusou o template, reenvia o template (resubmitted: true) e a Régua liga sozinha na aprovação. |
| GET | /api/v1/journeys/{id} | journeys:read | Consulta a definição completa de uma Régua. |
| PUT | /api/v1/journeys/{id} | journeys:write | Substitui a definição da Régua; exige a version atual. Sem status, mantém o estado atual. Responde a definição completa, com steps. |
| DELETE | /api/v1/journeys/{id} | journeys:write | Arquiva a Régua; exige ?version= atual. |
| POST | /api/v1/journeys/{id}/control | journeys:write | Ação pause, resume ou archive, com a version atual. resume exige templates APPROVED (422 com template_unavailable). |
| GET | /api/v1/journeys/{id}/runs | journeys:read | Lista os acompanhamentos (Disparos) da Régua. Paginado por cursor. |
| POST | /api/v1/journeys/{id}/runs | journeys:write | Inscreve um contato uma vez por occurrence_key; repetição ou alvo fora da regra ativa responde 409 not_enrolled. Contato de número onde o template de um passo não está aprovado responde 422 template_unavailable. |
| GET | /api/v1/journey-runs/{id} | journeys:read | Consulta um acompanhamento com os passos. |
| POST | /api/v1/journey-runs/{id}/control | journeys:write | Ação stop ou acknowledge sobre um acompanhamento (note opcional). |
Contrato detalhado e exemplos em Réguas e consentimento.
Webhooks
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/webhooks | webhooks:read | Lista os webhooks com canais (channel_account_ids) e estado sanitizado de saúde, inclusive por canal (channels_health); o secret não é retornado. Paginado por cursor. |
| POST | /api/v1/webhooks | webhooks:write | Registra um webhook em unverified, de todos os canais ou só dos channel_account_ids informados; o secret aparece somente no 201. |
| GET | /api/v1/webhooks/{id} | webhooks:read | Consulta configuração, canais e saúde sanitizada (resumo e por canal), sem secret. |
| PATCH | /api/v1/webhooks/{id} | webhooks:write | Atualiza URL, Authorization, eventos, customer_id, canais (channel_account_ids), a intenção active ou rotaciona o secret (16–256 caracteres; não é devolvido); URL e Authorization exigem novo teste. |
| DELETE | /api/v1/webhooks/{id} | webhooks:write | Remove um webhook. |
| POST | /api/v1/webhooks/{id}/test | webhooks:write | Verifica e ativa com qualquer 2xx e retoma os canais pausados; falha de destino responde 502 e não entra no streak. |
Contrato detalhado e exemplos em Webhooks.
Contrato de saúde do webhook
active é a intenção manual, enquanto health_statusé automático: unverified, healthy, degraded ou paused. Um endpoint novo não admite eventos reais até o teste POST /api/v1/webhooks/{id}/testretornar 2xx. Para reativar, use esse teste depois de corrigir o destino;PATCH { "active": true } sozinho retorna verification_required.
Depois de verificado, cada canal do endpoint tem fila própria: o retry segue 1 / 2 / 4 / 8 / 16 / 32 / 60 minutos (60 minutos repetidos) pelo streak do canal, e no 15º o canal pausa sem segurar os outros. Alertas ao owner cruzam os streaks 5, 10 e 15 do pior canal. O endpoint só entra em paused quando um canal pausou e nenhum outro canal entregou com sucesso nas 24 horas antes do início das falhas, sem escrever active=false. O backlog de um canal pausado fica retido por 14 dias e é acordado por um novo teste 2xx, se não tiver expirado.
Leituras e o PATCH expõem os campos sanitizados health_status, failure_streak, verified_at, last_success_at, last_failure_at, last_response_code, next_attempt_at, paused_at, channel_account_ids (null = todos os canais) e channels_health (os canais com falha). O secret não aparece nessas leituras. channel_account_ids inválido responde 422 invalid_channel_account_ids; canal de outra Conta ou de outro Cliente, 404 channel_account_not_found; trocar o customer_id sem enviar canais do novo Cliente, 422 channel_accounts_outside_customer. Veja Canais do webhook.
Entregas de webhook
Status inválido no filtro responde 422 invalid_status. pending lista o que ainda aguarda a próxima tentativa.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/webhook_deliveries | webhooks:read | Tentativas de entrega. Filtros: endpoint_id (ou webhook_id), status (pending, success, failed, exhausted) e event_type (nome fino, ex. whatsapp.message.received; categorias não casam). Paginado por cursor. |
| POST | /api/v1/webhook_deliveries/{id}/replay | webhooks:write | Reenvia uma entrega esgotada (exhausted) ou cortada pelo limite do mês (limited), com a mesma X-Idempotency-Key. Sem corpo. Outro status responde 409 delivery_not_replayable; sem saldo no limite do mês, 409 forward_limit_reached. |
Contrato detalhado e exemplos em Webhooks.
Números e Contas de canal
Toda leitura de contato, conversa e mensagem traz channel e channel_account (id, channel, display), por onde a conversa acontece, e a mensagem traz external_id, o id dela no canal (no WhatsApp, o mesmo valor do wamid).
Template, transmissão, saúde de número e reengajamento por template só existem no WhatsApp. Informar uma Conta de canal de outro canal nesses recursos responde 422 channel_not_supported. /api/v1/phone_numbers continua inalterado: quem só fala WhatsApp não precisa migrar para /api/v1/channel_accounts.
Em /health, readiness.state é ready, reconnect_required, blocked, unknown, unavailable ou sandbox. É a mesma decisão do painel: conexão revogada ou bloqueada pela Meta nunca vira healthy por causa de um token válido ou de um status antigo.
O Free permite 1 número. Os outros números conectados continuam recebendo, mas não enviam: o envio responde 402 free_number_cap e a leitura traz plan_suspended: true (também quando o Cliente do número está suspenso). Fica ativo o número que entrou na Conta primeiro; ao assinar ou desconectar o outro, volta sozinho.
O label do PATCH aceita até 100 caracteres. Leituras de número trazem label (ou null) ao lado de display_phone_number e verified_name, que continuam vindo da Meta.
Dar um nome local a um número
Grava o `label` do número, um nome só seu para identificar o número no BotoZap. Os dados da Meta (`display_phone_number`, `verified_name`, `quality_rating`) não mudam. Envie `label: null` ou texto vazio para limpar.
curl https://botozap.com.br/api/v1/phone_numbers/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
-X PATCH \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Loja Centro"
}'Resposta 200
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"phone_number_id": "109876543210987",
"display_phone_number": "+5511999990000",
"verified_name": null,
"label": "Loja Centro",
"quality_rating": "UNKNOWN",
"type": null,
"waba_connection_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"customer_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"waba_id": "waba-xxxx",
"connection_status": "active",
"token_status": "unknown",
"created_at": "2026-07-14T12:00:00.000Z"
}
}`{id}` aceita o UUID interno ou o `phone_number_id` da Meta. Número de outra conta responde 404.
`label` é aparado, vai até 100 caracteres e não aceita quebra de linha. Sem `label` no corpo, a resposta é 422 no_updatable_fields.
Numa Conta de canal do Instagram, o bloco instagram traz a saúde da conexão: connection_status, token_status, token_expires_at e token_refreshed_at. O token do Instagram vale 60 dias e a BotoZap o renova sozinha. token_status é ok, expiring (vence em até 7 dias), expired, invalid (a Meta recusou o token), revoked (conta desconectada) ou unknown (conexão pendente). Com expired, invalid ou revoked, os envios falham até alguém reconectar a conta em Canais. Nenhum token sai na resposta.
Saúde da conexão de uma Conta do Instagram
Na Conta de canal do Instagram, o bloco `instagram` diz se o token da conexão está válido, vencendo ou vencido, sem expor o token.
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel": "instagram",
"customer_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"display": "@lojaexemplo",
"status": "active",
"sandbox": false,
"external_id": "17841400000000001",
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z",
"instagram": {
"instagram_account_id": "17841400000000001",
"username": "lojaexemplo",
"name": "Loja Exemplo",
"instagram_connection_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"connection_status": "active",
"token_status": "ok",
"token_expires_at": "2026-07-14T12:00:00.000Z",
"token_refreshed_at": "2026-07-14T12:00:00.000Z"
}
}
}`token_status`: `ok`, `expiring` (vence em até 7 dias; a renovação automática ainda tenta), `expired`, `invalid` (a Meta recusou o token), `revoked` (conta desconectada) ou `unknown` (conexão pendente). Com `expired`, `invalid` ou `revoked`, os envios falham até reconectar a conta em Canais.
`token_expires_at` é a validade do token atual (60 dias, renovada sozinha a cada ~30); `token_refreshed_at` é a última renovação bem-sucedida. Os dois ficam `null` quando não há registro.
O bloco `whatsapp` só aparece em Conta de canal do WhatsApp, e o `instagram` só na do Instagram.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/channel_accounts/{id}/connection | numbers:read | Consulta estado e diagnóstico da Conexão do Instagram, sem expor tokens nem consultar a Meta. |
| POST | /api/v1/channel_accounts/{id}/connection/resubscribe | numbers:write | Refaz a assinatura na Meta e devolve o estado atualizado. Sem corpo. |
| DELETE | /api/v1/channel_accounts/{id}/connection | numbers:write | Desconecta o Instagram de forma idempotente, preservando histórico. Exige chave de API; OAuth delegado não autoriza. |
| GET | /api/v1/channel_accounts | numbers:read | Lista as Contas de canal (os endpoints de mensagem da conta). Filtros channel e customer_id. Paginado por página. Aceita chave sandbox. |
| GET | /api/v1/channel_accounts/{id} | numbers:read | Consulta uma Conta de canal pelo UUID interno ou pelo id do endpoint na Meta (external_id). Aceita chave sandbox. |
| GET | /api/v1/phone_numbers | numbers:read | Lista os números conectados. Filtro customer_id. plan_suspended: true = o número (ou o Cliente dele) passou do teto do Free: recebe, mas não envia. Paginado por página. Aceita chave sandbox. |
| GET | /api/v1/phone_numbers/{id} | numbers:read | Consulta um número, com plan_suspended. |
| PATCH | /api/v1/phone_numbers/{id} | numbers:write | Grava o label, nome local do número (null ou vazio limpa). É o único campo editável; corpo sem label responde 422 no_updatable_fields. |
| DELETE | /api/v1/phone_numbers/{id} | numbers:write | Desconecta o número do nosso sistema (não desregistra na Meta). Recusa com 409 phone_in_use se houver conversas, mensagens, contatos ou transmissões associados. |
| GET | /api/v1/phone_numbers/{id}/health | numbers:read | Prontidão do número: status legado e readiness (state, reason, next_action, observed_at, stale). Com a conexão ativa, confere ao vivo o token (checks.token_validity) e se a Meta manda as mensagens para o BotoZap (checks.webhook_subscription: subscribed, missing ou unknown). |
| POST | /api/v1/phone_numbers/{id}/webhook-subscription | numbers:write | Inscreve o BotoZap de novo para receber as mensagens do número, com a autorização já guardada, e devolve webhook_subscription (subscribed, missing ou unknown). Resolve a prontidão webhooks_lost sem refazer a conexão quando o app saiu da conta do WhatsApp. Se a conta mudou de portfólio na Meta, a resposta vem missing, e autorização recusada pela Meta responde 409 reconnect_required: nos dois casos, só o link de setup resolve. |
| GET | /api/v1/phone_numbers/{id}/history-import | numbers:read | Conversas antigas do app WhatsApp Business (coexistência): status (awaiting_choice, queued, requested, skipped...), window_days (0, 30 ou 180), window_source (customer ou default), can_choose, default_at e deadline_at. Número sem importação responde 404 history_import_not_available. |
| PUT | /api/v1/phone_numbers/{id}/history-import | numbers:write | Escolhe quanto importar: { "window_days": 0 | 30 | 180 }. Vale uma vez por conexão, enquanto can_choose; a mesma escolha repetida devolve 200, outra devolve 409 history_import_locked. Sem escolha, o último mês vale 20 h depois da conexão. |
Configurações do número do WhatsApp
Perfil do WhatsApp, perguntas prontas e comandos, QR codes com link curto e contatos bloqueados, lidos e gravados direto na Meta (nada fica guardado no BotoZap). {id} é o UUID interno ou o phone_number_id da Meta. Número do sandbox responde 409 sandbox_not_supported; conexão fora do ar, 409 connection_inactive; autorização vencida, 409 reconnect_required. Em coexistência (número também no app WhatsApp Business), a Meta não aceita mudar o perfil pela API.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/phone_numbers/{id}/profile | numbers:read | Perfil do WhatsApp lido na Meta: about, description, address, email, websites, vertical, profile_picture_url e editable (false em coexistência). |
| PATCH | /api/v1/phone_numbers/{id}/profile | numbers:write | Muda campos do perfil na Meta e devolve o perfil relido. Omitido mantém; vazio limpa (menos about). Coexistência responde 409 coexistence_not_supported. |
| POST | /api/v1/phone_numbers/{id}/profile/photo | numbers:write | Troca a foto do perfil: multipart/form-data com file (JPG ou PNG, até 4 MB). |
| GET | /api/v1/phone_numbers/{id}/conversational-automation | numbers:read | Perguntas prontas (prompts, até 4) e comandos (commands, até 30) do número, lidos na Meta. |
| PATCH | /api/v1/phone_numbers/{id}/conversational-automation | numbers:write | Grava perguntas e/ou comandos (omitido mantém, lista vazia remove). Gravar conteúdo exige plano com automações (403 plan_restricted). |
| DELETE | /api/v1/phone_numbers/{id}/conversational-automation | numbers:write | Remove todas as perguntas prontas e comandos do número. |
| GET | /api/v1/phone_numbers/{id}/qr-codes | numbers:read | Lista os QR codes do número: code, prefilled_message e deep_link_url (link curto wa.me/message). |
| POST | /api/v1/phone_numbers/{id}/qr-codes | numbers:write | Cria um QR code com prefilled_message (até 140 caracteres) e image_format PNG ou SVG; responde 201 com qr_image_url. Não é idempotente. |
| GET | /api/v1/phone_numbers/{id}/qr-codes/{code} | numbers:read | Um QR code com qr_image_url temporária no formato image_format (PNG ou SVG). |
| PATCH | /api/v1/phone_numbers/{id}/qr-codes/{code} | numbers:write | Troca a prefilled_message; o código, o link e a imagem continuam os mesmos. |
| DELETE | /api/v1/phone_numbers/{id}/qr-codes/{code} | numbers:write | Apaga o QR code na Meta (sem volta: o código passa a dar "expirado"). Responde 204. |
| GET | /api/v1/phone_numbers/{id}/blocked-users | numbers:read | Contatos bloqueados no número (wa_id, contact_id, name), 100 por página. Paginado por cursor. |
| POST | /api/v1/phone_numbers/{id}/blocked-users | numbers:write | Bloqueia por contact_id ou user (telefone com DDI). Só quem escreveu nas últimas 24 h: senão 422 block_window_closed. |
| DELETE | /api/v1/phone_numbers/{id}/blocked-users/{user} | numbers:write | Desbloqueia pelo wa_id da lista (ou telefone com DDI). |
Contrato detalhado e exemplos em Configurações do número.
Regras de mensagem do Instagram
Automatize directs pelos seis gatilhos. A Regra explícita vence a IA; encaminhamento usa apenas o respondedor publicado. Contrato e exemplos em Regras de mensagem do Instagram.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/channel_accounts/{id}/message-rules | message-rules:read | Lista Regras da Conta de canal por prioridade; paginação por página. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/channel_accounts/{id}/message-rules | message-rules:write | Cria Regra para um dos seis gatilhos; responde 201. Ref ausente é gerado. Aceita chave sandbox. |
| GET | /api/v1/channel_accounts/{id}/message-rules/{ruleId} | message-rules:read | Consulta uma Regra da Conta de canal. Aceita chave sandbox. |
| PATCH | /api/v1/channel_accounts/{id}/message-rules/{ruleId} | message-rules:write | Edita campos presentes; is_active pausa ou ativa. Aceita chave sandbox. |
| DELETE | /api/v1/channel_accounts/{id}/message-rules/{ruleId} | message-rules:write | Exclui a Regra, preservando os Disparos e seus snapshots. Aceita chave sandbox. |
| GET | /api/v1/channel_accounts/{id}/message-rules/{ruleId}/qr | message-rules:read | QR code do link ig.me da Regra (format=png|svg, SVG por padrão), como arquivo para baixar. Aceita chave sandbox. |
Contrato detalhado e exemplos em Regras de mensagem.
Regras de comentário do Instagram
dm_button_title é opcional (até 20 caracteres). Com ele, a abertura vira um template com um botão postback e dm_text aceita até 640 caracteres. Com require_follow=true, a entrega só sai para quem segue.non_follower_text é obrigatório nesse caso (até 640 caracteres): substitui a entrega e reapresenta o mesmo botão. Cada toque consulta o perfil novamente (até 3 segundos); na falha, usa o dado salvo, ou considera que não segue quando não há dado. Há até 3 pedidos de seguir por Disparo. Depois disso, um novo toque de quem já segue ainda entrega, uma única vez. Os dois campos são editáveis em POST/PATCH e retornados em GET, com os mesmos escoposcomment-rules:write/comment-rules:read. O payload é rule:<rule_id>. Configure delivery_text(obrigatório com botão, até 1.000 bytes, pode incluir link) e, se quiser,delivery_media (URL HTTPS pública de imagem). Null ou vazio limpa o campo. O toque abre a janela de 24 horas e envia a entrega uma vez por Disparo; texto livre continua no atendimento normal. Regra inexistente, desativada ou de outro canal é ignorada. O botão aparece no aplicativo do Instagram; a versão web mostra apenas o texto.
Use o UUID interno da Conta de canal em {id}, obtido em GET /api/v1/channel_accounts. Cada regra pertence a uma única Conta de canal; IDs de outra Conta, canal ou ambiente respondem 404.
dm_text é obrigatório na criação, até 1000 bytes sem botão. Os campos opcionais são keyword (até 60 caracteres; null ou vazio significa qualquer comentário), reply_text (até 2200 caracteres; null ou vazio desliga a resposta pública), media_id (ID numérico do post, até 32 dígitos; null ou vazio vale para todos os posts) e is_active (booleano, padrão true). Use keywords e excluded_keywords para listas de até 20 palavras ou expressões (60 caracteres por item). Qualquer palavra-chave casa e qualquer exclusão bloqueia esta regra; ambas ignoram acentos/maiúsculas e exigem palavra inteira.reply_variations aceita até 10 textos (2.200 caracteres cada), alternados na ordem da lista entre novos Disparos. Reentrega e dedupe não avançam a variação.keyword e reply_text espelham o primeiro item; escrever esses campos legados substitui a lista por um item (null limpa a lista). Listas vazias desligam o filtro de palavras ou a resposta pública. O PATCH preserva os campos omitidos. Uma combinação duplicada de palavra-chave inicial e alvo responde 409 duplicate_rule.
Criar ou ativar exige plano pago reconhecido, trial vigente ou graça legada do Free até 31/10/2026. Sem esse direito, a API responde 422 plan_restricted no envelope padrão. Leitura, edição e desativação continuam disponíveis. O estado retornado é active, inactive ou paused_plan; paused_by_plan indica a pausa e is_active preserva a intenção configurada. Ao recuperar o direito, as regras ativas voltam sem reconfiguração.
notice traz o aviso de alcance quando a regra responde a qualquer comentário em todos os posts; nos demais casos é null. As respostas também incluem id, channel_account_id, created_at e updated_at. Chaves sandbox só gerenciam regras de Contas de canal sandbox, que nunca fazem envios reais.
live: true seleciona Durante lives: comentários de qualquer transmissão desta conta, com as mesmas palavras e exclusões. O padrão é false, inclusive nas respostas GET. Regras de posts não disparam em lives e vice-versa. Não combine live: true commedia_id preenchido ou next_post: true (422invalid_request). Para trocar o alcance no PATCH, envie tambémmedia_id: null e next_post: false quando necessário. Enquanto estiver em liberação, a API retorna 422 feature_unavailableno envelope padrão; GET e desativação permanecem disponíveis. O direct só pode sair durante a transmissão. Uma recusa terminal do Instagram fica no Disparo com motivo legível e não é reenviada no replay do webhook. Os escopos continuam comment-rules:read e comment-rules:write.
Criar regra durante lives
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"live": true,
"keywords": [
"LIVE"
],
"excluded_keywords": [
"não quero"
],
"dm_text": "Aqui está o link",
"media_id": null,
"next_post": false
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"keyword": "LIVE",
"keywords": [
"LIVE"
],
"excluded_keywords": [
"não quero"
],
"dm_text": "Aqui está o link",
"dm_button_title": null,
"delivery_text": null,
"delivery_media": null,
"reply_text": null,
"reply_variations": [],
"media_id": null,
"next_post": false,
"next_post_activated_at": null,
"live": true,
"is_active": true,
"status": "active",
"paused_by_plan": false,
"notice": null,
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Disponível depois da liberação: com a flag de lives desligada responde 422 feature_unavailable. O direct só é aceito enquanto a live está no ar. live não pode combinar com media_id preenchido ou next_post=true. GET e PATCH usam o mesmo campo live, sem novos escopos.
next_post: true aguarda o primeiro post publicado após a ativação, registrada pelo servidor em next_post_activated_at. Não combine com um media_id no mesmo corpo. No drainer, a lista paginada/me/media do Instagram Login (Graph v25.0, campos id e timestamp) determina o alvo; um comentário em post antigo não o seleciona. A vinculação é atômica e preenche media_id; depois disso o alvo fica fixo. Pausar/reativar antes de vincular reinicia a espera; depois de vincular mantém o alvo. Para rearmar, envie { next_post: true, media_id: null }. Sem data válida ou após 300 posts sem alcançar a ativação, não fixa alvo: o inbox retenta. Escolha um post específico se precisar superar esse limite.
O Disparo reserva a pessoa pelo autor do comentário, escopado pela conta do Instagram, e deduplica por Regra, post e pessoa antes de enviar. Outro comentário da mesma pessoa no mesmo post não gera um novo Disparo nesta regra. Exclusão usaDELETE /v1/channel_accounts/:id/comment-rules/:ruleId comcomment-rules:write, sem exigir plano de operação; retorna{ data: { id, deleted: true } } e preserva o histórico de Disparos. Recurso ausente, já excluído ou de outro tenant/canal/ambiente retorna 404.
Criar uma Regra de comentário
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"require_follow": true,
"non_follower_text": "Para receber, siga @sua_loja e toque no botão de novo 👇",
"keyword": "boto",
"dm_text": "Toque para receber o link",
"dm_button_title": "Receber link",
"delivery_text": "Aqui está: https://botozap.com.br",
"delivery_media": "https://botozap.com.br/brand/v2/botozap-verificacao-og.png",
"reply_text": "Enviei no direct",
"media_id": "17895695668004550"
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"require_follow": true,
"non_follower_text": "Para receber, siga @sua_loja e toque no botão de novo 👇",
"keyword": "boto",
"dm_text": "Toque para receber o link",
"dm_button_title": "Receber link",
"delivery_text": "Aqui está: https://botozap.com.br",
"delivery_media": "https://botozap.com.br/brand/v2/botozap-verificacao-og.png",
"keywords": [
"boto"
],
"excluded_keywords": [],
"reply_variations": [
"Enviei no direct"
],
"next_post": false,
"next_post_activated_at": null,
"live": false,
"reply_text": "Enviei no direct",
"media_id": "17895695668004550",
"is_active": true,
"status": "active",
"paused_by_plan": false,
"notice": null,
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Com dm_button_title, a abertura usa button template (texto até 640 caracteres, botão até 20). delivery_text é obrigatório e delivery_media opcional (imagem HTTPS). O toque no app entrega uma vez por Disparo; botões não aparecem na web do Instagram.
Use o UUID interno da Conta de canal do Instagram. Criar exige o BotoZap, trial vigente ou graça legada do Free (até 31/10/2026); a recusa é 422 plan_restricted.
Criar regra para o próximo post com exclusões e variações
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules \
-X POST \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"keywords": [
"link",
"quero"
],
"excluded_keywords": [
"não quero"
],
"dm_text": "Aqui está o link",
"dm_button_title": null,
"delivery_text": null,
"delivery_media": null,
"reply_variations": [
"Enviei no direct",
"Confira seu direct"
],
"next_post": true
}'Resposta 201
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"keyword": "link",
"keywords": [
"link",
"quero"
],
"excluded_keywords": [
"não quero"
],
"dm_text": "Aqui está o link",
"dm_button_title": null,
"delivery_text": null,
"delivery_media": null,
"reply_text": "Enviei no direct",
"reply_variations": [
"Enviei no direct",
"Confira seu direct"
],
"media_id": null,
"next_post": true,
"next_post_activated_at": "2026-07-14T12:00:00.000Z",
"live": false,
"is_active": true,
"status": "active",
"paused_by_plan": false,
"notice": null,
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z"
}
}O drainer fixa o primeiro post publicado após next_post_activated_at usando /me/media do Instagram Login. A data é gerada no servidor. keyword e reply_text espelham o primeiro item para clientes antigos.
Excluir uma Regra de comentário
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
-X DELETE \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"deleted": true
}
}Preserva os Disparos e mensagens. Regra já excluída ou de outra Conta/canal/ambiente responde 404 not_found. Excluir não exige direito de operar.
Desativar uma Regra de comentário
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11 \
-X PATCH \
-H "X-API-Key: $BOTOZAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"is_active": false
}'Resposta 200
{
"data": {
"id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"keyword": "boto",
"dm_text": "Toque para receber o link",
"dm_button_title": "Receber link",
"delivery_text": "Aqui está: https://botozap.com.br",
"delivery_media": "https://botozap.com.br/brand/v2/botozap-verificacao-og.png",
"keywords": [
"boto"
],
"excluded_keywords": [],
"reply_variations": [
"Enviei no direct"
],
"next_post": false,
"next_post_activated_at": null,
"live": false,
"reply_text": "Enviei no direct",
"media_id": "17895695668004550",
"is_active": false,
"status": "inactive",
"paused_by_plan": false,
"notice": null,
"created_at": "2026-07-14T12:00:00.000Z",
"updated_at": "2026-07-14T12:00:00.000Z"
}
}Desativar preserva a regra e seu histórico. Para ativar, envie is_active: true; sem direito de operar a API recusa com plan_restricted.
Resultados: GET /v1/channel_accounts/:id/comment-rules/:ruleId/metrics?from&to, com comment-rules:read, inclusive em sandbox e sem exigir plano de operação. Informe os dois instantes ISO 8601 com fuso; from é inclusivo eto exclusivo. Ausência, data inválida ou intervalo invertido retorna 422. A coorte contém os Disparos criados nesse período: comments_matched conta Disparos (comentários deduplicados não geram outro); dms_delivered epublic_replies contam seus estados atuais sent, mesmo se uma retentativa terminou depois do período. DM entregue significa resposta privada aceita pela Meta, sem exigir recibo de entrega ou leitura.
totals traz os totais e posts separa por media_id e live (booleano), incluindo null para post histórico desconhecido. dm_touches conta uma vez cada mensagem recebida com context.quick_reply.payload oucontext.postback.payload exatamente rule:<rule_id>. Até a automação emitir esse payload, toques sem identificação não são atribuídos.touch_rate é toques / DMs entregues, null sem entregas; toques repetidos podem fazê-la superar 1. Não conta clique em URL sem mensagem de retorno.
A resposta precisa chegar após a DM e antes de to. Cada mensagem é atribuída à última DM da Regra identificada no payload ou, sem identificação, à última DM de comentário da Conversa. conversations_opened conta Conversas distintas com resposta (inclui chip/botão): várias mensagens na mesma Conversa contam uma só. Uma Conversa pode aparecer em mais de um post, então a soma dos posts pode superar o total de Conversas. Respostas antes da DM ou de Disparos fora da coorte não contam; retenção das mensagens recebidas limita o histórico.
Consultar resultados da Regra por post
curl https://botozap.com.br/api/v1/channel_accounts/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/comment-rules/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/metrics?from=2026-10-01T00%3A00%3A00Z&to=2026-11-01T00%3A00%3A00Z \
-H "X-API-Key: $BOTOZAP_KEY"Resposta 200
{
"data": {
"rule_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"channel_account_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
"from": "2026-10-01T00:00:00Z",
"to": "2026-11-01T00:00:00Z",
"totals": {
"comments_matched": 4,
"dms_delivered": 2,
"public_replies": 2,
"dm_touches": 1,
"conversations_opened": 1,
"touch_rate": 0.5
},
"posts": [
{
"live": false,
"media_id": "17895695668004550",
"comments_matched": 2,
"dms_delivered": 1,
"public_replies": 1,
"dm_touches": 1,
"conversations_opened": 1,
"touch_rate": 1
},
{
"live": false,
"media_id": null,
"comments_matched": 2,
"dms_delivered": 1,
"public_replies": 1,
"dm_touches": 0,
"conversations_opened": 0,
"touch_rate": 0
}
]
}
}Coorte: Disparos criados em [from,to), estados de envio atuais. Toques e respostas recebidas antes de to; atribuição à última DM anterior na Conversa (payload rule:<rule_id> seleciona a Regra).
DM entregue significa resposta privada aceita pela Meta (dm_status=sent). touch_rate é razão, null sem entregas, e pode superar 1 por toques repetidos. posts identifica lives com live=true e inclui media_id=null quando o post histórico é desconhecido.
Conversas distintas no total; uma mesma Conversa pode aparecer em mais de um post. Payload sem identificação de Regra não conta como toque. Retenção das mensagens recebidas limita o histórico.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/channel_accounts/{id}/comment-rules | comment-rules:read | Lista as regras da Conta de canal. Paginado por página. Aceita chave sandbox. |
| POST | /api/v1/channel_accounts/{id}/comment-rules | comment-rules:write | Cria uma regra. dm_button_title opcional (20 caracteres) transforma dm_text em button template (640 caracteres); delivery_text obrigatório com botão (1.000 bytes), delivery_media opcional (imagem HTTPS). Sem botão mantém texto. Responde 201. Aceita chave sandbox. |
| GET | /api/v1/channel_accounts/{id}/comment-rules/{ruleId} | comment-rules:read | Consulta uma regra e seu estado de operação. Aceita chave sandbox. |
| GET | /api/v1/channel_accounts/{id}/comment-rules/{ruleId}/metrics | comment-rules:read | Resultados por Regra e post da coorte de Disparos [from,to). Exige from e to ISO 8601 com fuso; retorna totals e posts, com touch_rate = dm_touches / dms_delivered (null sem entregas). Aceita chave sandbox. |
| PATCH | /api/v1/channel_accounts/{id}/comment-rules/{ruleId} | comment-rules:write | Edita listas, exclusões, variações, alvo (next_post/media_id), abertura/entrega (dm_button_title, delivery_text, delivery_media) ou ativa/desativa com is_active; campos omitidos são preservados. Aceita chave sandbox. |
| DELETE | /api/v1/channel_accounts/{id}/comment-rules/{ruleId} | comment-rules:write | Exclui a regra, preservando Disparos e mensagens; responde { data: { id, deleted: true } }. Aceita chave sandbox. |
Perguntas e menu do Instagram
Use o UUID da Conta de canal do Instagram. GET lê o desejado salvo; PATCH atualiza as seções informadas (ausente preserva, null remove); DELETE remove ambas; POST sync verifica e reaplica o desejado quando a Meta divergir. Nenhuma dessas rotas aceita sandbox.
A configuração persiste antes da Meta e pode ficar pendente de aplicação. Se a Conexão precisar de autorização, reconecte e repita sync. O contrato detalhado e os exemplos estão em Perguntas e menu do Instagram.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/channel_accounts/{id}/messenger-profile | messenger-profile:read | Lê a configuração salva e o estado da última sincronização. |
| PATCH | /api/v1/channel_accounts/{id}/messenger-profile | messenger-profile:write | Atualiza ice_breakers e/ou persistent_menu; ausente preserva, null ou [] remove. Guarda o desejado e aplica na Meta. |
| DELETE | /api/v1/channel_accounts/{id}/messenger-profile | messenger-profile:write | Remove as duas seções e guarda uma configuração vazia para retries. |
| POST | /api/v1/channel_accounts/{id}/messenger-profile/sync | messenger-profile:write | Sem corpo: verifica a Meta e reaplica a última configuração salva se houver divergência. |
Contrato detalhado e exemplos em Perfil de mensagens.
Mídia
O media_id devolvido por POST /api/v1/media vale por cerca de 30 dias e fica atrelado ao número. Use-o no cabeçalho de um template ({ "id": "..." } dentro de template.components); o envio direto de mídia em POST /api/v1/messages aceita só link. Arquivos maiores que 4,5 MB: use source.
GET /api/v1/media/{id} consulta mídia recebida, pelo media_id da Cloud API que chega na mensagem recebida. No Instagram, use o media.id que vem em instagram.message.received; 410 media_unavailable diz que a URL da Meta expirou antes do espelho, sem retry. No sandbox, só o id sandbox-media-0001 responde.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| POST | /api/v1/media | media:write | Sobe uma mídia para a Meta por source (URL https) ou multipart/form-data com file (até ~4,5 MB), sempre com phone_number_id. O media_id devolvido serve no cabeçalho de template; delivery=meta_resumable_asset devolve um handle para criar template. |
| GET | /api/v1/media/{id} | media:read | Consulta uma mídia recebida: mime_type, file_size, sha256, download_url assinada (1 hora) e expires_at. Ainda espelhando: 202 media_not_ready com Retry-After. Aceita chave sandbox. |
| GET | /api/v1/media/{id}/download | media:read | Redireciona (302) para o download da mídia recebida, com os mesmos estados da rota acima. Aceita chave sandbox. |
Contrato detalhado e exemplos em Mídia.
Usuários
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/users | team:read | Lista os membros do workspace: id (= user_id), email, name e role (owner, admin ou member; no painel, owner e admin aparecem como Administrador e member como Operador). Paginado por página. |
Registro de atividades
Cada evento traz actor (pessoa, chave de API ou sistema), action (por exemplo member.role_changed ou api_key.created), target (tipo, id e nome legível), before e after (só campos não sensíveis; nunca segredo, token ou conteúdo de conversa), ip_address e created_at. since é inclusivo e until exclusivo. Filtro inválido responde 422 com código próprio: invalid_period, invalid_actor, invalid_action ou invalid_target_type. Chave criada por quem deixou de ser Administrador responde 403 admin_required.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/team_events | team:read | Registro de atividades da equipe, do mais novo para o mais antigo, guardado por 12 meses: convites, papéis, chaves de API, canais, webhooks, exclusão da conta, plano. Só Administrador lê (a chave vale enquanto quem a criou for Administrador). Filtros: since/until (ISO 8601), actor_id (pessoa ou chave de API), action, target_type e target_id (por exemplo, o id da conversa). Paginado por cursor. |
Logs de API
since é inclusivo e until exclusivo. environment=unknown traz os registros antigos, anteriores à coleta do ambiente. Filtro inválido responde 422 com código próprio: invalid_environment, invalid_phone, invalid_period ou invalid_status_code. Em /api_logs/meta_hourly, channel_account_id fora do formato responde 422 invalid_channel_account, e de outra Conta, 404 not_found.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/api_logs | logs:read | Requisições feitas à API. Cada linha traz request_id, o mesmo x-request-id da resposta (nulo nos registros mais antigos e nos avisos da Meta). Filtros: environment (live ou unknown), phone_number_id (UUID interno), since/until (ISO 8601), source, method e status_code. Com source=meta_webhook, só os avisos da Meta que o BotoZap desistiu de processar (status_code 500 e error_code processing_failed). A linha entra quando o BotoZap desiste, horas depois da chegada, mas com o created_at da chegada: para achá-la, filtre por since/until em vez de ler só as linhas novas. Todos os avisos, contados por hora, estão em GET /api/v1/api_logs/meta_hourly. Paginado por cursor. |
| GET | /api/v1/api_logs/meta_hourly | logs:read | Avisos que a Meta mandou à Conta, contados por hora. Cada item é uma hora (hour, o começo dela), com received (os recebidos), failed (os que o BotoZap desistiu de processar, o que só entra horas depois) e channels (a conta de cada número ou conta do Instagram, por channel_account_id). Hora sem aviso não vem. A contagem das últimas 24 h é refeita aos 5 minutos de cada hora: partial marca a hora que ainda não fechou (entre :00 e :05, a anterior; a hora em curso só aparece depois dos :05). Filtros: channel_account_id e since/until (ISO 8601, comparados com o começo da hora). limit conta horas (máximo 100); com muitos canais, a página traz menos horas, e o cursor segue. O sandbox não entra. Paginado por cursor. |
Custo Meta
O valor é o aproximado que a Meta devolve, na moeda da WABA; a fatura da Meta é a autoridade. Nada é convertido e moedas diferentes vêm em grupos separados (totals, by_day, by_category, cada item com currency). A resposta traz source: "meta_pricing_analytics" e approximate: true. Cliente de outra Conta responde 404 not_found. Quando a Meta não devolve custo (WABA na linha de crédito de um parceiro), cost vem null, nunca 0, com unavailable: true e unavailable_reason: "cost_not_returned"; WABA ativa ainda não sincronizada responde unavailable_reason: "not_synced". Os dados são atualizados uma vez por dia e os últimos 7 dias são relidos para absorver revisões da Meta; sync.last_synced_at e sync.covered_from mostram o frescor e o primeiro dia coberto.
Estimativa. Cada grupo também traz estimated_cost e cost_source (meta, estimate, mixed ou null). Onde a Meta não informou custo, estimamos pelo volume de mensagens cobradas (REGULAR) × tarifa publicada pela Meta para destinatários no Brasil, na moeda da WABA (BRL ou USD); mensagens grátis (FREE_*) contam 0. Categoria ou moeda sem tarifa publicada conhecida (ex.: MARKETING_LITE) deixa estimated_cost: null — nada é inventado. O campo cost continua sendo só o valor da Meta. O objeto estimate informa a base (basis: "published_rates", market: "BR", rates_effective_from, rates_as_of, source_url), o que ela não considera (excludes: descontos por faixa de volume e destinatários fora do Brasil) e se cobre todo o recorte (available).
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/usage/meta-costs | customers:read | Volume e custo das mensagens informados pela Meta (Pricing Analytics), por dia e por categoria. Query: customer_id (opcional), from e to (YYYY-MM-DD, inclusivos; padrão 30 dias; máximo 366). |
Plano e slots adicionais
O plano pago inclui 1 negócio. Cada negócio a mais ocupa um slot adicional de R$ 47/mês, com fatura própria. Ao conectar um Cliente novo além do incluso, ele usa um slot vazio ou ganha um slot novo; conectar outro número de um Cliente já conectado não muda nada, porque a cobrança é por negócio. Estas rotas aceitam só chave de API de produção com os escopos billing:read e billing:write; aplicativos conectados por OAuth não as acessam.
GET /billing devolve plan, included_businesses (null = sem limite), legacy_extra_businesses (extras do contrato antigo), slot_amount_cents, can_add_slot, guarantee e slots. guarantee é null sem direito à garantia de 7 dias; dentro dela traz term (monthly ou annual), amount_cents (o valor da primeira cobrança, que volta integral se a assinatura for cancelada na tela Plano) e deadline (fim do prazo, ISO). Não cobre tarifas da Meta, negócio extra nem slot adicional. Cada slot traz id, customer_id e customer_name (ou null se vazio), paid, next_due_date, invoice_url (link da fatura em aberto; null enquanto não houver), paused e created_at.
POST /billing/slots compra um slot vazio, como o botão da tela Plano. Mande Idempotency-Key para poder repetir com segurança: a mesma chave devolve o mesmo slot com 200 e nunca cria outra cobrança. A fatura pode levar alguns instantes: se invoice_url vier null, consulte GET /billing depois. Recusas: 402 plan_required (assine o plano), 402 slot_limit (pague uma das faturas em aberto), 402 billing_customer_required (fale com o suporte) e 503 billing_not_configured.
DELETE /billing/slots/{id} cancela só slot vazio; o slot adicional não entra na garantia de 7 dias e não há reembolso. Slot ocupado responde 409 slot_in_use: desconecte o negócio antes. Quando a fatura de um slot ocupado vence há mais de 7 dias, só aquele negócio fica pausado e o envio responde 402 business_payment_required; pagou, libera na hora.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/billing | billing:read | Plano (paid, free, trial ou courtesy), negócios incluídos, extras antigos e os slots adicionais abertos: quem ocupa, se está pago, vencimento, link da fatura e pausa. |
| POST | /api/v1/billing/slots | billing:write | Compra um slot adicional vazio de R$ 47/mês, com fatura própria. Idempotency-Key opcional: a mesma chave devolve o mesmo slot. Responde 201 com o slot. |
| DELETE | /api/v1/billing/slots/{id} | billing:write | Cancela um slot vazio, sem reembolso. Ocupado responde 409 slot_in_use; já cancelado responde 204. |
Exportação de dados
A exportação leva os seus dados para fora do BotoZap sem pedido formal e sem prazo de carência: contatos (com campos, tags, etapa e consentimento), conversas, mensagens (texto, tipo, direção, data e status), transmissões e o registro de envio (destinatários de transmissões e mensagens enviadas pela API, com o status de cada uma). Vale para a Conta inteira ou, com customer_id, para um Cliente. É a mesma exportação do painel, em Configurações › Exportar dados, e atende também ao pedido de portabilidade do titular (LGPD, art. 18, V). Estas rotas aceitam só chave de API de produção com os escopos exports:read e exports:write; aplicativos conectados por OAuth não as acessam.
POST /exports aceita { "customer_id": "…", "format": "json" } (os dois campos são opcionais; format é json ou csv). Responde 202 com o pedido em status: "pending". O arquivo é gerado em fila: consulte GET /exports/{id} até status: "ready"; então download.url é um link assinado que vale poucos minutos (download.expires_in, em segundos). Peça de novo para receber outro link. O arquivo é um .zip com um arquivo por tipo (contatos, conversas, mensagens, transmissoes, envios) e um LEIA-ME.txt, e é apagado sozinho 7 dias depois de pronto (expires_at; depois disso o status é expired). As mídias (fotos, áudios, documentos) não vão no arquivo: cada mensagem traz nome, tipo e tamanho da mídia.
Um pedido igual (mesmo escopo e formato) enquanto o anterior ainda está na fila devolve o mesmo pedido com 200. Recusas: 404 not_found (cliente de outra Conta), 422 invalid_request, 429 rate_limited (6 pedidos por hora) e 409 account_deletion_in_progress (a exclusão do workspace já começou). Com a exclusão confirmada e ainda não iniciada, o workspace fica 30 dias em somente leitura, e POST /exports segue liberado: é o momento de levar os dados.
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/exports | exports:read | Os últimos 50 pedidos de exportação da Conta, do mais novo ao mais antigo, com status (pending, processing, ready, failed, expired), escopo, tamanho e contagem de linhas. O link de download só vem em GET /exports/{id}. |
| POST | /api/v1/exports | exports:write | Pede a exportação completa da Conta, ou de um Cliente (customer_id): contatos, conversas, mensagens, transmissões e registro de envio. format: json (padrão) ou csv; o arquivo é um zip com um arquivo por tipo, gerado em fila. Responde 202 com o pedido; um pedido igual ainda na fila devolve o mesmo (200). |
| GET | /api/v1/exports/{id} | exports:read | Status do pedido. Pronto e dentro do prazo (7 dias), traz download.url, um link assinado que vale poucos minutos (download.expires_in); peça de novo para receber outro. Pedido de outra Conta responde 404. |
Agente de IA
As 155 rotas /api/v1/ai cobrem agentes e versões, credenciais BYOK, provedores, conhecimento, memória, skills, follow-ups, roteadores, casos, alertas, avisos, propostas, execuções e orçamento. Use agents:read para leitura e agents:write para alterações; nenhuma aceita chave sandbox. A Conta vem da chave autenticada; o Cliente é informado em customer_id. A tabela completa, verificada contra o código, está em Agente de IA pela API. Rotas por recurso: agents (12), alerts (3), cases (8), commercial-proposals (6), credentials (6), eligibility (6), evolution (1), executions (3), files (4), followup-flows (10), followups (12), inferences (1), knowledge (18), memory (13), notices (8), operator-metrics (1), promises (1), proposals (5), providers (6), routers (8), skills (13), style-adjustments (2), uploads (2), usage (6).
O controle do agente numa conversa fica fora de /api/v1/ai:
| Método | Caminho | Escopo | Descrição |
|---|---|---|---|
| GET | /api/v1/channel_accounts/{id}/comment-ai | agents:read | Configuração opt-in, teto diário, respostas de hoje e pré-requisitos da IA de comentários. |
| PATCH | /api/v1/channel_accounts/{id}/comment-ai | agents:write | Altera enabled, agent_id e daily_limit (1–200); OAuth dashboard-only. |
| GET | /api/v1/channel_accounts/{id}/comment-ai/runs | agents:read | Comentários tratados e motivos legíveis; da decisão à resposta confirmada. Paginado por página. |
| POST | /api/v1/conversations/{id}/agent-control | agents:write | Pausa ou retoma o agente de IA na conversa: { "action": "pause" | "resume" }. |
Contrato detalhado e exemplos em Agente de IA pela API.
