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

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.

Ver em Markdown

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.

Shell
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.

Shell
export POLYMORFA_KEY="pmfa_REPLACE_ME"

As chaves da equipe mantêm o prefixo pmfa_. O segredo é exibido uma única vez.

Crie um QuickLink persistente a partir do seu backend:

Shell
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.

Shell
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.

Shell
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#

Shell
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.