Pular para o conteúdo principal

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

​
POST /v1/numbers/remote-pairing

Mesmo corpo de POST /v1/numbers, mais opções específicas de pareamento: 
curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
    "name": "Customer João",
    "number": "+5511999999999",
    "linkToApiKey": true,
    "sendViaWhatsApp": false
  }'
Resposta 201: 
{
  "instance": { "id": "wa_abc", "instanceName": "PS-tenant-xxx", "number": "5511999999999", "name": "Customer João", "state": "CLOSE" },
  "remotePairingUrl": "https://pilotstatus.com/connect/abc123-def456-...",
  "maskedNumber": "+551199****9999",
  "messageSent": false
}
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 enviar ao cliente final.
  • Quando o cliente final abre a URL e conecta, o webhook number.connected dispara normalmente.

​
Envio automático via WhatsApp

Com sendViaWhatsApp: true, o Pilot Status tenta enviar uma mensagem de template para o número de destino contendo o link de pareamento. Requer um template chamado pilot_status_remote_pairing (categoria OTP) criado no painel. Se o envio falhar, a instância e a URL ainda são criadas, mas messageSent retorna false com um messageError. 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.
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.

​
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:
MétodoEndpointRetorna
GET/v1/remote-pairing/{token}{ valid, name, maskedNumber, state, branding }
POST/v1/remote-pairing/{token}/connect{ qrcodeBase64, pairingCode }
GET/v1/remote-pairing/{token}/status{ state, isFullyConnected }
GET/v1/connect/{token}/branding{ branding } (também usado pelo fluxo Meta Embedded Signup)
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.