Pular para o conteúdo

connection.status

POSTpara o webhookBaseUrl do projeto

A conexão abriu, fechou ou foi restringida.

Ver em Markdown

O socket da conexão abriu ou fechou, ou o WhatsApp mudou o que a conta pode fazer. Uma abertura traz status: open e o número pareado em phoneNumber, sem reason. Um fechamento traz o motivo em reason e, em willReconnect, se a apiwpp reconecta sozinha: com true ela continua tentando, com espera crescente, e o próximo status: open diz que deu certo; com false ela parou e espera alguém, com um QR code novo ou uma reconexão explícita.

Como toda entrega de webhook é feita pelo menos uma vez, aplique-o de forma idempotente: use o timestamp do envelope para ignorar um status mais antigo que o último que você guardou.

Os motivos de um fechamento. Todos vêm com status: close, willReconnect e statusCode:

transient (willReconnect: true): queda de rede ou erro do lado do WhatsApp, como um 503. A apiwpp tenta de novo, com espera crescente, até abrir.

restart_required (willReconnect: true): o WhatsApp pediu um socket novo, o que é normal logo depois do pareamento. A reconexão é imediata.

replaced (willReconnect: false): outro cliente assumiu a sessão (em geral, statusCode 440). A conexão espera uma reconexão explícita com POST /tenants/{id}/connections/{connId}/connect. Raramente, um replaced é seguido de um open sem que ninguém tenha reconectado: numa falha da infraestrutura, outra instância pode abrir a sessão por alguns instantes, e a conexão é retomada sozinha quando ela sai.

qr_not_scanned (willReconnect: false): ninguém escaneou os QR codes de uma conexão que nunca foi pareada. Conecte de novo para uma nova tentativa.

logged_out (willReconnect: false): a sessão acabou do lado do WhatsApp; o aparelho foi desconectado no celular, removido ou bloqueado (em geral, statusCode 401). É preciso parear de novo, com um QR code novo.

manual (willReconnect: false): alguém chamou POST /connections/{id}/disconnect ou POST /tenants/{id}/connections/{connId}/disconnect. A conexão fica parada até ser conectada de novo.

passkey_required: o QR code foi escaneado, mas o pareamento não terminou porque o WhatsApp pediu uma passkey (chave de acesso) ao celular. status é close, sem phoneNumber (a conexão nunca confirmou um número), sem willReconnect e sem statusCode, e nenhum QR code novo é gerado até a conexão ser conectada de novo. Veja Quando o WhatsApp pede uma passkey.

reachout_timelock: o WhatsApp colocou a conta num bloqueio temporário de novas conversas, depois de um erro 463 num envio ou de uma notificação dele. Não é um fechamento: status é o status atual da conexão, normalmente open, e reachoutTimelock diz até quando o bloqueio vale. Até reachoutTimelock.endsAt, ou até um evento com reachout_timelock_lifted, todo envio da fila é descartado sem ser tentado, e os que têm clientRef geram message.send_failed com reason: reachout_timelocked. O evento chega de novo se o WhatsApp prolongar o bloqueio ou mudar o tipo dele. Veja Bloqueio temporário de novas conversas.

reachout_timelock_lifted: o WhatsApp informou que um bloqueio em vigor acabou antes do prazo, e reachoutTimelock vem com active: false. Um bloqueio que termina no endsAt anunciado não gera este evento: conte com o horário. Um bloqueio sem fim anunciado (endsAt: null) vale até o WhatsApp suspendê-lo, e a apiwpp volta a consultar o WhatsApp no máximo uma vez por minuto antes de recusar um envio.

Quando avisar alguém. willReconnect é a decisão da apiwpp, não uma promessa. Avise na hora num fechamento com willReconnect: false, e num com true só se nenhum open chegar dentro do seu próprio prazo. Decida pelo reason, nunca pelo statusCode, que serve só para diagnóstico. Para consultar o status a qualquer momento, use GET /connections/{id}/qr.

Projeto inativo. Desativar o projeto fecha as conexões dele sem nenhum connection.status: um projeto inativo não recebe webhooks.

Entrega. Um POST com Content-Type: application/json ao webhookBaseUrl do projeto, feito pelo menos uma vez; um projeto inativo não recebe webhooks. Responda 2xx em até 10 segundos: o corpo da resposta é ignorado, e um redirecionamento (3xx) não é seguido e conta como falha. Uma entrega que falha é tentada de novo depois de cerca de 2, 4, 8, 16 e 32 segundos, 6 tentativas no total, e então fica dead. Depois de 5 falhas seguidas, as entregas do projeto ficam em pausa de 30 segundos a 5 minutos, e um evento que passa 24 horas sem ser entregue também fica dead. Uma nova tentativa pode chegar depois de eventos mais novos: ordene pelo timestamp do envelope. Reenvie as entregas dead com POST /webhooks/deliveries/{id}/resend ou POST /webhooks/deliveries/resend-dead.

