Pular para o conteúdo principal
Use um token de cliente de curta duração para fazer requisições a partir de um navegador ou de um app de celular. Cada token fica limitado a uma sessão e às ações que você permitir. Um token por Customer, por sua vez, cobre os números que um Customer possui.

​
Emitir

Chame POST /platform/client-tokens com uma chave de projeto ou da equipe que tenha todas estas permissões: sessions:manage, messages:write, contacts:read, presence:read, presence:observe e mcp. Atualizar as regras da sessão exige as mesmas permissões. Tokens emitidos com tetos de ação carregam um teto de ação imutável. Cada requisição faz a interseção desse teto com as regras da sessão em vigor e com a propriedade atual do número. Edições de regras não podem conceder ações fora do teto. Uma chave da equipe ou um token de projeto pertencente a uma pessoa só pode emitir tokens enquanto essa pessoa continuar como proprietária ou administradora da equipe e não estiver banida. Credenciais de conta de serviço não podem emitir tokens que permitam ações de mensagens. O emissor precisa continuar ativo e não revogado, com os escopos exigidos e a propriedade atual do número ou do Customer selecionado. Essas verificações valem para toda emissão, incluindo renovações de token. Uma recusa por causa do emissor ou da propriedade atual retorna 403 sem token. Se a Polymorfa não conseguir concluir as verificações de emissão, ela retorna 503 sem token.
A resposta contém o token e a validade dele:
ttlSeconds precisa estar dentro dos limites documentados para o endpoint. O token fica restrito à equipe, à sessão, ao ID efêmero e à validade dele. O allow de sessão exige inscrição no beta de tetos de ação. Até esse beta ser ativado, requisições de sessão com allow são recusadas, e omitir o campo mantém o formato de token baseado em regras que já existe. Tetos selados existentes continuam sendo aplicados se a emissão de novos tetos for desativada. allow também aceita um teto explícito para um token de sessão, incluindo as ações mcp e voip_*. Um allow de sessão vazio não concede nenhuma ação da API. O allow de Customer precisa conter pelo menos uma ação. Defina as regras antes de emitir. Um token sem ações permitidas precisa ser emitido de novo depois que você configurar as regras dele. Os nomes de ação chats_read, chats_manage, contact_write e contact_delete são reservados para o acesso ao beta regional de equipes inscritas. Incluir uma ação reservada não ativa Contatos ou Conversas regionais. Tetos regionais também exigem o escopo de emissor correspondente: chats:read, chats:manage ou contacts:manage. Essas permissões não autorizam rotas legadas de conversas do WhatsApp. read_contact continua cobrindo as consultas de contato documentadas; ela não concede acesso irrestrito a um diretório de contatos retido. Tokens existentes não podem ganhar essas ações reservadas por meio de uma edição de regra.

​
Regras da sessão

As regras são gerenciadas separadamente:
PUT substitui o conjunto inteiro de regras. Campos opcionais omitidos voltam aos valores padrão. As regras continuam valendo até que você as substitua ou exclua, e excluir uma sessão também exclui as regras dela. recipientMode é conversation, any ou none. Modos desconhecidos falham de forma fechada (fail closed). allowedActions é uma lista separada por vírgulas que contém apenas estes valores:

​
Janela de conversa

No modo conversation, um token de cliente só pode enviar para um contato que tenha mandado mensagem para a sessão dentro da janela de conversa. A janela recomeça a cada nova mensagem desse contato. conversationTtlSeconds define a janela, em segundos: Valores fora desse intervalo retornam 400. Não existe janela sem expiração: um contato que não manda mensagem para a sessão há mais de 7 dias precisa mandar uma nova mensagem antes que um token de cliente possa responder. As ações voip_* permitem chamadas. Três campos opcionais da regra limitam as chamadas: maxSetupsPerMinute (inícios de chamada por minuto para cada ephemeralId; 0 usa o padrão de 10), allowedNumber (uma lista separada por vírgulas de números E.164 que o token pode chamar ou convidar) e maxConcurrency (chamadas simultâneas; 0 significa sem limite). Consulte Chamadas. Tokens de cliente nunca pareiam números. Use um QuickLink para conectar um número a partir de um navegador ou de um celular. A ação mcp permite o handshake do protocolo. Cada ferramenta MCP continua passando pelas regras normais de sessão, destinatário, ação, origem e taxa.

