Recebendo Eventos

O MessageFy envia eventos em tempo real para a sua aplicação via webhooks — callbacks HTTP POST enviados para a URL configurada no seu canal. Sempre que algo acontece (mensagem recebida, mudança de conexão, resposta a um comando), sua aplicação é notificada automaticamente.

Como funciona

Configure a URL de webhook

Ao criar ou atualizar um canal, defina a URL de webhook para onde os eventos serão enviados.

Eventos acontecem

Quando um evento ocorre (mensagem recebida, status de conexão alterado, resposta a comando, etc.), o MessageFy envia um HTTP POST para a URL configurada.

Processe o evento

Sua aplicação recebe o payload JSON, valida o header de autenticação configurado no canal, processa o evento e retorna HTTP 200.

Formato do payload

Todos os webhooks seguem o formato Package:

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "pedido-8842",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-05-14T19:12:00Z",
  "echoMessage": false,
  "providerMetadata": null,
  "content": {
    "type": "TIPO_DO_EVENTO",
    "timestamp": "2026-05-14T19:12:00Z"
  }
}

Campo	Tipo	Descrição
`packageId`	`string` (UUID) \| `null`	Identificador do pacote, atribuído pela plataforma/gateway. Usado para rastreamento
`correlationId`	`string` \| `null`	Identificador de rastreamento fornecido por você no envio. Fica `null` quando você não o informa (por exemplo, em mensagens recebidas espontaneamente)
`channelId`	`string` (UUID)	Identificador do canal que gerou ou recebe o evento
`timestamp`	`string` (ISO 8601)	Momento em que o pacote foi gerado (nível raiz — distinto de `content.timestamp`)
`echoMessage`	`boolean` \| `null`	`true` quando é uma mensagem ecoada de volta ao remetente
`providerMetadata`	`object` \| `null`	Metadados opcionais do provider (pares chave/valor que variam por provider)
`content`	`object`	Conteúdo do evento. O campo `type` determina o tipo
`content.type`	`string`	Tipo do evento (ex: `TEXT`, `CONNECTED`, `MESSAGE_SENT`)
`content.timestamp`	`string` (ISO 8601)	Momento associado ao conteúdo do evento

O packageId é atribuído pela plataforma e serve para rastreamento. O correlationId é opcional e definido por você no momento do envio — ele retorna nos webhooks de resposta e fica null quando não é informado (é o caso de mensagens recebidas espontaneamente de terceiros). O envelope também pode trazer, quando disponíveis, campos de contexto opcionais: accountId, accountName, organizationID e organizationName.

Resposta esperada

Seu servidor deve retornar HTTP status 200 para confirmar o recebimento do webhook.

Se o servidor retornar um código diferente de 200 (ou não responder), o MessageFy tentará reenviar o webhook. Certifique-se de que seu endpoint é idempotente para evitar processamento duplicado — ou seja, processar o mesmo evento duas vezes não deve causar efeitos colaterais indesejados. Para deduplicar com segurança, combine o packageId com os identificadores do próprio evento (como messageId ou messageIds); não dependa de um único campo, já que packageId e correlationId podem não estar presentes em todos os eventos.

Autenticando os webhooks recebidos

Os webhooks não incluem assinatura criptográfica. Para garantir que as requisições recebidas vêm do MessageFy, use um (ou ambos) dos mecanismos abaixo, configurados no canal de webhook (http-sender):

