Quickstart: revenda

Para agência ou integrador que opera vários negócios na mesma Conta: cada negócio vira um Cliente, conecta o próprio WhatsApp por um link e recebe mensagens pelo número dele.

Na BotoZap, a sua empresa é a Conta e cada negócio atendido é um Cliente. A Conta vem da chave de API, então você nunca passa um id de conta, e o isolamento é garantido no servidor. O vocabulário completo está em Conceitos. Se você opera um negócio só, o quickstart do seu número é mais curto.

1. Gere uma chave de produção

Em Configurações › Desenvolvedores › Chaves de API, no painel, gere uma chave Produção (bz_live_) com customers:write, numbers:read, webhooks:write e messages:send. Chaves sandbox não acessam Clientes nem links de setup e recebem 403 sandbox_forbidden. Para experimentar o envio antes, use Primeiros passos.

2. Crie o Cliente

Criar um cliente

Cria um Cliente (um negócio atendido por você) na Conta da chave. Cada número conectado pertence a um Cliente.

curl https://botozap.com.br/api/v1/customers \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Padaria Boto"
}'

Resposta 201

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "name": "Padaria Boto",
    "external_customer_id": null,
    "is_self": false,
    "created_at": "2026-07-14T12:00:00.000Z",
    "updated_at": "2026-07-14T12:00:00.000Z"
  }
}

`external_customer_id` é opcional: use o id do cliente no seu sistema. O valor é único por Conta; repeti-lo responde 409 `external_id_conflict`.

A Conta vem da chave. Não existe `account_id` no corpo.

O Cliente abre a url e conecta o WhatsApp oficial pelo cadastro da Meta (Embedded Signup), sem compartilhar senha com você. O número conectado fica vinculado a esse Cliente. Pelo painel, o mesmo fluxo está em Clientes e Links de setup. A página do link é sempre em português: o campo language continua aceito por compatibilidade, mas é ignorado. Cada link conecta um canal; channel omitido vale whatsapp.

Gerar um link de setup para o cliente

Cria o link que o cliente abre para conectar o WhatsApp oficial pelo cadastro da Meta (Embedded Signup), sem compartilhar senha com você.

curl https://botozap.com.br/api/v1/customers/5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11/setup_links \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channel": "whatsapp",
  "allowed_connection_types": [
    "dedicated",
    "coexistence"
  ],
  "success_redirect_url": "https://exemplo-integracao.com.br/onboarding/ok",
  "theme_config": {
    "primary_color": "#0a66c2"
  }
}'

Resposta 201

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "channel": "whatsapp",
    "status": "active",
    "whatsapp_setup_status": "pending",
    "url": "https://botozap.com.br/whatsapp/setup/...",
    "allowed_connection_types": [
      "dedicated",
      "coexistence"
    ],
    "language": null,
    "success_redirect_url": "https://exemplo-integracao.com.br/onboarding/ok",
    "failure_redirect_url": null,
    "theme_config": {
      "primary_color": "#0a66c2"
    },
    "expires_at": "2026-07-14T12:00:00.000Z",
    "created_at": "2026-07-14T12:00:00.000Z",
    "updated_at": "2026-07-14T12:00:00.000Z"
  }
}

O link vale 30 dias. Quando o número fica conectado, o BotoZap emite o Evento `whatsapp.phone_number.connected` (categoria `account`, com `customer_id`, `waba_id`, `phone_number_id`, `connection_mode` e `setup_link_id`) no seu webhook e em `GET /api/v1/events` — sem precisar de polling. `whatsapp_setup_status` (`pending` → `in_progress` → `completed` ou `failed`) em `GET /api/v1/customers/{id}/setup_links` continua disponível.

`allowed_connection_types` aceita `dedicated` (número só na API) e `coexistence` (API e aplicativo no mesmo número). Omitido, vale `dedicated`.

Cada link conecta um canal. `channel` omitido vale `whatsapp`; os outros valores estão na referência da API.

`provision_phone_number` foi removido: o BotoZap não provisiona número. Se enviado, é ignorado e não volta na resposta.

Para revogar, envie `PATCH /api/v1/customers/{id}/setup_links/{linkId}` com `status: "revoked"`.

A página do link é sempre em português. `language` é aceito por compatibilidade e ignorado: links novos voltam com `language: null`.

`success_redirect_url`/`failure_redirect_url` precisam ser `https`. Ao concluir, a página de conexão leva o cliente para a URL de sucesso com `setup_link_id` e `status=completed`; link esgotado vai para a de falha com `status=failed`, e desistência, com `status=cancelled`.

`theme_config.primary_color` (`#RRGGBB`) pinta a página do link com a cor da sua marca, nos temas claro e escuro; a luminosidade se ajusta só o necessário para o texto ficar legível. As outras chaves do formato da Kapso são aceitas e ignoradas, e a cor volta em minúsculas. Omitido ou `null`, a página usa as cores padrão. Para trocar ou apagar depois, `PATCH` com `theme_config`: o objeto substitui o tema inteiro, e sem `primary_color` o link volta às cores padrão.

