Referência dos endpoints da API
Por Equipe BotConversa · Atualizado em 6 de setembro de 2026
Se você ainda não pegou a chave nem fez a primeira chamada, comece por 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 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ô.
| 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 |
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.
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 |
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 ou o bloco de Integração.
- 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.
- Não expõe relatórios. As métricas ficam no painel e nos relatórios exportáveis.