​
Tokens por Customer

Os tokens por Customer estão em beta. Quando o beta for oferecido à sua equipe, um proprietário ou administrador da equipe seleciona Participar na linha do beta, na página Números de um projeto, e aceita os termos. Até a equipe participar, emitir com customer retorna 403.
Quando um Customer possui vários números, emita um único token para o Customer em vez de um por sessão. Passe o ID do Customer na Polymorfa em customer em vez de session:
  • Envie exatamente um entre session e customer.
  • customer é o ID do Customer na Polymorfa. Primeiro, procure o Customer pelo seu próprio ID externo no seu servidor; os tokens nunca aceitam um ID externo.
  • A chave emissora também precisa de customers:read. Um token de projeto só pode emitir para Customers do próprio projeto. Uma chave da equipe pode emitir para qualquer Customer da equipe. Um Customer fora da equipe ou do projeto da chave retorna 404.
  • O Customer precisa estar ativo e possuir pelo menos um número, e o projeto precisa estar com Customers ativado. Um token cobre no máximo 64 números; emitir para um Customer com mais números retorna 400.
O token cobre os números que o Customer possui no momento da emissão. Cada requisição também é verificada em relação aos números atuais do Customer: Chame as rotas de sessão normais com o ID de sessão do número no caminho, por exemplo POST /messaging/{session}/messages/send. Cada requisição também precisa passar pelas regras dessa sessão: um token por Customer nunca permite mais do que as regras da sessão permitem. allow restringe o token ainda mais. Ele aceita send_message, send_reaction, send_typing, send_seen, read_presence, subscribe_presence e read_contact. Para um Customer, omita o campo para usar esse conjunto de ações original. Para uma sessão, a omissão registra as ações configuradas no momento da emissão; sem regras, o token sai sem ações. Um token por Customer não pode usar chamadas (voip_*) nem MCP; emita um token de sessão para isso.

​
Comportamento de segurança

  • Tokens de cliente não podem emitir outros tokens, incluindo tokens por Customer.
  • Regras, estado de destinatário/conversa, restrições de origem e limites de taxa são verificados depois que o token é autenticado.
  • Exclua ou desative as regras da sessão para interromper os efeitos permitidos antes que todos os tokens emitidos expirem.
  • Cada alteração de regra aparece nos Logs de auditoria como clientToken.rulesCreated, clientToken.rulesUpdated ou clientToken.rulesDeleted. O registro informa quais campos mudaram, o modo de destinatário, os limites e a janela de conversa. Ele registra quantas origens e quantos números são permitidos, não as origens nem os números em si.
  • Se um PUT ou DELETE retornar 503 com o código service_unavailable, a Polymorfa armazenou a alteração, mas não conseguiu confirmar que os tokens de cliente já a usam. Repita a mesma requisição depois do intervalo indicado em Retry-After.

​
Indisponibilidade temporária

Os tokens de cliente falham de forma fechada. Se a Polymorfa não conseguir verificar as regras de uma requisição, a requisição é recusada em vez de ser permitida sem verificação:
  • 503 com o código credential_verification_unavailable quando as regras da sessão não podem ser carregadas. O token continua válido; tente a requisição novamente.
  • 503 com o código service_unavailable e um cabeçalho Retry-After quando um rateLimit por minuto ou a janela conversation não pode ser verificado. Tente novamente depois do número de segundos indicado.
Consulte Emitir um token de cliente e Regras da sessão na referência da Platform API.