Início rápido
Crie uma chave da equipe da Polymorfa, conecte um número com QuickLink, envie uma mensagem e registre um webhook assinado.
1. Crie sua conta e seu projeto#
Abra a Polymorfa, cadastre-se com OTP por e-mail, chave de acesso ou um provedor social habilitado e conclua a configuração da equipe e do projeto. Guarde o ID do projeto exibido no Console.
export POLYMORFA_BASE_URL="https://api.polymorfa.com"
export POLYMORFA_PROJECT_ID="replace-with-project-id"2. Crie uma chave da equipe#
Abra a equipe sem selecionar um projeto, depois abra Configurações → Chaves de API da equipe e escolha Criar chave da equipe. Conceda apenas os escopos de que a tarefa precisa. Este início rápido precisa de quicklink:manage, sessions:read, messages:write e webhooks:manage. Um token de projeto pode acessar recursos das APIs Messaging e Platform dentro do seu projeto quando os escopos dele permitem a ação.
export POLYMORFA_KEY="pmfa_REPLACE_ME"As chaves da equipe mantêm o prefixo pmfa_. O segredo é exibido uma única vez.
3. Conecte um número com QuickLink#
Crie um QuickLink persistente a partir do seu backend:
curl -X POST "$POLYMORFA_BASE_URL/messaging/quicklinks" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d "{\"projectId\":\"$POLYMORFA_PROJECT_ID\",\"settings\":{\"methods\":[\"qr\",\"pairing\"],\"businessName\":\"Acme\"}}"Envie a url retornada para a pessoa que está com o celular ou abra-a você mesmo. A página hospedada exibe o QR code ou o código de pareamento e confirma a conexão. Não grave a URL em logs; ela é a credencial deste pareamento.
export POLYMORFA_SESSION="quicklink-replace_me"Guarde o valor session da resposta do QuickLink. Ele é o valor de {session} nos caminhos com escopo de sessão. A obtenção direta do QR code e do código de pareamento não faz parte da API padrão para clientes; esses endpoints retornam 403. Consulte QuickLink para consultar o status, receber callbacks e cancelar.
4. Envie uma mensagem#
Defina conversation.phoneNumber como o número de telefone internacional do destinatário no formato E.164, incluindo o +. Coloque exatamente um tipo de mensagem dentro de content.
curl -X POST "$POLYMORFA_BASE_URL/messaging/$POLYMORFA_SESSION/messages/send" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": { "phoneNumber": "+5511999999999" },
"content": { "text": "Hello from Polymorfa" }
}'O schema da requisição também aceita mensagens de imagem, arquivo, voz, vídeo, enquete, localização, contato, produto, lista de produtos, pedido, lista de seleção única, botão de fluxo nativo, coleta de endereço e fluxo publicado. Consulte o método Send a message para ver os campos obrigatórios exatos de cada tipo. O envio de mensagens começa imediatamente e não altera a presença da sessão nem emite um indicador de digitação ou de gravação. Chame a operação de presença ou de digitação explicitamente quando a sua aplicação precisar desse comportamento.
Já tem código escrito para a Cloud API da Meta? A Graph API aceita o formato de requisição da Meta em /graph/whatsapp/v26.0 e responde no formato da Meta.
5. Registre um webhook assinado#
curl -X POST "$POLYMORFA_BASE_URL/api/webhooks" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/polymorfa/webhook",
"events": ["message.received", "message.ack", "session.status"],
"hmacKey": "replace-with-a-random-secret",
"format": "native"
}'Verifique o X-Webhook-Signature sobre o corpo bruto antes de processar a requisição. Para um consumidor compatível com a Meta, defina format como meta e verifique o X-Hub-Signature-256 em vez disso. Consulte Webhooks.