Headers customizados: defina headers próprios em parameters.headers do canal (ex.: {"X-Webhook-Token": "um-segredo-seu"}). Todos os webhooks daquele canal serão enviados com esses headers — valide o valor no seu endpoint.
Basic Auth via URL: informe credenciais na própria URL do canal (https://user:senha@seu-dominio.com/webhook). A plataforma converte para o header Authorization: Basic ... em cada requisição.

Sempre valide o header configurado antes de processar o webhook. Sem isso, qualquer terceiro que descubra a URL pode enviar payloads forjados ao seu endpoint. Use HTTPS e trate a URL do webhook como um segredo.

Para desenvolvimento local, você pode usar webhook.site para visualizar webhooks recebidos, ou ngrok para expor seu servidor local na internet.

Tipos de eventos

Os eventos estão organizados nas seguintes categorias. Clique no link para ver a documentação completa com payloads e exemplos de cada tipo:

Categoria	Eventos	Documentação
Conexão e sessão	`CONNECTED`, `DISCONNECTED`, `SESSION_EXPIRED`, `INSTANCE_START`, `INSTANCE_STOP`, `INSTANCE_USER_CONNECT_TIMEOUT`, `GENERATE_QR_CODE_RESPONSE`, `PAIR_CODE_GENERATED_RESPONSE`, `SESSION_START_LINK_GENERATED_RESPONSE`, `STATUS_RESPONSE`, `SESSION_START_ERROR`, `PAIRING_ERROR`, `HISTORY_SYNC_PROGRESS`, `HISTORY_SYNC_COMPLETED`, `OFFLINE_SYNC_COMPLETED`, `APP_STATE_SYNC_COMPLETED`	Iniciar Sessão
Passkey	`PASSKEY_REQUEST`, `PASSKEY_CONFIRMATION`, `PASSKEY_ERROR`	Passkey
Backup de sessão	`DEVICE_SESSION_BACKUP`	Backup de sessão
Status de mensagem	`MESSAGE_SENT`, `MESSAGE_FAILED`, `SEND_MESSAGE_RESPONSE` (falha), `MESSAGE_DELIVERED`, `MESSAGE_READ`, `MESSAGE_PLAYED`, `MESSAGE_DELETED`, `MESSAGE_EDITED`, `DOWNLOAD_AVAILABLE`	Status de mensagem
Mensagens recebidas	`TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`, `STICKER`, `LOCATION`, `CONTACT_MESSAGE`, `ORDER`, `REACTION`, `POLL`, `POLL_VOTE`, `FLOW_RECEIVED`	Mensagens
Presença	`CONTACT_PRESENCE`	Presença
Grupo	`GROUP_ACTION_INFO`	Info do Grupo
Chamadas	`CALL_TERMINATED`	Chamadas
Consultas	`GET_LAST_MESSAGES_RESPONSE`	Consultas
Flows	`FLOWS_RESPONSE`, `FLOWS_LIST_RESPONSE`, `FLOWS_DETAIL_RESPONSE`, `FLOWS_PREVIEW_RESPONSE`, `FLOWS_SYNC_RESPONSE`	Flows
Templates	`TEMPLATES_SYNC_RESPONSE`	Sincronizar templates
Carteiras	`WALLET_RESPONSE`, `WALLET_LIST_RESPONSE`, `WALLET_BALANCE_RESPONSE`, `WALLET_ADD_FUND_RESPONSE`, `WALLET_CREDIT_RESPONSE`, `WALLET_STATEMENT_RESPONSE`, `WALLET_TRANSACTIONS_RESPONSE`	Carteiras
Erros de processamento	`UNRECOVERABLE_PROCESS_ERROR`	Erros de processamento
Administração	`CHANNEL_DELETION_COMPLETED`	Administração

Os endereços (from, to) que aparecem nos eventos são polimórficos. Para WhatsApp, o objeto tem a forma { "type": "WHATSAPP", "jid": "...", "lid": "...", "number": "...", "name": "..." }, onde jid é o JID (ex: 5511999887766@s.whatsapp.net), lid é o LinkedID, number é o telefone e name é o nome. Os demais campos são opcionais e aparecem quando conhecidos.

Echo de mensagens enviadas (echoMessage)

Além dos eventos de status, o canal de webhook recebe um eco de cada mensagem enviada: o próprio conteúdo da mensagem, no mesmo formato de uma mensagem recebida, com echoMessage: true no envelope. Ele confirma o que a plataforma processou e permite sincronizar o histórico da conversa do seu lado (inclusive mensagens enviadas por outros dispositivos vinculados ao número, que chegam com content.isFromMe: true).

{
  "packageId": "0192f4b0-1111-7abc-9d56-2c963f66afa6",
  "correlationId": "pedido-12345",
  "originPackageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "echoMessage": true,
  "content": {
    "type": "TEXT",
    "text": "Seu pedido #12345 foi confirmado!",
    "to": { "type": "WHATSAPP", "jid": "5511999887766@s.whatsapp.net" },
    "isFromMe": true,
    "messageId": "3EB0A1B2C3D4E5F6"
  }
}

Campo	Descrição
`echoMessage`	`true` identifica o eco (nas demais mensagens vem `null`/`false`)
`originPackageId`	`packageId` retornado no `200 OK` do envio original
`correlationId`	O identificador que você informou no envio
`content.isFromMe`	Sempre `true` no eco

Trate o eco de forma idempotente junto com o MESSAGE_SENT: os dois se referem ao mesmo envio, correlacionados por originPackageId/correlationId.

Status de mensagem

Eventos que informam o ciclo de vida de mensagens que você enviou (aceitação, entrega, leitura, reprodução de áudio, exclusão e edição), além da disponibilidade de download de mídia recebida.

MESSAGE_SENT

Confirma que uma mensagem enviada por você foi aceita e despachada pelo provider.

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "MESSAGE_SENT",
    "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "messageId": "3EB0C431D2A1F5E9B7",
    "chatId": "5511999887766@s.whatsapp.net",
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "129437285019283@lid"
  }
}

