---
title: "API do BotConversa: primeiros passos"
url: https://ajuda.botconversa.com.br/aula/api-do-botconversa-primeiros-passos
section: "API e desenvolvedores"
date_modified: 2026-09-06T16:42:18.400212+00:00
language: pt-BR
---

# API do BotConversa: primeiros passos

[Vídeo da aula](https://www.youtube.com/watch?v=8c0RRJ81cPY)

## Resposta rápida

A API fica em `https://backend.botconversa.com.br/api/v1/webhook`. A autenticação é o cabeçalho `API-KEY`, com a chave que está em **Configurações → Geral → Integrações**, no bloco **API**. Para testar sem escrever uma linha de código, use o [Swagger](https://backend.botconversa.com.br/swagger/): clique em **Authorize**, cole a chave e use **Try it out** em qualquer endpoint.

**Tempo de leitura:** ~7 min**Para quem é:** Desenvolvedor

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](/aula/referencia-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.

**Cuidado com o botão Atualizar ao lado da chave.** Ele não recarrega a tela: **gera uma chave nova e invalida a antiga**, derrubando toda integração que estiver usando a anterior. Só use quando a intenção for exatamente essa.

O bloco **API** e o bloco **Zapier** têm chaves **diferentes**, uma embaixo da outra na mesma tela. Copiar a errada devolve `401` e é o erro mais comum de quem está começando. Confira que você pegou a do bloco **API**.

## 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](https://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.

**Se a sua conexão é API Oficial, `send_message` só entrega dentro da janela de 24 horas.** Fora dela, a mensagem não chega e o motivo não aparece na resposta da API. Para alcançar quem está fora da janela, o caminho é disparar um fluxo com modelo aprovado — veja [Entendendo modelos de mensagem](/aula/entendendo-modelos-de-mensagem-templates).

### 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.

## Dicas

-   **Não esqueça a barra final.** Todos os caminhos terminam em `/`. Sem ela, a chamada pode falhar ou ser redirecionada perdendo o corpo do POST.
-   **Guarde o `subscriber_id` no seu banco.** Ele é a chave de praticamente todas as outras chamadas.
-   **Registre a resposta completa nos seus logs.** Sem o corpo do erro, sobra só "não funcionou" — e aí não há como o suporte ajudar.
-   **Nunca ponha a chave no front-end.** Ela dá acesso total à companhia. Chame a API a partir do seu servidor.

## Perguntas frequentes

Recebi 401. O que houve?

A chave está errada, expirada ou você copiou a do Zapier em vez da do bloco API. Confira que o cabeçalho é `API-KEY`, exatamente assim.

Criei o contato mas a mensagem não chegou.

Verifique o telefone (só dígitos, com DDI) e, se você usa API Oficial, se o contato falou com você nas últimas 24 horas.

A API funciona nas duas conexões?

Sim, mas o comportamento de envio muda: na API Oficial vale a janela de 24 horas e a exigência de modelo aprovado fora dela.

Tem limite de requisições?

A tela de Webhooks mostra o teto de requisições da conta. Para volume alto, alinhe com o suporte antes de subir a integração.

Posso usar a API para receber mensagens?

Não por aqui. Para ser avisado de eventos, o caminho é o webhook de entrada ou o bloco de Integração dentro do fluxo — veja [Introdução às integrações](/aula/introducao-as-integracoes).