Assinatura. X-Webhook-Token vem sempre, com o webhookToken do projeto, junto com os webhookHeaders personalizados. Com um webhookSecret, cada tentativa também traz X-Sales-Timestamp (segundos unix da tentativa) e X-Sales-Signature: calcule "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + corpo)) sobre os bytes do corpo exatamente como chegaram, compare em tempo constante e rejeite um X-Sales-Timestamp a mais de 300 segundos do seu relógio. Veja Webhooks e assinatura.

Guia: Parear um número

Cabeçalhos da entrega

X-Webhook-Tokenstringsempre

O webhookToken do projeto, em toda entrega. Pode ser definido, mas nunca é devolvido pela API: troque-o com PATCH /tenants/{id}. Os webhookHeaders personalizados do projeto também são enviados.

X-Sales-Timestampstring

Só quando o projeto tem um webhookSecret: segundos unix desta tentativa de entrega (as novas tentativas são assinadas de novo). Rejeite um que esteja a mais de 300 s do seu relógio.

formato `^\d+$`
X-Sales-Signaturestring

Só quando o projeto tem um webhookSecret: "sha256=" + hex(HMAC-SHA256(webhookSecret, X-Sales-Timestamp + "." + rawBody)). Calcule sobre os bytes do corpo exatamente como recebidos, nunca sobre um objeto serializado de novo, e compare em tempo constante.

formato `^sha256=[0-9a-f]{64}$`

Envelope

typestringsempre presente

O tipo do evento, que decide o formato de data. Ignore os tipos que você não conhece: a lista de eventos pode crescer.

sempre "connection.status"
connectionIdstring · uuidsempre presente

O id (UUID) da conexão, ou seja, do número, que gerou o evento.

tenantIdstring · uuidsempre presente

O id (UUID) do projeto dono da conexão.

externalIdstring | nullsempre presente

O externalId que você informou ao criar a conexão, para ligá-la a um registro seu. null quando a conexão foi criada sem ele.

timestampstring · date-timesempre presente

Quando o evento foi gerado, em ISO 8601 (UTC). É o mesmo em todas as tentativas de entrega; o momento de cada tentativa vem no cabeçalho X-Sales-Timestamp.

Campos de data

statusstringsempre presente

O status da conexão: open (aberta) ou close (fechada). Num evento com reachout_timelock ou reachout_timelock_lifted, é o status do momento, que também pode ser connecting (conectando).

Valores: "connecting", "open", "close"
phoneNumberstring

Os dígitos do número pareado, quando conhecido (por exemplo, 5511900000001). Não vem com passkey_required.

reasonstring

Por que o evento foi enviado. Num fechamento: transient, restart_required, replaced, qr_not_scanned, logged_out, manual ou passkey_required. Com o status atual: reachout_timelock ou reachout_timelock_lifted. Não vem numa abertura.

Valores: "transient", "restart_required", "replaced", "qr_not_scanned", "logged_out", "manual", "reachout_timelock", "reachout_timelock_lifted", "passkey_required"
willReconnectboolean

Só num fechamento com transient, restart_required, replaced, qr_not_scanned, logged_out ou manual: se a apiwpp reconecta sozinha. É true só com transient e restart_required.

statusCodenumber | null

Só junto com willReconnect. O código de desconexão do WhatsApp (por exemplo, 401 sessão encerrada, 440 sessão substituída, 503 erro do WhatsApp, 515 reinício pedido), ou null quando não houve um. Serve para diagnóstico: decida pelo reason.

reachoutTimelockobject

O bloqueio temporário de novas conversas. Vem com reachout_timelock e reachout_timelock_lifted.

reachoutTimelock.activebooleansempre presente

Se o bloqueio está em vigor: true com reachout_timelock, false com reachout_timelock_lifted.

reachoutTimelock.endsAtstring · date-time | nullsempre presente

Quando o bloqueio termina (ISO 8601), ou null quando o WhatsApp não informou um fim ou quando o bloqueio acabou.

reachoutTimelock.enforcementTypestring | nullsempre presente

O tipo de restrição informado pelo WhatsApp, por exemplo DEFAULT ou BIZ_QUALITY; null quando não há bloqueio.

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