Campo	Tipo	Descrição
`packageId`	`string`	Identificador do pacote de envio correspondente
`messageId`	`string`	Identificador da mensagem atribuído pelo provider
`chatId`	`string`	Chave da conversa (JID de grupo ou telefone)
`jid`	`string`	JID do destino, quando conhecido
`lid`	`string`	LinkedID do destino, quando conhecido

MESSAGE_FAILED

Enviado quando o destino recusa a mensagem após o aceite assíncrono do provider. É o par negativo do MESSAGE_SENT: o provedor aceitou o comando, mas o destinatário final não recebeu a mensagem.

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "MESSAGE_FAILED",
    "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "messageId": "3EB0C431D2A1F5E9B7",
    "chatId": "5511999887766@s.whatsapp.net",
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "129437285019283@lid",
    "message": "Mensagem não entregue pelo destinatário",
    "isGroupMessage": false,
    "timestamp": "2026-09-18T10:30:00Z"
  }
}

Campo	Tipo	Descrição
`packageId`	`string`	Identificador do pacote de envio correspondente
`messageId`	`string`	Identificador da mensagem atribuído pelo provider
`chatId`	`string` \| `null`	Chave da conversa (JID de grupo ou telefone)
`jid`	`string` \| `null`	JID do destino, quando conhecido
`lid`	`string` \| `null`	LinkedID do destino, quando conhecido
`message`	`string` \| `null`	Mensagem descritiva do motivo da falha
`isGroupMessage`	`boolean` \| `null`	`true` quando a mensagem era para um grupo
`timestamp`	`string` (ISO 8601)	Momento em que a falha ocorreu

O MESSAGE_FAILED só aparece em envios com desfecho assíncrono (quando o provider aceita o pacote mas o destinatário recusa posteriormente). Em falhas síncronas, você recebe apenas o SEND_MESSAGE_RESPONSE com success: false.

SEND_MESSAGE_RESPONSE — falha no envio

Quando um envio falha depois do 200 OK (canal desconectado, template não aprovado, saldo insuficiente, destinatário inválido…), a plataforma envia um SEND_MESSAGE_RESPONSE com success: false. Em alguns cenários, o próprio destinatário recusa a mensagem após o aceite assíncrono do provider — nesse caso a plataforma envia também um MESSAGE_FAILED.

{
  "originPackageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "pedido-12345",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "SEND_MESSAGE_RESPONSE",
    "commandType": "SEND_MESSAGE_RESPONSE",
    "success": false,
    "error": "Descrição da falha"
  },
  "providerMetadata": {
    "category": "error",
    "error_code": "...",
    "error_message": "..."
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	`false` indica que a mensagem não foi enviada
`error`	`string`	Descrição da falha
`providerMetadata`	`object` \| `null`	Detalhes adicionais do provider, quando disponíveis

Um 200 OK no SendMessage significa apenas que o pacote foi aceito para processamento. Considere a mensagem enviada somente após receber o MESSAGE_SENT; monitore o SEND_MESSAGE_RESPONSE com success: false e o MESSAGE_FAILED para detectar falhas, correlacionando por originPackageId/correlationId.

MESSAGE_DELIVERED / MESSAGE_READ / MESSAGE_PLAYED

Recibos de entrega (MESSAGE_DELIVERED), leitura (MESSAGE_READ) e reprodução de áudio (MESSAGE_PLAYED). Os três compartilham o mesmo formato de payload.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "MESSAGE_DELIVERED",
    "messageIds": ["3EB0C431D2A1F5E9B7"],
    "chatId": "5511999887766@s.whatsapp.net",
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "129437285019283@lid",
    "isHistoryEvent": false
  }
}