4. Encontre o número do Cliente

Depois que o link chega a completed, liste os números. Cada item traz customer_id, e a listagem aceita o filtro ?customer_id= para trazer só os números de um Cliente.

Listar números conectados

Lista os números da conta, paginado por página (`page`/`per_page`).

curl https://botozap.com.br/api/v1/phone_numbers?page=1&per_page=2 \
  -H "X-API-Key: $BOTOZAP_KEY"

Resposta 200

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total_pages": 1,
    "total_count": 1
  }
}

5. Receba os eventos

Um endpoint com customer_id: null recebe os eventos de todos os Clientes da Conta. Informe o customer_id para separar um endpoint por Cliente. Em qualquer caso, o endpoint só passa a receber eventos reais depois do teste assinado respondido com 2xx (Webhooks).

Registrar um endpoint de webhook

Cria o endpoint com `health_status=unverified`: mesmo com `active=true`, eventos reais só são admitidos depois de um teste assinado com resposta 2xx.

curl https://botozap.com.br/api/v1/webhooks \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemplo-integracao.com.br/webhooks/botozap",
  "events": [
    "messages",
    "statuses"
  ],
  "customer_id": null,
  "channel_account_ids": null
}'

Resposta 201

{
  "data": {
    "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "customer_id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
    "channel_account_ids": null,
    "url": "https://exemplo-integracao.com.br/webhooks/botozap",
    "events": [
      "messages",
      "statuses"
    ],
    "active": true,
    "has_authorization": false,
    "health_status": "unverified",
    "failure_streak": 0,
    "verified_at": null,
    "last_success_at": null,
    "last_failure_at": null,
    "last_response_code": null,
    "next_attempt_at": null,
    "paused_at": null,
    "channels_health": [],
    "secret": "whsec_...",
    "created_at": "2026-07-14T12:00:00.000Z",
    "updated_at": "2026-07-14T12:00:00.000Z"
  }
}

O `secret` (`whsec_...`) só aparece nesta resposta de criação — guarde-o agora, ele assina cada entrega (`X-Webhook-Signature-V2`, com o `X-Webhook-Timestamp`).

`active` expressa sua intenção manual; `health_status` começa como `unverified`. Execute `POST /api/v1/webhooks/{id}/test` e receba 2xx para verificar e ativar o endpoint.

`customer_id` é opcional: omitido ou `null`, o endpoint recebe eventos de todos os Clientes da Conta; informado, recebe apenas eventos daquele Cliente. O id precisa pertencer à Conta da chave.

`channel_account_ids` é opcional: omitido ou `null`, o endpoint recebe eventos de todos os canais da Conta; uma lista de 1 a 100 ids (os mesmos de `GET /api/v1/channel_accounts` e do `channel_account.id` de cada payload) limita o endpoint a esses canais. Com `customer_id`, os canais precisam ser desse Cliente. Lista vazia, mais de 100 itens ou item que não é UUID responde `422 invalid_channel_account_ids`; canal de outra Conta (ou de outro Cliente) responde `404 channel_account_not_found` e nenhum endpoint é criado.

A URL precisa usar https:// e resolver para um destino público (o BotoZap bloqueia loopback/redes privadas por segurança).

`events` aceita `messages`, `statuses`, `crm`, `account` e `app_messages`. `app_messages` (o que a equipe envia, edita ou apaga pelo app em coexistência: `whatsapp.message.echo`, `.edited`, `.revoked`) é opt-in: só chega se estiver na lista.

6. Envie pelo número do Cliente

Com mais de um número na Conta, todo envio precisa de from: o phone_number_id da Meta ou o UUID interno do número, ambos na listagem do passo 4. Sem ele, a API responde 422 ambiguous_phone.

Enviar por um número específico (`from`)

Contas com mais de um número conectado precisam informar `from` (o `phone_number_id` Meta ou o UUID interno) para desambiguar por qual número enviar.

curl https://botozap.com.br/api/v1/messages \
  -X POST \
  -H "X-API-Key: $BOTOZAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+5511988887777",
  "type": "template",
  "template": {
    "name": "pedido_confirmado",
    "language": {
      "code": "pt_BR"
    }
  },
  "from": "112233445566778"
}'

Resposta 201

{
  "id": "5b0a9d0e-6e1a-4f3b-8c2d-1a9f6e0b7c11",
  "wamid": "wamid.HBgNNTU5MTk5OTk5OTk5FQIAERgSM0FCQzFEMkUzRjRBNUI2QzdEAA==",
  "to": "5511988887777",
  "sent_to": "5511988887777",
  "status": "sent"
}

`from` é obrigatório quando a conta tem mais de um número conectado — sem ele a API responde 422 `ambiguous_phone`.

Use o `phone_number_id` Meta ou o UUID interno retornado por `GET /api/v1/phone_numbers`.

Próximos passos