Criar, conectar e excluir números

Crie um número de WhatsApp via API pública, conecte-o (QR code ou código de pareamento) e exclua-o quando não for mais necessário.

Use uma chave de API com escopo de tenant (recomendada para plataformas SaaS que gerenciam múltiplos números). Uma chave com escopo de número também funciona — ela continua presa ao número que já cobre. Autentique com x-api-key: ps_....

POST /v1/numbers — Criar um número

curl -X POST "https://pilotstatus.com.br/v1/numbers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "My WhatsApp",
    "number": "+5511999999999"
  }'

string

obrigatório

Nome de exibição do número.

string

obrigatório

O número de telefone no formato E.164 (ex.: +5511999999999).

boolean

obsoleto

Aposentado — aceito, mas não faz nada. Enviá-lo não é erro, e nenhuma chave de API é alterada: linkedApiKeyId na resposta é sempre null. Ele reapontava uma chave com escopo de número para o número que você acabara de criar, tirando-a silenciosamente do número ao qual estava presa.

A resposta inclui qrcodeBase64 e pairingCode (código de pareamento por letras do WhatsApp; pode ser null se o provedor não retornar um). Mostre o QR code para a pessoa dona do telefone, ou deixe-a digitar o código de pareamento.

Chame estes endpoints apenas a partir do seu backend — nunca exponha sua chave ps_ no navegador.

Números Meta (API oficial da Cloud)

POST /v1/numbers cria um número não oficial (pareado por QR). Para números oficiais da Meta Cloud API, use um dos fluxos Meta em vez disso:

POST /v1/numbers/meta — BYO-WABA direto: traga suas próprias credenciais de WABA, ou
Meta Embedded Signup hospedado via um link de pareamento remoto com metaFlow.

POST /v1/numbers/meta — traga sua própria WABA

Provisiona um número oficial da Meta Cloud API a partir de credenciais de WABA que você já possui. Este fluxo é para plataformas que já controlam a WABA e têm um token de system user. Se você não tem essas credenciais, use o Embedded Signup hospedado via um link de pareamento remoto com provider=META. Exige uma chave de API com escopo de tenant.

curl -X POST "https://pilotstatus.com.br/v1/numbers/meta" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "My Official Number",
    "number": "+5511999999999",
    "metaPhoneId": "123456789012345",
    "metaWabaId": "987654321098765",
    "metaAccessToken": "EAAG...",
    "metaAppSecret": "your_meta_app_secret",
    "metaAppId": "112233445566778"
  }'

string

obrigatório

Nome de exibição do número (1–60 caracteres).

string

obrigatório

O número de telefone em dígitos, com + inicial opcional.

string

obrigatório

O phone number ID da Meta do telefone da WABA.

string

obrigatório

O ID da WhatsApp Business Account (WABA).

string

obrigatório

Um token de acesso de system user com acesso à WABA.

string

obrigatório

O app secret do seu app Meta.

string

obrigatório

O ID do seu app Meta.

boolean

padrão:"false"

Quando true, a Pilot Status inscreve sua WABA no próprio callback de webhook dela (definindo o override_callback_uri da Meta mais um verify token por número), de modo que as mensagens recebidas cheguem à Pilot automaticamente — você nunca cola uma URL de webhook no seu Meta App Dashboard. A resposta então retorna webhook.routedToPilot: true.Padrão false. O override é um valor único por WABA, então habilitá-lo redireciona todos os números daquela WABA para longe do callback que seu app usa atualmente (por exemplo, seu próprio backend ou um Chatwoot existente). Só ative quando quiser que a Pilot Status seja a dona da entrega de webhooks dessa WABA.

boolean

obsoleto

Aposentado — aceito, mas não faz nada, exatamente como no POST /v1/numbers acima. linkedApiKeyId na resposta é sempre null.

Erros:

400 — erro de validação (campos do corpo ausentes ou inválidos).
402 PLAN_NUMBER_LIMIT_REACHED — a cota de números do seu plano está cheia e você nunca comprou um número extra. Adicionar créditos não resolve: libere um slot ou suba de plano.
402 INSUFFICIENT_FUNDS — o número seria um extra pago e não há saldo na carteira nem cartão salvo.
403 NUMBERS_GRANT_NOT_ALLOWED — grants OAuth por número não podem provisionar números.
409 — “Number already exists” (o número já existe).

Erros de capacidade e como resolver

As duas rotas de provisionamento desta página (POST /v1/numbers e POST /v1/numbers/meta) checam capacidade antes de gravar a linha do número, e as duas recusam com 402. O status sozinho não diz o que fazer — o campo error diz. Nestas duas rotas o discriminador vem só em error; o POST /v1/numbers/remote-pairing manda os mesmos valores em error e em code.