Campo	Tipo	Descrição
`messageIds`	`string[]`	Identificadores das mensagens afetadas pelo recibo
`chatId`	`string`	Chave da conversa (JID de grupo ou telefone; LID como último recurso)
`jid`	`string`	JID de quem emitiu o recibo, quando conhecido
`lid`	`string`	LinkedID de quem emitiu o recibo, quando conhecido
`isHistoryEvent`	`boolean`	`true` quando o recibo veio da sincronização de histórico

MESSAGE_DELETED

Enviado quando uma mensagem é apagada para todos.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "MESSAGE_DELETED",
    "messageId": "3EB0C431D2A1F5E9B7",
    "chatId": "5511999887766@s.whatsapp.net",
    "isFromMe": false,
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "129437285019283@lid"
  }
}

Campo	Tipo	Descrição
`messageId`	`string`	Identificador da mensagem apagada
`chatId`	`string`	Chave da conversa em que a mensagem foi apagada
`isFromMe`	`boolean`	`true` se quem apagou foi o próprio canal
`jid`	`string`	JID de quem apagou, quando conhecido
`lid`	`string`	LinkedID de quem apagou, quando conhecido

MESSAGE_EDITED

Enviado quando uma mensagem é editada.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "MESSAGE_EDITED",
    "messageId": "3EB0C431D2A1F5E9B7",
    "newMessageId": "3EB0C431D2A1F5E9C0",
    "chatId": "5511999887766@s.whatsapp.net",
    "newText": "Texto corrigido",
    "isFromMe": true,
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "129437285019283@lid"
  }
}

Campo	Tipo	Descrição
`messageId`	`string`	Identificador da mensagem original
`newMessageId`	`string` \| `null`	Novo identificador da mensagem após a edição
`chatId`	`string`	Chave da conversa em que a mensagem foi editada
`newText`	`string`	Novo conteúdo de texto da mensagem
`isFromMe`	`boolean`	`true` se quem editou foi o próprio canal
`jid`	`string`	JID de quem editou, quando conhecido
`lid`	`string`	LinkedID de quem editou, quando conhecido

DOWNLOAD_AVAILABLE

Enviado quando o download de uma mídia recebida fica disponível (após o upload ser confirmado no StorageFy). A externalDownloadUrl é a URL pré-assinada para baixar o arquivo. Nos pedidos (ORDER), essa URL corresponde ao items[].imageUrl de cada item.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "DOWNLOAD_AVAILABLE",
    "success": true,
    "messageId": "3EB0C431D2A1F5E9B7",
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999887766@s.whatsapp.net",
      "number": "5511999887766",
      "name": "Fulano"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988776655@s.whatsapp.net",
      "number": "5511988776655"
    },
    "externalDownloadUrl": "https://storage.messagefy.io/media/3fa85f64.jpg",
    "errorMessage": null,
    "isStatusMessage": false,
    "isHistoryDownload": false
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	`true` quando o download foi processado com sucesso
`messageId`	`string`	Identificador da mensagem de mídia original
`from`	`Address`	Endereço de origem da mídia, quando conhecido
`to`	`Address`	Endereço de destino da mídia, quando conhecido
`externalDownloadUrl`	`string` (URL)	URL pré-assinada para baixar o arquivo
`errorMessage`	`string` \| `null`	Mensagem de erro quando `success` é `false`
`isStatusMessage`	`boolean`	`true` se a mídia pertence a uma mensagem de status
`isHistoryDownload`	`boolean`	`true` quando o download veio da sincronização de histórico

Enquetes e votos

POLL - Enquete recebida

Enviado quando uma enquete é recebida pelo canal. O messageId da enquete é o pollMessageId que os votos subsequentes referenciam.

{
  "packageId": "019a129d-06ad-74bc-9543-bcc030a38169",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "content": {
    "type": "POLL",
    "name": "Qual horário você prefere?",
    "options": ["Manhã", "Tarde", "Noite"],
    "selectableCount": 1,
    "optionHashes": [
      "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
      "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3",
      "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
    ],
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777"
    },
    "messageId": "3EB08209536937A66D8434",
    "isFromMe": false,
    "isGroupMessage": false,
    "timestamp": "2025-10-23T19:47:51+00:00"
  }
}

