Pular para o conteúdo

Código de pareamento

POST/connections/{id}/pairing-code

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.

Ver em Markdown

Parâmetros de caminho

idstring · uuidobrigatório

Identificador da conexão (o número).

Corpo da requisição

phonestringobrigatório

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

de 8 a 32 caracteres

Respostas

Respostas: código de status, erro e descrição
CódigoErro e descrição
200code: 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).
400phone não é um número em formato internacional com 8 a 15 dígitos (phone must be the number to link in international format…).
400FST_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.
401Sem chave de API, ou com uma chave desconhecida, revogada ou expirada. O corpo é {"error": "Unauthorized"}.
402subscription_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.
403A chave não tem o escopo connections:write; a mensagem de erro cita o escopo que falta.
404A 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).
409already_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).
409not_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.
429pairing_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
429Requisições demais deste IP de origem, ou autenticações com falha demais: espere os segundos de Retry-After.Cabeçalho: Retry-After
500O 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.
501unsupported_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.
503A 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

Esta página ajudou? · Atualizado em 28 set 2026