`error`	O que significa	O que resolve
`PLAN_NUMBER_LIMIT_REACHED`	O teto é a cota do próprio plano, e nenhum número extra foi comprado ou concedido.	Libere um slot (`DELETE /v1/numbers/{id}`) ou suba de plano. Dinheiro não resolve este.
`INSUFFICIENT_FUNDS`	O próximo número é um extra pago — um plano que cobra por número, ou uma conta que já comprou extras — e não dá para custeá-lo.	Adicione créditos ou salve um cartão, e tente de novo.

O corpo traz os números por trás da recusa, para você não ter de adivinhar:

{
  "error": "PLAN_NUMBER_LIMIT_REACHED",
  "plan": "FREE",
  "maxNumbers": 1,
  "currentNumberCount": 1,
  "extras": 1,
  "proratedTotal": 14.95,
  "walletBalance": 0,
  "currency": "BRL"
}

Mudou. Um plano cuja cota estava simplesmente cheia também respondia INSUFFICIENT_FUNDS — então uma conta com um número num plano de um número era informada de que estava sem dinheiro, e ia atrás de um saldo que nunca foi o problema. O status não mudou (402); o que é novo é o valor em error, e os campos que vêm junto.

Entrega de webhook (mensagens recebidas)

O envio funciona assim que o número é criado — não depende do webhook. Para a Pilot Status também receber mensagens, a Meta precisa entregar os webhooks dessa WABA para a Pilot. A resposta traz um objeto webhook justamente para isso:

{
  "webhook": {
    "url": "https://webhook.pilotstatus.com.br/api/meta/webhook",
    "verifyToken": "…",
    "routedToPilot": false
  }
}

Duas formas de conectar:

Automática — passe routeWebhooksToPilot: true na requisição. A Pilot inscreve a WABA para você e a resposta retorna webhook.routedToPilot: true; nada mais a configurar.
Manual — no seu Meta App Dashboard, defina a Callback URL do produto WhatsApp como webhook.url e o Verify token como webhook.verifyToken.

A página de conexão hospedada metaFlow: "credentials" (veja pareamento remoto) expõe a mesma escolha como um checkbox.

GET /v1/numbers//connect — Regenerar o QR code

Gera um novo QR code e código de pareamento quando a instância não está OPEN.

curl "https://pilotstatus.com.br/v1/numbers/wa_abc/connect" \
  -H "x-api-key: ps_your_token_here"

A resposta inclui qrcodeBase64 e pairingCode novos.
Se o número já estiver conectado (OPEN), o endpoint retorna 409 — não há nada para parear.
Não se aplica a números Meta (eles não usam pareamento por QR).
Reflete o mesmo estado de conexão que a página de Números no painel.

DELETE /v1/numbers/ — Remover um número

curl -X DELETE "https://pilotstatus.com.br/v1/numbers/wa_abc" \
  -H "x-api-key: ps_your_token_here"

Remove o registro da Pilot Status e tenta encerrar ou remover a sessão de WhatsApp associada quando aplicável (HTTP 404 das etapas de limpeza é ignorado).

Webhooks relacionados

number.created — dispara quando a instância é criada.
number.connected — dispara quando o cliente completa a conexão via QR / pareamento (estado OPEN).
number.removed — dispara na exclusão.

Consulte a referência de eventos de webhook.

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

POST /v1/numbers — Criar um Número

Criar, conectar e excluir números

POST /v1/numbers — Criar um número

Números Meta (API oficial da Cloud)

POST /v1/numbers/meta — traga sua própria WABA

Erros de capacidade e como resolver

Entrega de webhook (mensagens recebidas)

GET /v1/numbers//connect — Regenerar o QR code

DELETE /v1/numbers/ — Remover um número

Webhooks relacionados

​Criar, conectar e excluir números

​POST /v1/numbers — Criar um número

​Números Meta (API oficial da Cloud)

​POST /v1/numbers/meta — traga sua própria WABA

​Erros de capacidade e como resolver

​Entrega de webhook (mensagens recebidas)

​GET /v1/numbers//connect — Regenerar o QR code

​DELETE /v1/numbers/ — Remover um número

​Webhooks relacionados

Criar, conectar e excluir números

POST /v1/numbers — Criar um número

Números Meta (API oficial da Cloud)

POST /v1/numbers/meta — traga sua própria WABA

Erros de capacidade e como resolver

Entrega de webhook (mensagens recebidas)

GET /v1/numbers//connect — Regenerar o QR code

DELETE /v1/numbers/ — Remover um número

Webhooks relacionados