Código de pareamento
Pede ao WhatsApp um código de 8 caracteres que conecta phone à conexão quando é digitado nesse celular (WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone), em vez de escanear o QR code. O celular recebe um aviso. Escopo necessário: connections:write.
Parâmetros de caminho
idstring · uuidobrigatórioIdentificador da conexão (o número).
Corpo da requisição
phonestringobrigatórioO número a conectar, em formato internacional: código do país primeiro, depois o DDD e o número (por exemplo, 5511988887777). +, espaços, hífens e parênteses são ignorados; o número precisa ter de 8 a 15 dígitos.
Respostas
| Código | Erro e descrição |
|---|---|
| 200 | code: o código de 8 caracteres a digitar no celular (o WhatsApp mostra em dois grupos de 4, como K7QX-2M9P). phone: o número que ele conecta, em E.164. expiresAt: até quando ele pode ser digitado (unix em milissegundos). |
| 400 | phone não é um número em formato internacional com 8 a 15 dígitos (phone must be the number to link in international format…). |
| 400 | FST_ERR_VALIDATIONA requisição não segue o schema da operação (por exemplo, um id que não é um UUID); message diz o que está errado. |
| 401 | Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}. |
| 402 | subscription_inactiveA organização dona da conexão não pode usar o WhatsApp agora: o período de teste acabou, ou uma fatura venceu e passou do prazo de carência. Pague para voltar a usar. |
| 403 | A chave não tem o escopo connections:write; a mensagem de erro cita o escopo que falta. |
| 404 | A conexão não existe ou não é de quem chama: a de outra pessoa responde exatamente como uma que não existe (Connection not found). |
| 409 | already_pairedA conexão já está ligada a um número, ou um pareamento está terminando. Para conectar outro número, faça o logout antes (POST /connections/{id}/logout). |
| 409 | not_pairingA conexão não está pareando com um QR code na tela (a mensagem traz o status): conecte-a de novo, ou tente de novo em alguns segundos enquanto ela inicia. Com Retry-After quando os QR codes desta tentativa terminam cedo demais para o código ser digitado: peça de novo quando o próximo QR code aparecer. |
| 429 | pairing_code_too_soonUm código foi pedido para esta conexão há menos de 30 segundos, ou este número já recebeu 5 códigos na última hora. Espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 429 | Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After |
| 500 | O pedido do código ao WhatsApp falhou de forma inesperada (Failed to request a pairing code). Pode repetir, mas o aviso pode ter chegado ao celular: o intervalo de 30 segundos entre códigos continua valendo. |
| 501 | unsupported_by_providerO provedor da conexão não faz esta operação: o provedor dela não pareia por QR code, e o código de pareamento só existe nesse pareamento. |
| 503 | A instância do gateway que roda a conexão está mudando (um reinício, um failover) ou não responde: espere os segundos de Retry-After e tente de novo.Cabeçalho: Retry-After |
Detalhes
Só funciona enquanto a conexão está pareando com o QR code na tela (GET /connections/{id}/qr mostra um): crie a conexão, ou conecte-a de novo, antes.
O código vale até expiresAt, quando terminam os QR codes dessa tentativa (no máximo cerca de 2,5 minutos depois de eles aparecerem) e a conexão mostra QR codes novos: peça outro código então. Quando eles terminam cedo demais para o código ser digitado, a resposta é 409 not_pairing com Retry-After, que diz quando os próximos aparecem.
Cada código gera um aviso no celular, então uma conexão pode pedir um código a cada 30 segundos, e um número recebe no máximo 5 por hora, qualquer que seja a conexão que pede (429 pairing_code_too_soon com Retry-After).
Depois de digitado, o pareamento termina como o do QR code: status: open e o webhook connection.status com open. Um código de pareamento não evita a passkey: quando o WhatsApp pede uma passkey ao celular depois do código digitado, o pareamento trava exatamente como depois da leitura do QR code, e a conexão para como passkey_required.
Uma falha inesperada ao pedir o código ao WhatsApp responde 500 (Failed to request a pairing code); o aviso pode ter chegado ao celular, então o intervalo de 30 segundos continua valendo.
Guia: Parear um número