Campo	Tipo	Descrição
`name`	`string`	Pergunta da enquete
`options`	`string[]`	Lista de opções da enquete (2 a 12 opções)
`selectableCount`	`integer`	Quantas opções podem ser marcadas. `0` = múltipla escolha livre
`optionHashes`	`string[]`	SHA-256 (hex) de cada opção, na mesma ordem de `options`. Use para correlacionar com votos
`messageId`	`string`	ID da enquete. Este é o `pollMessageId` que os votos referenciam

Veja a documentação completa em Enquete.

POLL_VOTE - Voto em enquete

Enviado quando alguém vota em uma enquete. Cada voto traz a seleção completa e atual do votante e substitui a anterior — lista vazia é voto retirado. A contagem fica por conta do consumidor.

{
  "packageId": "019a129e-12ab-74bc-9543-bcc030a38170",
  "channelId": "019a1258-177c-7286-b060-9ee02a0800c7",
  "content": {
    "type": "POLL_VOTE",
    "pollMessageId": "3EB08209536937A66D8434",
    "voter": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "selectedOptionHashes": [
      "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
    ],
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999998888@s.whatsapp.net",
      "number": "5511999998888",
      "name": "Cliente"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988887777@s.whatsapp.net",
      "number": "5511988887777"
    },
    "messageId": "3EB0C431D2A1F5E9B7",
    "isFromMe": false,
    "isGroupMessage": false,
    "timestamp": "2025-10-23T19:50:00+00:00"
  }
}

Campo	Tipo	Descrição
`pollMessageId`	`string`	ID da enquete votada (o `messageId` da enquete original)
`voter`	`Address`	Quem votou. Em grupo, o participante. Veja formatos de endereço
`selectedOptionHashes`	`string[]`	SHA-256 (hex) de cada opção escolhida. Compare com `optionHashes` da enquete para saber o nome da opção
`messageId`	`string`	ID do voto no provedor

O WhatsApp só entrega o hash de cada opção escolhida. Para saber o nome da opção, compare os selectedOptionHashes com os optionHashes da enquete original (recebida via webhook POLL). Se a enquete foi enviada pela API, calcule o SHA-256 do texto de cada opção.

Cada voto traz a seleção completa e atual do votante, substituindo a anterior. Lista vazia (selectedOptionHashes: []) significa que o votante retirou seu voto. A contagem de votos fica por conta do consumidor.

Consultas

Eventos de resposta a comandos de consulta, sinalizando o fim do processamento do pedido.

GET_LAST_MESSAGES_RESPONSE

Enviado quando o processamento do comando Últimas Mensagens termina. As mensagens individuais chegam como webhooks separados (nos formatos de mensagem recebida: TEXT, IMAGE, etc.); este evento informa apenas o resultado global da operação — se foi bem-sucedida e quantas mensagens foram pedidas.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "GET_LAST_MESSAGES_RESPONSE",
    "chatJID": "5511999887766@s.whatsapp.net",
    "messageIdReference": "3EB0A1B2C3D4E5F6",
    "requestedCount": 20,
    "status": "COMPLETED",
    "message": null,
    "success": true,
    "error": null
  }
}

Campo	Tipo	Descrição
`chatJID`	`string` \| `null`	JID da conversa consultada
`messageIdReference`	`string` \| `null`	`messageId` usado como cursor de paginação na requisição, quando informado
`requestedCount`	`integer` \| `null`	Quantidade de mensagens solicitadas
`status`	`string` \| `null`	Status do processamento (ex.: `COMPLETED`)
`message`	`string` \| `null`	Mensagem descritiva adicional
`success`	`boolean`	`true` se a consulta foi concluída com sucesso
`error`	`string` \| `null`	Descrição do erro, quando `success` é `false`

Use o success deste evento como sinal definitivo de término da operação — as mensagens individuais podem chegar antes ou depois deste webhook. Correlacione a requisição original pelo packageId do envelope.

Passkey

O WhatsApp introduziu uma verificação por passkey (companion linking via WebAuthn) que pode interromper o login por QR Code. Durante esse fluxo, a plataforma envia três eventos ao seu webhook e espera que você responda com o comando Confirmar Passkey. O fluxo é:

A plataforma envia PASSKEY_REQUEST quando o WhatsApp exige a verificação por passkey.
Em seguida envia PASSKEY_CONFIRMATION com o code que deve ser exibido ao operador.
Você responde via POST /api/v1/message/SendCommand com PASSKEY_CONFIRM (abort: false conclui o pareamento; abort: true cancela).
Se algo falhar, a plataforma envia PASSKEY_ERROR.

