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

Conceitos

Como equipes, projetos, sessões, credenciais, mensagens, webhooks e o Sandbox se relacionam.

Ver em Markdown

A Polymorfa mantém a administração da conta separada do acesso às mensagens. Comece pela hierarquia de equipes e projetos e depois escolha a credencial que corresponde à operação que você precisa fazer.

Equipes e projetos#

A equipe é dona dos membros, da cobrança, das chaves da equipe, dos projetos e do histórico de auditoria da equipe. As funções de membro disponíveis são Proprietário, Administrador e Membro.

Um projeto agrupa recursos de mensagens, como sessões, tokens de projeto, webhooks, modelos, campanhas e configurações de integração. Os tokens de projeto ficam vinculados a um único projeto, por isso não autorizam o acesso aos recursos de outro projeto.

Sessões#

Uma sessão representa um número conectado. Cada sessão tem um identificador estável, usado em caminhos da Messaging API como API Send message.

Os tipos públicos da Messaging API usam três estados de conexão:

StatusSignificado
CONNECTINGA conexão está sendo estabelecida.
CONNECTEDA sessão está pronta para as operações de mensagens compatíveis.
DISCONNECTEDA sessão não está conectada. Pareie, inicie ou inspecione a sessão antes de enviar.

Números novos recebem IDs opacos em formato de string decimal, qualquer que seja a forma como foram criados. Mantenha os IDs como strings; não os converta em números de JavaScript. Use testMode para identificar números de teste. Os números de teste são criados em um projeto de desenvolvimento e não iniciam uma conexão real com o WhatsApp.

Credenciais#

CredencialPrefixo ou formatoUso
Chave da equipepmfa_…Acesso de servidor confiável aos recursos autorizados para uma equipe.
Token de projetopmfa_pt_…Acesso de servidor confiável restrito a um projeto e a um conjunto explícito de escopos.
Token de clientepmfa_ct_…Acesso de curta duração para navegador ou app móvel, restrito por sessão e por regras do cliente.
Bearer do dashboardJWTRequisições do Console e da conta feitas por quem está conectado.

As operações públicas da Platform API em /platform/* aceitam uma chave da equipe ou um bearer do dashboard verificado. Elas recusam tokens de projeto. As operações da Messaging API, do MCP e de bridge aceitam apenas os tipos de credencial indicados na referência gerada de cada uma.

Toda credencial de serviço é um segredo do tipo bearer. Mantenha chaves da equipe e tokens de projeto em servidores confiáveis, solicite apenas os escopos necessários e revogue uma credencial quando ela puder ter sido exposta. Consulte Autenticação para ver os nomes de escopo atuais e as regras de público de cada API.

Mensagens e webhooks#

Os endpoints de mensagens usam corpos de requisição e de resposta tipados para texto, mídia, localização, contato, enquete, reação e outras operações compatíveis. Use a referência gerada da Messaging API para ver os campos e os formatos exatos.

Os webhooks entregam eventos no seu endpoint HTTPS. As entregas nativas usam X-Webhook-Signature; as entregas compatíveis com a Meta usam X-Hub-Signature-256. Verifique a assinatura com o corpo bruto da requisição antes de interpretá-lo. O guia de webhooks lista os nomes de evento, os formatos e as configurações de novas tentativas atuais.

Versionamento#

As requisições da Messaging API podem fixar a versão de data atual:

HTTP
Polymorfa-Version: 2026-09-22

Os caminhos compatíveis com a Meta usam a própria versão vNN.0. Consulte Versionamento para ver os padrões atuais e os cabeçalhos de resposta. A referência da API cobre as três APIs: escolha a API da Polymorfa ou a Graph API no seletor da barra lateral.

Sandbox#

O Sandbox oferece fluxos de trabalho com números de teste para projetos de desenvolvimento. Os números de teste gratuitos têm limite de 5 mensagens por segundo, 1 GB de armazenamento incluído, 5 chamadas recebidas e 5 chamadas feitas por mês e 1.000 execuções serverless por mês. Eles não incluem campanhas. As operações de pool, claim, dispositivo e mensagem do Sandbox têm rotas documentadas próprias; não presuma que toda operação de produção tem um equivalente simulado.

Próximos passos#