Confirmar Passkey

O comando Confirmar Passkey (PASSKEY_CONFIRM) é a sua resposta ao fluxo de verificação por passkey do WhatsApp. Alguns números passam a exigir uma verificação de segurança (passkey / security-key) que interrompe o login por QR Code. Quando isso acontece, a plataforma conduz o fluxo por webhooks e aguarda que você confirme (ou cancele) o pareamento enviando este comando. O fluxo segue o padrão de companion linking (WebAuthn) do WhatsApp:

A plataforma emite o webhook PASSKEY_REQUEST assim que o WhatsApp exige a verificação por passkey.
Em seguida, emite PASSKEY_CONFIRMATION com o code que deve ser exibido ao operador.
Você responde via /SendCommand com PASSKEY_CONFIRM, informando abort: false conclui o pareamento; true cancela (a conexão é encerrada).
Se a verificação falhar, a plataforma emite PASSKEY_ERROR.

Este comando só faz sentido dentro de uma sessão de conexão em andamento, em resposta a um webhook PASSKEY_CONFIRMATION. Enviá-lo fora desse contexto não tem efeito.

Requisição

POST /api/v1/message/SendCommand

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "PASSKEY_CONFIRM",
    "commandType": "PASSKEY_CONFIRM",
    "abort": false
  }
}

Campos

string

required

Deve ser "PASSKEY_CONFIRM".

string

required

Deve ser "PASSKEY_CONFIRM".

boolean

default:"false"

Define o desfecho da verificação:

false — conclui o pareamento com a passkey e finaliza a conexão do canal.
true — cancela o fluxo. A ponte de conexão é encerrada e o canal permanece desconectado.

Resposta da API

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

O resultado da confirmação chega de forma assíncrona pelos webhooks do fluxo: após um PASSKEY_CONFIRM com abort: false bem-sucedido, o canal termina de conectar e você recebe o evento CONNECTED. Em caso de falha, você recebe PASSKEY_ERROR.

Webhooks do fluxo de passkey

Durante o fluxo, o canal (do tipo http-sender) associado como feedback recebe os webhooks abaixo. Todos são entregues no envelope padrão do Package, com o conteúdo em content.

PASSKEY_REQUEST

Emitido quando o WhatsApp passa a exigir a verificação por passkey. Não possui campos adicionais além do envelope.

{
  "packageId": "0f9c1c1e-6b4a-7c2d-9e3f-1a2b3c4d5e6f",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_REQUEST",
    "commandType": "PASSKEY_REQUEST"
  }
}

PASSKEY_CONFIRMATION

Traz o código que deve ser apresentado ao operador para concluir a verificação no aparelho.

{
  "packageId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_CONFIRMATION",
    "commandType": "PASSKEY_CONFIRMATION",
    "code": "8F2K-4Q9Z",
    "skipHandoffUX": false
  }
}

Campo	Tipo	Descrição
`code`	`string`	Obrigatório. Código a ser exibido ao operador para concluir a verificação por passkey.
`skipHandoffUX`	`boolean`	Indica se a etapa de handoff (transferência para o operador concluir no aparelho) deve ser pulada. Padrão `false`.

PASSKEY_ERROR

Emitido quando a verificação por passkey falha.

{
  "packageId": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_ERROR",
    "commandType": "PASSKEY_ERROR",
    "error": "PASSKEY_TIMEOUT",
    "continuation": false
  }
}

Campo	Tipo	Descrição
`error`	`string`	Obrigatório. Descrição/código do erro ocorrido na verificação.
`continuation`	`boolean`	Indica se o fluxo pode continuar (nova tentativa) após o erro. Padrão `false`.

Exemplo completo

Concluindo o pareamento após receber o webhook PASSKEY_CONFIRMATION:

curl -X POST https://api-dev.messagefy.io/api/v1/message/SendCommand \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: sua-api-key" \
  -d '{
    "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": {
      "type": "PASSKEY_CONFIRM",
      "commandType": "PASSKEY_CONFIRM",
      "abort": false
    }
  }'

import requests

response = requests.post(
    "https://api-dev.messagefy.io/api/v1/message/SendCommand",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key"
    },
    json={
        "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "content": {
            "type": "PASSKEY_CONFIRM",
            "commandType": "PASSKEY_CONFIRM",
            "abort": False
        }
    }
)

print(response.json())

const response = await fetch(
  "https://api-dev.messagefy.io/api/v1/message/SendCommand",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "sua-api-key",
    },
    body: JSON.stringify({
      channelId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      content: {
        type: "PASSKEY_CONFIRM",
        commandType: "PASSKEY_CONFIRM",
        abort: false,
      },
    }),
  }
);

const data = await response.json();
console.log(data);

Cancelando o fluxo

Para abortar a verificação, envie o mesmo comando com abort igual a true:

{
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_CONFIRM",
    "commandType": "PASSKEY_CONFIRM",
    "abort": true
  }
}

Exiba o code recebido em PASSKEY_CONFIRMATION ao operador antes de enviar o PASSKEY_CONFIRM com abort: false. O código é necessário para concluir a verificação diretamente no aparelho.

Se o número exigir passkey e você não conseguir concluir este fluxo, o login por QR Code não será possível. Nesse caso, utilize a Importação de Sessão (SESSION_IMPORT) como alternativa para conectar um número já autenticado, sem pareamento.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Confirmar Passkey

Confirmar Passkey

Requisição

Campos

Resposta da API

Webhooks do fluxo de passkey

PASSKEY_REQUEST

PASSKEY_CONFIRMATION

PASSKEY_ERROR

Exemplo completo

Cancelando o fluxo

​Confirmar Passkey

​Requisição

​Campos

​Resposta da API

​Webhooks do fluxo de passkey

​PASSKEY_REQUEST

​PASSKEY_CONFIRMATION

​PASSKEY_ERROR

​Exemplo completo

​Cancelando o fluxo

Confirmar Passkey

Requisição

Campos

Resposta da API

Webhooks do fluxo de passkey

PASSKEY_REQUEST

PASSKEY_CONFIRMATION

PASSKEY_ERROR

Exemplo completo

Cancelando o fluxo