PASSKEY_REQUEST

Sinaliza que o WhatsApp exige verificação por passkey. Não possui campos específicos além do envelope e do content.type.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_REQUEST"
  }
}

PASSKEY_CONFIRMATION

Carrega o código de verificação que deve ser apresentado ao operador para concluir o pareamento.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_CONFIRMATION",
    "code": "8F3K-92QP",
    "skipHandoffUX": false
  }
}

Campo	Tipo	Descrição
`code`	`string`	Código de verificação a exibir ao operador (obrigatório)
`skipHandoffUX`	`boolean`	`true` quando a etapa de handoff visual pode ser pulada

PASSKEY_ERROR

Enviado quando a verificação por passkey falha.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "PASSKEY_ERROR",
    "error": "passkey_timeout",
    "continuation": true
  }
}

Campo	Tipo	Descrição
`error`	`string`	Descrição do erro ocorrido (obrigatório)
`continuation`	`boolean`	`true` quando o fluxo ainda pode continuar após o erro

Se o número usar passkey e o login por QR não avançar, use a importação de sessão (Importar Sessão) como alternativa para conectar sem pareamento.

Backup de sessão

DEVICE_SESSION_BACKUP

Carrega o blob completo da sessão do dispositivo em sessionData. É o par de Importar Sessão: permite reimportar a sessão posteriormente sem um novo pareamento.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "DEVICE_SESSION_BACKUP",
    "sessionData": "<blob-opaco-da-sessao>"
  }
}

Campo	Tipo	Descrição
`sessionData`	`string`	Blob opaco com o estado completo da sessão do dispositivo

O sessionData é uma credencial bruta de autenticação — quem o possui tem acesso total à conta do WhatsApp. Trafegue-o apenas sobre TLS, nunca o registre em logs nem o persista no cliente sem necessidade, e trate-o como um segredo.

Carteiras

Eventos de resposta a operações de carteira (saldo, extrato, crédito, etc.). Todas as respostas incluem errorCode quando success: false, permitindo tratamento programático de erros.

WALLET_RESPONSE

Resposta genérica de carteira, usada quando a operação falha ou quando não há payload específico.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_RESPONSE",
    "commandType": "WALLET",
    "success": false,
    "error": "Operação não suportada",
    "errorCode": "COMMAND_NOT_SUPPORTED"
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	`true` se a operação foi bem-sucedida
`error`	`string` \| `null`	Descrição legível do erro quando `success: false`
`errorCode`	`string` \| `null`	Código estável do erro (`WALLET_NOT_FOUND`, `COMMAND_NOT_SUPPORTED`, etc.)

WALLET_LIST_RESPONSE

Lista de carteiras disponíveis.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_LIST_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "wallets": [
      {
        "id": "wallet-uuid",
        "balance": 150.75,
        "currency": "BRL",
        "name": "Carteira Principal",
        "isDefault": true
      }
    ],
    "count": 1
  }
}

Campo	Tipo	Descrição
`wallets`	`WalletDetails[]` \| `null`	Lista de carteiras
`count`	`integer`	Quantidade de carteiras na lista
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

WALLET_BALANCE_RESPONSE

Saldo detalhado de uma carteira específica.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_BALANCE_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "wallet": {
      "id": "wallet-uuid",
      "balance": 150.75,
      "currency": "BRL",
      "name": "Carteira Principal",
      "isDefault": true
    }
  }
}

Campo	Tipo	Descrição
`wallet`	`WalletDetails` \| `null`	Detalhes da carteira consultada
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

WALLET_ADD_FUND_RESPONSE

Resposta ao solicitar adição de fundos (gera link de checkout).

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_ADD_FUND_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "link": "https://checkout.example.com/pay/abc123",
    "fundRequestId": "fund-req-uuid"
  }
}

Campo	Tipo	Descrição
`link`	`string` \| `null`	URL de checkout para adicionar fundos
`fundRequestId`	`string` \| `null`	Identificador da solicitação de fundos
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

WALLET_CREDIT_RESPONSE

Resposta ao creditar valor em uma carteira.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_CREDIT_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "message": "Crédito de R$ 50,00 realizado com sucesso"
  }
}

