VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp Platform

Chave mestra e URL padrão das rotas

Mostra e altera a chave mestra usada por sistemas externos para se cadastrar e a URL de destino preenchida em rotas novas.

Além de o operador criar rotas à mão, sistemas externos podem se cadastrar sozinhos numa rota da plataforma, apresentando uma chave mestra compartilhada. Esta página cobre a configuração dessas rotas: a chave mestra e a URL de destino padrão. Exigem root_admin com o privilégio manage_whatsapp_platform.

A chave mestra é enviada pelo sistema externo no cabeçalho X-Api-Key do endereço público de auto-cadastro de rotas da plataforma (fora desta seção). Quem tem a chave consegue criar ou alterar a rota de qualquer telefone, então trate-a como um segredo de alta importância.

Ler a configuração

GET/api/v1/admin/whatsapp-platform/routes/configAdmin

Ler a chave mestra e a URL padrão

Devolve a chave mestra e a URL de destino padrão. Na primeira leitura, se ainda não existe chave mestra, ela é gerada e gravada: esta chamada GET tem efeito colateral na primeira vez. A chave volta em texto puro.

200Configuração lida
json
{
  "master_api_key": "5b0e...64 caracteres hexadecimais...c7a2",
  "default_webhook_url": "platform"
}

Campos da resposta

master_api_keystring
Chave mestra, 64 caracteres hexadecimais (32 bytes aleatórios).
default_webhook_urlstring
Destino usado quando uma rota é criada sem webhook_url. Se estiver vazio no banco, volta como platform.

Salvar a URL padrão

PUT/api/v1/admin/whatsapp-platform/routes/configAdmin

Alterar a URL de destino padrão das rotas

Grava a URL padrão (com os espaços das pontas removidos). A chave mestra não muda. A URL padrão só vale para rotas criadas depois; rotas existentes não são alteradas.

Corpo da requisição

default_webhook_urlstring
Destino padrão: platform ou uma URL. Vazio é aceito; nesse caso a leitura volta a mostrar platform.
200URL padrão salva
json
{ "success": true }

Gerar uma nova chave mestra

POST/api/v1/admin/whatsapp-platform/routes/master-key/regenerateAdmin

Emitir uma nova chave mestra

Gera uma chave nova, grava e devolve. A chave anterior deixa de funcionar imediatamente: todo sistema externo que a usava passa a receber 403 Invalid API key até ser atualizado. As api_key próprias de cada rota não são afetadas. Não tem corpo.

200Nova chave emitida
json
{ "master_api_key": "e83d...64 caracteres hexadecimais...19f0" }

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/whatsapp-platform/routes/config" \
  -H "Authorization: Bearer $TOKEN"

curl -X PUT "$BASE_URL/api/v1/admin/whatsapp-platform/routes/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_webhook_url": "platform"}'

curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/routes/master-key/regenerate" \
  -H "Authorization: Bearer $TOKEN"

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido (PUT){"error":"Invalid request body"}
401Sem cabeçalho Authorization{"error":"missing authorization header"}
403Sem ser root_admin com manage_whatsapp_platform{"error":"insufficient permissions"}
500Falha de banco ao ler ou gravar{"error":"..."}
Regenerar derruba os integradores

Não há período de transição entre a chave antiga e a nova. Combine a troca com quem usa o auto-cadastro antes de chamar a rota.

Atenção ao PUT com valor vazio

O PUT aceita default_webhook_url vazio, mas não é uma forma de "desligar" nada: na leitura e na criação de rotas o valor vazio é tratado como platform.

Veja também

  • Rotas de callback
  • Conectar um número
  • Visão geral do WhatsApp Platform
Anterior
Rotas de callback
Próxima
Flows globais
Nesta página
  • Ler a configuração
  • Salvar a URL padrão
  • Gerar uma nova chave mestra
  • Exemplo de requisição
  • Erros
  • Veja também