Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Tokens de cliente

Emita credenciais pmfa_ct_ de curta duração e aplique regras de sessão, destinatário, ação, origem e taxa.

Ver em Markdown

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.

Os tokens de cliente funcionam apenas com a Messaging API. A Graph API os recusa; chame-a do seu servidor com uma chave da equipe ou um token de projeto.

Emitir#

Chame API Mint client token 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.

JSON
{
  "session": "739182640518203",
  "ephemeralId": "user_42",
  "ttlSeconds": 900
}
TypeScript
const minted = await messaging.clientTokens.mint({
  session: "<number-id>",
  ephemeralId: "user_42",
  ttlSeconds: 900,
});

// Return the token to your signed-in browser client. Do not log it.
const browserResponse = Response.json(
  { token: minted.data.data.token, expiresAt: minted.data.data.expiresAt },
  { headers: { "Cache-Control": "no-store" } },
);

Emita o token no seu servidor e envie ao navegador apenas o token. A resposta contém o token e a validade dele:

JSON
{
  "success": true,
  "data": {
    "token": "pmfa_ct_…",
    "expiresAt": "2030-01-01T00:15:00.000Z"
  }
}

TypeScript:

Leia e altere as regras da sessão com clientTokens.retrieveRules e clientTokens.updateRules.

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:

HTTP
GET    /platform/sessions/{session}/client-rules
PUT    /platform/sessions/{session}/client-rules
DELETE /platform/sessions/{session}/client-rules
JSON
{
  "recipientMode": "conversation",
  "allowedActions": "send_message,send_seen,send_typing",
  "rateLimit": 30,
  "maxDaily": 500,
  "allowedOrigins": "https://app.example.com",
  "conversationTtlSeconds": 86400,
  "enabled": true
}

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:

Text
mcp                     send_message            send_reaction
send_typing             send_seen               read_presence
subscribe_presence      read_contact            voip_place
voip_answer             voip_signal

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:

ValorJanela
86400 (padrão)24 horas
300 (mínimo)5 minutos
604800 (máximo)7 dias

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. allowedNumber restringe os números que um token de cliente pode chamar ou convidar (uma lista separada por vírgulas de números E.164). Tokens de cliente têm os mesmos limites de chamada que as suas chaves de API; consulte Limites de acesso. maxSetupsPerMinute e maxConcurrency estão obsoletos e não têm efeito.

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#

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:

JSON
{
  "customer": "0190f0b6-7c1e-7a55-9d1a-2f0c6b1e4a10",
  "ephemeralId": "user_42",
  "allow": ["send_message", "read_presence"],
  "ttlSeconds": 900
}
  • 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:

Depois da emissãoEfeito no token
Um número passa para outro CustomerRequisições para esse número retornam 403 imediatamente.
Um número passa para este CustomerNão é coberto. Emita um novo token para incluí-lo.
O Customer é arquivado, ou Customers é desativado no projetoTodas as requisições retornam 403.
A equipe sai do betaTodas as requisições retornam 403.

Chame as rotas de sessão normais com o ID de sessão do número no caminho, por exemplo API Send message. 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.