Campo	Tipo	Descrição
`message`	`string` \| `null`	Mensagem descritiva do resultado
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

WALLET_STATEMENT_RESPONSE

Extrato da carteira (lançamentos recentes). Substitui o antigo WALLET_TRANSACTIONS_RESPONSE.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_STATEMENT_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "transactions": [
      {
        "id": "txn-uuid",
        "walletId": "wallet-uuid",
        "type": "CREDIT",
        "amount": 50.00,
        "description": "Crédito de teste",
        "referenceId": "ref-123",
        "createdAt": "2026-10-14T10:30:00Z"
      }
    ],
    "count": 1
  }
}

Campo	Tipo	Descrição
`transactions`	`WalletTransactionDetails[]` \| `null`	Lista de lançamentos
`count`	`integer`	Quantidade de lançamentos
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

WALLET_TRANSACTIONS_RESPONSE

Deprecado: use WALLET_STATEMENT_RESPONSE. Mantido para compatibilidade com operações antigas.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "WALLET_TRANSACTIONS_RESPONSE",
    "commandType": "WALLET",
    "success": true,
    "transactions": [
      {
        "id": "txn-uuid",
        "walletId": "wallet-uuid",
        "type": "CREDIT",
        "amount": 50.00,
        "description": "Crédito de teste",
        "referenceId": "ref-123",
        "createdAt": "2026-10-14T10:30:00Z"
      }
    ],
    "count": 1
  }
}

Campo	Tipo	Descrição
`transactions`	`WalletTransactionDetails[]` \| `null`	Lista de transações
`count`	`integer`	Quantidade de transações
`errorCode`	`string` \| `null`	Código do erro quando `success: false`

Todos os eventos de carteira incluem campos adicionais do Billing (como available, reserved, status, balanceAfter) que variam conforme a operação. Consulte a documentação da API de Billing para detalhes completos.

Erros de processamento

UNRECOVERABLE_PROCESS_ERROR

Enviado quando a plataforma não consegue processar um conteúdo recebido de forma irrecuperável. O campo originalContent ecoa o conteúdo que falhou (incluindo o seu próprio type), permitindo diagnóstico e reprocessamento manual.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "UNRECOVERABLE_PROCESS_ERROR",
    "message": "Falha ao processar o conteúdo recebido",
    "error": "InvalidOperationException: conteúdo inconsistente",
    "originalContent": {
      "type": "IMAGE",
      "caption": "foto do produto"
    }
  }
}

Campo	Tipo	Descrição
`message`	`string` \| `null`	Descrição legível do erro
`error`	`string` \| `null`	Detalhe técnico do erro (ex: exceção)
`originalContent`	`object` \| `null`	Conteúdo original que falhou (um `content` completo, com seu próprio `type`)

Chamadas

Eventos relacionados ao ciclo de vida de chamadas (voz/vídeo) recebidas no canal. Atualmente o MessageFy apenas observa o término de chamadas — não há comandos para iniciá-las.

CALL_TERMINATED

Enviado quando uma chamada recebida pelo canal é encerrada (atendida, recusada ou perdida).

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "CALL_TERMINATED",
    "callId": "1234567890ABCDEF",
    "callTime": "2026-05-14T19:12:00Z",
    "reason": "rejected",
    "isFromMe": false,
    "from": {
      "type": "WHATSAPP",
      "jid": "5511999887766@s.whatsapp.net",
      "number": "5511999887766",
      "name": "Fulano"
    },
    "to": {
      "type": "WHATSAPP",
      "jid": "5511988776655@s.whatsapp.net",
      "number": "5511988776655"
    }
  }
}

Campo	Tipo	Descrição
`callId`	`string`	Identificador único da chamada
`callTime`	`string` (ISO 8601)	Momento em que a chamada terminou
`reason`	`string`	Motivo do encerramento. Chamadas recebidas: `accepted`, `rejected`, `no_reaction`, `unknown`. Chamadas realizadas pelo canal: `outgoing_call_accepted`, `outgoing_call_rejected`, `outgoing_call_no_action`, `outgoing_call_unknown`
`isFromMe`	`boolean`	`true` se a chamada partiu do canal (saída), `false` se foi recebida
`from`	`Address`	Endereço que originou a chamada
`to`	`Address`	Endereço de destino da chamada

