--- title: "Referência dos endpoints da API" url: https://ajuda.botconversa.com.br/aula/referencia-dos-endpoints-da-api section: "API e desenvolvedores" date_modified: 2026-09-06T16:41:47.336202+00:00 language: pt-BR --- # Referência dos endpoints da API ## Resposta rápida São **30 endpoints**, todos sob `https://backend.botconversa.com.br/api/v1/webhook` e autenticados pelo cabeçalho `API-KEY`. Estão agrupados abaixo por assunto: contatos, etiquetas, campos, fluxos, sequências, campanhas e equipe. Para testar qualquer um com a sua chave, use o [Swagger](https://backend.botconversa.com.br/swagger/). **Tempo de leitura:** ~8 min**Para quem é:** Desenvolvedor Se você ainda não pegou a chave nem fez a primeira chamada, comece por [API do BotConversa: primeiros passos](/aula/api-do-botconversa-primeiros-passos). Os caminhos abaixo são relativos à base, e **todos terminam em barra**. ## Contatos O contato é o centro da API: o `subscriber_id` devolvido aqui é o que abre quase todas as outras chamadas. Método Caminho O que faz GET `/subscribers/` Lista os contatos da companhia POST `/subscriber/` Cria um contato (`phone`, `first_name`, `last_name`, `has_opt_in_whatsapp`) GET `/subscriber/get_by_phone/{phone}/` Busca pelo telefone e devolve o `id` DELETE `/subscriber/{id}/delete/` Remove o contato da companhia POST `/subscriber/{id}/send_message/` Envia mensagem avulsa (`type`: `text` ou `file`) POST `/subscriber/{id}/send_flow/` Dispara um fluxo (`flow`: id numérico) POST `/subscriber/{id}/change_conversation_status/` Muda o status da conversa no Inbox ## Etiquetas Método Caminho O que faz GET `/tags/` Lista as etiquetas com seus ids POST `/subscriber/{id}/tags/{tag_id}/` Aplica a etiqueta ao contato DELETE `/subscriber/{id}/tags/{tag_id}/` Remove a etiqueta do contato Aplicar e remover usam o **mesmo caminho**, mudando só o verbo — e nenhum dos dois tem corpo. Veja [Criando e usando etiquetas](/aula/criando-e-usando-etiquetas) para o que a etiqueta significa na operação. ## Campos personalizados e campos do robô São coisas diferentes, e confundi-las é fonte garantida de bug. **Campo personalizado** guarda um valor _por contato_. **Campo do robô** é uma variável global da companhia, igual para todo mundo. O detalhe está em [Campos do Usuário e Campos do Robô](/aula/campos-do-usuario-e-campos-do-robo). Método Caminho O que faz GET `/custom_fields/` Lista os campos personalizados e seus ids POST `/subscriber/{id}/custom_fields/{custom_field_id}/` Grava o valor do campo naquele contato DELETE `/subscriber/{id}/custom_fields/{custom_field_id}/` Limpa o valor do campo naquele contato GET `/bot_fields/` Lista os campos do robô POST `/bot_fields/{bot_variable_id}/` Define o valor de um campo do robô ## Fluxos Método Caminho O que faz GET `/flows/` Lista os fluxos com seus ids — a origem do `flow` usado em `send_flow` Não existe endpoint para **criar ou editar** fluxo. O fluxo é montado no construtor; a API só o dispara. Se o seu plano depende de gerar fluxos por código, ele não é viável hoje. ## Sequências Método Caminho O que faz GET `/sequences/` Lista as sequências com seus ids POST `/subscriber/{id}/sequences/{sequence_id}/` Inscreve o contato na sequência DELETE `/subscriber/{id}/sequences/{sequence_id}/` Retira o contato da sequência ## Campanhas Método Caminho O que faz GET `/campaigns/` Lista as campanhas POST `/campaigns/create/` Cria uma campanha GET `/campaigns/{id}/` Detalha uma campanha DELETE `/campaigns/{id}/` Exclui a campanha POST `/subscriber/{id}/campaigns/{campaign_id}/` Inscreve o contato na campanha DELETE `/subscriber/{id}/campaigns/{campaign_id}/` Retira o contato da campanha Campanha e transmissão não são a mesma coisa — a diferença está em [Diferença entre campanha e transmissão](/aula/diferenca-entre-campanha-e-transmissao). ## Equipe Método Caminho O que faz GET `/managers/` Lista os membros da equipe POST `/managers/` Cria um membro GET `/managers/{id}/` Detalha um membro PATCH `/managers/{id}/` Altera dados do membro DELETE `/managers/{id}/` Remove o membro Os endpoints de **equipe** criam e apagam acessos ao painel. Trate-os com o mesmo cuidado de uma tela de administração: um `DELETE` disparado por engano tira uma pessoa do atendimento. Veja [Permissões e papéis](/aula/permissoes-e-papeis). ## O que a API não faz? Vale saber antes de desenhar a integração: - **Não recebe mensagens.** Para reagir a eventos, use o [webhook de entrada](/aula/configurando-webhooks) ou o [bloco de Integração](/aula/bloco-integracao). - **Não cria nem edita fluxos.** Só dispara os que já existem. - **Não gerencia modelos de mensagem.** Eles vivem na Meta — veja [Entendendo modelos de mensagem](/aula/entendendo-modelos-de-mensagem-templates). - **Não expõe relatórios.** As métricas ficam no painel e nos relatórios exportáveis. ## Dicas - **Cacheie os ids.** Etiquetas, fluxos, campos e sequências mudam pouco. Liste uma vez e guarde. - **Prefira `send_flow` a `send_message`** quando houver qualquer ramificação: o fluxo já traz botões, condições e transferência para a equipe. - **Trate DELETE como definitivo.** Nenhum dos endpoints de exclusão tem desfazer. - **Confirme no Swagger antes de abrir chamado.** Se a requisição funciona lá e falha no seu código, a diferença está no seu lado — normalmente cabeçalho ou barra final. ## Perguntas frequentes Por que a base termina em `/webhook` se é uma API REST? É herança do nome original do recurso. Apesar do caminho, são endpoints REST comuns — e não têm relação com a aba Webhooks do painel. Existe paginação nas listagens? Confira a resposta real da sua companhia pelo Swagger: o formato exibido lá é o que o seu código vai receber. Posso usar a mesma chave em várias companhias? Não. A chave pertence a uma companhia e já a identifica — por isso nenhum endpoint pede id de conta. Qual a diferença entre `/subscribers/` e `/subscriber/`? O plural lista contatos. O singular opera sobre um contato — criar, buscar e agir sobre ele. A API muda sem aviso? O Swagger é gerado do que está no ar, então ele é sempre a versão atual. Vale conferir por lá antes de subir mudanças grandes.