API do BotConversa: primeiros passos

Este artigo leva você da chave até a primeira mensagem enviada por código. A lista completa do que dá para fazer está em Referência dos endpoints da API.

Onde pego a chave?

1. Acesse Configurações → Geral → Integrações.
2. Na aba Externo, localize o bloco API — ele traz o link para o Swagger e o campo Chave API.
3. Copie a chave desse bloco.

Como autentico?

A chave vai no cabeçalho API-KEY — não é Authorization, nem Bearer, nem parâmetro na URL:

curl https://backend.botconversa.com.br/api/v1/webhook/tags/ \
  -H "API-KEY: sua-chave-aqui"

Se voltar a lista de etiquetas da sua companhia, está tudo certo. A chave já identifica a companhia — não existe parâmetro de conta em nenhum endpoint.

Como testo sem escrever código?

1. Abra backend.botconversa.com.br/swagger.
2. Clique em Authorize, no canto direito, e cole a chave.
3. Escolha um endpoint, clique em Try it out, preencha os campos e execute.

O Swagger mostra a requisição montada e a resposta real da sua companhia. É a forma mais rápida de descobrir o formato de um corpo antes de escrever o código — e de conferir se o problema está no seu lado ou no nosso.

O caminho de sempre: contato primeiro, ação depois

Quase tudo na API gira em torno do contato, e quase todo endpoint pede o subscriber_id. Então o passo um é sempre obter esse id.

1. Criar o contato

POST /api/v1/webhook/subscriber/

{
  "phone": "5511999999999",
  "first_name": "Maria",
  "last_name": "Silva"
}

O telefone vai com DDI, DDO e número, só dígitos — sem +, espaço, parêntese ou traço. Número mal formatado é a segunda causa mais comum de integração que "não faz nada".

2. Achar um contato que já existe

GET /api/v1/webhook/subscriber/get_by_phone/5511999999999/

Devolve o contato com o id. Guarde esse valor no seu sistema junto do registro do cliente — assim você não precisa consultar de novo a cada ação.

3. Agir sobre ele

POST /api/v1/webhook/subscriber/{subscriber_id}/send_message/

{
  "type": "text",
  "value": "Seu pedido saiu para entrega!"
}

O campo type aceita text ou file. Para file, o value é uma URL pública que termina na extensão do arquivo — .pdf, .png, .mp4. O WhatsApp identifica o tipo de mídia pela extensão da URL, então link com query string no fim ou rota dinâmica costuma falhar silenciosamente.

4. Ou disparar um fluxo inteiro

POST /api/v1/webhook/subscriber/{subscriber_id}/send_flow/

{ "flow": 12345 }

Costuma ser melhor que mandar texto solto: o fluxo já carrega os botões, as condições e o encaminhamento para a equipe. Os ids disponíveis vêm de GET /flows/.

Como descubro os ids de fluxos, etiquetas e campos?

Todos têm endpoint de listagem: GET /flows/, GET /tags/, GET /custom_fields/, GET /sequences/, GET /campaigns/. Consulte uma vez, guarde os ids no seu sistema e não fique listando a cada chamada.