O conteúdo da chamada (áudio/vídeo) não é capturado — o MessageFy só registra que ela ocorreu e seu desfecho. Use este evento para auditoria, métricas ou para acionar fluxos de atendimento.

Administração

Eventos disparados ao final de operações administrativas assíncronas no canal.

CHANNEL_DELETION_COMPLETED

Enviado para o canal de feedback quando a deleção assíncrona de um canal termina. A deleção é iniciada por DELETE /api/v1/Admin/Channel/{id} (retorna 204 imediatamente) e finaliza em background; este evento sinaliza o fim do processo.

{
  "packageId": null,
  "channelId": "feedback-channel-uuid",
  "content": {
    "type": "CHANNEL_DELETION_COMPLETED",
    "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "channelName": "Loja Centro",
    "accountId": "11111111-2222-3333-4444-555555555555",
    "organizationId": "66666666-7777-8888-9999-aaaaaaaaaaaa",
    "success": true,
    "message": null
  }
}

Campo	Tipo	Descrição
`channelId`	`string` (UUID)	Identificador do canal que foi deletado
`channelName`	`string`	Nome do canal no momento da deleção
`accountId`	`string` (UUID)	Conta dona do canal
`organizationId`	`string` (UUID)	Organização da conta
`success`	`boolean`	`true` se a deleção foi concluída com sucesso
`message`	`string`	Mensagem opcional descrevendo erro ou status

Este evento é enviado ao canal de feedback do canal deletado, não ao canal deletado em si (que não existe mais). Configure um canal de feedback se quiser receber o sinal de conclusão.

​Recebendo Eventos

​Como funciona

​Formato do payload

​Resposta esperada

​Autenticando os webhooks recebidos

​Tipos de eventos

​Echo de mensagens enviadas (echoMessage)

​Status de mensagem

​MESSAGE_SENT

​MESSAGE_FAILED

​SEND_MESSAGE_RESPONSE — falha no envio

​MESSAGE_DELIVERED / MESSAGE_READ / MESSAGE_PLAYED

​MESSAGE_DELETED

​MESSAGE_EDITED

​DOWNLOAD_AVAILABLE

​Enquetes e votos

​POLL - Enquete recebida

​POLL_VOTE - Voto em enquete

​Consultas

​GET_LAST_MESSAGES_RESPONSE

​Passkey

​PASSKEY_REQUEST

​PASSKEY_CONFIRMATION

​PASSKEY_ERROR

​Backup de sessão

​DEVICE_SESSION_BACKUP

​Carteiras

​WALLET_RESPONSE

​WALLET_LIST_RESPONSE

​WALLET_BALANCE_RESPONSE

​WALLET_ADD_FUND_RESPONSE

​WALLET_CREDIT_RESPONSE

​WALLET_STATEMENT_RESPONSE

​WALLET_TRANSACTIONS_RESPONSE

​Erros de processamento

​UNRECOVERABLE_PROCESS_ERROR

​Chamadas

​CALL_TERMINATED

​Administração

​CHANNEL_DELETION_COMPLETED

Recebendo Eventos

Como funciona

Formato do payload

Resposta esperada

Autenticando os webhooks recebidos

Tipos de eventos

Echo de mensagens enviadas (echoMessage)

Status de mensagem

MESSAGE_SENT

MESSAGE_FAILED

SEND_MESSAGE_RESPONSE — falha no envio

MESSAGE_DELIVERED / MESSAGE_READ / MESSAGE_PLAYED

MESSAGE_DELETED

MESSAGE_EDITED

DOWNLOAD_AVAILABLE

Enquetes e votos

POLL - Enquete recebida

POLL_VOTE - Voto em enquete

Consultas

GET_LAST_MESSAGES_RESPONSE

Passkey

PASSKEY_REQUEST

PASSKEY_CONFIRMATION

PASSKEY_ERROR

Backup de sessão

DEVICE_SESSION_BACKUP

Carteiras

WALLET_RESPONSE

WALLET_LIST_RESPONSE

WALLET_BALANCE_RESPONSE

WALLET_ADD_FUND_RESPONSE

WALLET_CREDIT_RESPONSE

WALLET_STATEMENT_RESPONSE

WALLET_TRANSACTIONS_RESPONSE

Erros de processamento

UNRECOVERABLE_PROCESS_ERROR

Chamadas

CALL_TERMINATED

Administração

CHANNEL_DELETION_COMPLETED