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

Links de pareamento de clientes

Permita que um cliente conecte um número sem dar acesso ao Console.

Ver em Markdown

Um link de pareamento de cliente permite que a pessoa que está com o celular conecte um número de WhatsApp ao registro dela em Clientes. O destinatário não precisa de conta na Polymorfa nem de acesso ao Console.

Console

  1. Abra Clientes e escolha o cliente.
  2. Abra a aba Links de pareamento e selecione Gerar link.
  3. Se quiser, informe o telefone esperado.
  4. Selecione Criar link e depois copie a URL.

O Console mostra a URL completa apenas depois da criação, então copie o link antes de fechar a janela.

API

Chame Create a customer pairing link com um Idempotency-Key e uma chave que tenha customers:manage. A URL é retornada apenas na primeira resposta. Uma repetição com a mesma chave de idempotência retorna url: null.

cURL
curl -X POST "https://api.polymorfa.com/platform/customers/$CUSTOMER_ID/pairing-links" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: pairing-crm_456-1" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "00000000-0000-4000-8000-000000000001",
    "expectedPhone": "+15551234567",
    "methods": ["qr", "phone"]
  }'
TypeScript
const link = await platform.customers.createPairingLink(
  customerId,
  { projectId: "<project-id>", expectedPhone: "+15551234567", methods: ["qr", "phone"] },
  { idempotencyKey: "pairing-crm_456-1" },
);

// Your application sends the URL over its own private channel; this is not an SDK method. Do not log it.
await sendToCustomer(customerId, link.data.data.url);

TypeScript:

Liste os links com listPairingLinks(customerId, projectId) e retire um com revokePairingLink(customerId, pairingLinkId, projectId).

O tempo de vida padrão do link é de 24 horas. As listas de links de pareamento mostram o status e os metadados, mas nunca exibem a URL de novo.

Quando o destinatário abre o link, a Polymorfa emite um QuickLink hospedado separado e envia o destinatário para ele. O QuickLink continua ativo até a conexão terminar ou até ser cancelado. O link do cliente nunca contém a credencial do QuickLink.

Fluxo do destinatário#

O destinatário chega à página hospedada, escaneia um código QR ou digita um código de pareamento no celular e confirma a conexão. A Polymorfa verifica o número conectado antes de atribuí-lo ao cliente. O link passa por estes estados:

EstadoSignificado
GeradoO link pode iniciar uma tentativa de conexão.
AbertoUm destinatário trocou o link durável e a Polymorfa reservou uma tentativa.
ConectandoUma sessão de QuickLink está ativa.
ConectadoO número verificado foi atribuído ao cliente. O link não pode ser reutilizado.
FalhouA tentativa falhou. O mesmo link durável pode iniciar outra tentativa, a menos que tenha atingido um limite de segurança.
ExpiradoO link passou do horário de expiração.
RevogadoUm membro do projeto encerrou o link.

Um link conectado, expirado ou revogado não pode iniciar outra sessão. Gere um novo link.

Informe um telefone esperado quando apenas uma identidade do WhatsApp for aceitável. O valor pertence a este convite e nunca é deduzido do perfil de um cliente. Ele precisa ser um número internacional válido. A Polymorfa verifica o número realmente conectado antes de atribuí-lo ao cliente.

Quando você cria o link, a Polymorfa verifica expectedPhone com um dos seus Números conectados. Um número confirmado como fora do WhatsApp falha com 400 phone_not_registered. Quando nenhum Número conectado consegue verificá-lo, o link é criado mesmo assim.

Se os números não corresponderem, a Polymorfa rejeita a conexão e solicita a limpeza do número pendente. Confira se a limpeza terminou antes de o destinatário tentar novamente com o mesmo link durável. Três divergências de telefone revogam o link. Gere um novo link com o número correto ou deixe de lado a restrição quando qualquer número verificado for aceitável.

Selecione Revogar ao lado de um link com status Gerado, Aberto, Conectando ou Falhou quando ele foi enviado para a pessoa errada ou não for mais necessário. A revogação impede outra troca da URL durável.

Os erros vistos pelo destinatário têm estas ações de recuperação:

  • This link is unavailable (em português, Este link está indisponível): peça um novo link. O original expirou, foi revogado, conectou um número ou não existe.
  • This link reached its limit: peça um novo link depois de tentativas repetidas.
  • Pairing is temporarily unavailable (em português, O pareamento está temporariamente indisponível): aguarde um pouco e abra o mesmo link de novo.
  • The connected phone does not match (o telefone conectado não corresponde): tente novamente com o telefone esperado. Depois de três divergências, peça um novo link.

Trate um link de pareamento como um convite. Envie o link apenas ao destinatário pretendido e revogue-o se ele for exposto.

Configurações salvas no convite#

Criar um convite de cliente salva as configurações de QuickLink do projeto e o perfil resolvido do telefone esperado. Alterações de aparência, política de histórico, preferência de conexão, links legais ou URLs de retorno valem para novos convites. Abrir um convite existente usa as configurações originais dele e não repete a consulta original do telefone. Os métodos de pareamento são a única política que a criação pode substituir; quando omitidos, eles vêm das configurações salvas do projeto.

Um convite indisponível precisa ser substituído. O endpoint de troca retorna 410 sem criar uma sessão quando o convite não pode ser usado.

Uma nova tentativa depois que a confirmação já vinculou o número retoma a conclusão para esse mesmo número. Ela não vincula outra sessão nem duplica eventos do cliente. Falhas definitivas da Meta Cloud API atualizam o convite do cliente e geram o evento de falha dele antes de o destinatário ser enviado à URL de retorno de falha.