Skip to main content

​
Pareamento remoto — link de pareamento hospedado

Para plataformas SaaS que gerenciam números para clientes finais, o Pareamento Remoto permite gerar um link de pareamento em vez de exibir o QR code você mesmo. Seu cliente abre o link, escaneia o QR (ou executa o Meta Embedded Signup), e o número conecta à sua conta.
Modal Pairing Link com o link de conexão hospedado

Uma sessão de pareamento remoto — envie o link hospedado ao seu cliente; quando ele escanear o QR, o webhook number.connected dispara.

​
POST /v1/numbers/remote-pairing

Mesmo corpo de POST /v1/numbers, mais opções específicas de pareamento:
Resposta 201:
Diferenças em relação a POST /v1/numbers:
  • A instância é criada no estado CLOSE (desconectada) — nenhum QR code é retornado.
  • remotePairingUrl é o link público para o cliente final. O endpoint apenas devolve o link — a entrega ao cliente é sua (sua própria interface, e-mail, chat, onde ele estiver).
  • Quando o cliente final abre a URL e conecta, o webhook number.connected dispara normalmente.

​
linkToApiKey — aposentado

Aceito, mas não faz nada. Enviá-lo não é erro, e nenhuma chave de API é alterada: linkedApiKeyId na resposta é sempre null. Ele reapontava uma chave com escopo de número para o número recém-pareado, tirando-a silenciosamente do número ao qual estava presa.

​
warnings no 201

Um pareamento bem-sucedido pode voltar com um array warnings de strings. Ele só aparece quando há algo a relatar. Para provider=PILOT_STATUS, externalRef e redirectUrl são aceitos mas não podem ser honrados: eles viajam na sessão assinada da Meta, e o link de pareamento por QR não carrega sessão nenhuma. Cada um deles é relatado em warnings — e o pareamento continua dando certo. Não é um 400:
Antes eles eram descartados em silêncio. Se você precisa de algum dos dois, use provider=META — é o ramo Meta que os leva adiante na sessão assinada. O corpo também aceita um objeto opcional branding para sobrescrever o logo/cores/título da página de conexão para apenas este link (registrado no token). Ele sobrepõe a marca salva do tenant. Veja Marca da página de conexão.

​
Números Meta: metaFlow

Para números da API oficial Meta Cloud o link de pareamento pode executar fluxos Meta em vez do pareamento por QR:
  • metaFlow: "embedded" — a página hospedada executa o Meta Embedded Signup para que seu cliente conecte a própria WABA sem sair do link.
  • metaFlow: "credentials" — a página hospedada coleta as credenciais da WABA existente do cliente. Ela também exibe um checkbox rotear webhooks recebidos para a Pilot Status (ligado por padrão) que inscreve automaticamente a WABA do cliente no callback da Pilot, dispensando qualquer configuração manual de webhook — veja entrega de webhook.
O pareamento remoto com metaFlow é a opção hospedada. Se você já possui as credenciais da WABA no servidor, use POST /v1/numbers/meta (BYO-WABA direto) em vez disso — sem link e sem interação do cliente final.

​
Erros

Os dois 402 trazem as figuras por trás da recusa — plan, maxNumbers, currentNumberCount, extras, proratedTotal, walletBalance e currency — ao lado de error e code. Ramifique pelo código: os dois compartilham o status, mas não a solução. Veja erros de capacidade.
Corrigido: INSUFFICIENT_FUNDS nesta rota agora responde 402, o mesmo status do POST /v1/numbers. Antes vinha como 500.
Mudou. Um plano com a cota simplesmente cheia também respondia INSUFFICIENT_FUNDS aqui, e o corpo não trazia nada além do código repetido nos dois campos. Agora responde PLAN_NUMBER_LIMIT_REACHED, com as figuras de capacidade junto.

​
Endpoints públicos por token (sem autenticação)

A página de pareamento usa estes endpoints baseados em token — você também pode chamá-los para construir sua própria UI de conexão: Observações:
  • O token expira após 24 horas ou mediante conexão bem-sucedida (uso único).
  • POST .../connect só funciona quando o estado não é OPEN.
  • O mesmo estado de conexão exibido no painel e nos webhooks (number.created, number.connected) se aplica.