Catálogo de eventos

Cada evento que a BotoZap emite, a categoria que o Endpoint precisa assinar para recebê-lo, a chave de idempotência e o payload completo.

Esta página é a referência dos nomes finos de evento. Para cadastrar, verificar e auditar um Endpoint, veja Webhooks; para retry, ordem e duplicatas, veja Confiabilidade e entrega.

Categorias de assinatura

Um Endpoint assina categorias, não nomes finos: POST /api/v1/webhooks aceita em events apenas messages, statuses, crm, account e app_messages. Valores fora dessa lista são descartados, e uma lista sem nenhum valor válido responde 422 invalid_events. Assinar uma categoria entrega todos os eventos dela, inclusive os que forem adicionados depois. app_messages é opt-in: só chega a Endpoints que a têm em events; um Endpoint sem categorias (events vazio) recebe as outras quatro, mas não esta.

CategoriaO que entrega
messagesMensagens recebidas e mudanças de Consentimento (crm.contact.consent_changed, apesar do prefixo crm.).
statusesStatus das mensagens enviadas pela BotoZap (enviada, entregue, lida, falhou) e o término de uma execução de Régua (automation.journey_run.finished).
crmTodo Evento crm.* exceto Consentimento: mudança de etapa do contato, oportunidades, demandas e agendamentos (criados e atualizados).
accountSaúde da WABA e conexão de número: número conectado pelo Embedded Signup, banimentos, restrições, violações e mudança de limite de mensagens do número.
app_messagesOpt-in. Coexistência: mensagens que a equipe envia, edita ou apaga pelo app WhatsApp Business. Só chega a Endpoints que assinaram app_messages explicitamente; um Endpoint sem categorias (events vazio) não a recebe.

Duas exceções ao prefixo do nome: crm.contact.consent_changed pertence a messages (um Endpoint assinado só em crm não o recebe) e automation.journey_run.finished pertence a statuses. O evento webhook.test não pertence a categoria nenhuma: vai só para o Endpoint que você testou.

EventoCategoriaNo streamX-Idempotency-Key
whatsapp.message.receivedmessagessim<wamid>
whatsapp.message.updatedmessagessim<wamid>:updated
whatsapp.message.echoapp_messagesnão<wamid>
whatsapp.message.editedapp_messagesnão<wamid do eco>:edited
whatsapp.message.revokedapp_messagesnão<wamid do eco>:revoked
whatsapp.message.sentstatusessim<wamid>:sent
whatsapp.message.deliveredstatusessim<wamid>:delivered
whatsapp.message.readstatusessim<wamid>:read
whatsapp.message.playedstatusessim<wamid>:played
whatsapp.message.failedstatusessim<wamid>:failed
whatsapp.account.updatedaccountsimwhatsapp.account.updated:<sha256 do payload normalizado>
whatsapp.phone_number.quality_updatedaccountsimwhatsapp.phone_number.quality_updated:<sha256 do payload normalizado>
whatsapp.phone_number.connectedaccountsimwhatsapp.phone_number.connected:<setup_link_id>:<phone_number_id>
crm.contact.stage_changedcrmsimcrm:stage:<contact_id>:<transação>:<etapa anterior|none>><nova etapa|none>
crm.contact.consent_changedmessagessimconsent:<id do registro de consentimento>
crm.opportunity.createdcrmsimcrm:opportunity:<id>:<version>
crm.opportunity.updatedcrmsimcrm:opportunity:<id>:<version>
crm.demand.createdcrmsimcrm:demand:<id>:<version>
crm.demand.updatedcrmsimcrm:demand:<id>:<version>
crm.appointment_createdcrmsimcrm:appointment:<id>:created
crm.appointment_updatedcrmsimappointment:<id>:<revision>
automation.journey_run.finishedstatusessimjourney_run:<run_id>:<status>
instagram.message.receivedmessagessim<mid>
instagram.message.reactionmessagessim<mid>:reaction:<actor|self>:<epoch em ms>
instagram.message.editedmessagessim<mid>:edited:<num_edit> (sem num_edit: <mid>:edited:<epoch em ms>)
instagram.message.revokedmessagessim<mid>:revoked
instagram.comment.receivedmessagessim<comment_id>
instagram.comment.repliedmessagessim<comment_id>:replied
instagram.message.sentstatusessim<mid>:sent
instagram.message.readstatusessim<mid>:read
instagram.message.failedstatusessim<mid>:failed
instagram.message_rule.failedstatusessim<run_id>:failed
webhook.testnenhumanãotest:<endpoint_id>

Nomes reservados, com categoria definida mas sem emissão hoje: instagram.message.delivered (Reservado: o Instagram não envia confirmação de entrega, então este evento não é emitido hoje.)

Envelope comum

Todo corpo é um objeto JSON com event (o mesmo valor do header X-Webhook-Event), customer_id (o Cliente dono da origem do evento; null quando a cadeia não pôde ser resolvida e no webhook.test) e environment (live ou sandbox, o ambiente da Conta de canal de origem; null só no webhook.test, que não nasce de canal nenhum). Os eventos ligados a um canal de mensagem também trazem o carimbo de canal:

  • channel: o canal da origem, ex. whatsapp.
  • channel_account: a Conta de canal de origem, como { id, channel, display }.
  • external_id: o identificador da mensagem no canal (o wamid no WhatsApp). Ausente nos eventos de CRM e de automação, que não se referem a uma mensagem.

Os eventos da categoria account (saúde da WABA e número conectado) e o webhook.test não têm carimbo de canal. A ordem das chaves não é garantida; leia os campos pelo nome.

Categoria messages

whatsapp.message.received

Um contato envia uma mensagem para um número conectado (inclusive respostas de botão e de lista). X-Idempotency-Key: <wamid>. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta que recebeu a mensagem.
  • message: O objeto de mensagem cru da Cloud API (id, from, timestamp, type, o conteúdo do tipo e context quando é resposta ou botão), mais external_id. Quando o contato chega por anúncio Click-to-WhatsApp, traz o referral da Meta (source_id, source_url, source_type, headline, ctwa_clid…; ctwa_clid não vem em anúncios de Status).
  • contact: wa_id (telefone ou, sem telefone, o BSUID), user_id, username, phone, profile_name e metadata (os campos personalizados do contato).

No stream, data.message é normalizado pela BotoZap (id, external_id, resource_id, conversation_id, contact_id, direction, type, status, content, context, timestamp) em vez do objeto cru da Cloud API, e data.contact inclui o id do contato.

{
  "event": "whatsapp.message.received",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "message": {
    "from": "5511988887777",
    "id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
    "timestamp": "1790341200",
    "type": "text",
    "text": {
      "body": "Oi, quero saber do meu pedido"
    },
    "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE"
  },
  "contact": {
    "wa_id": "5511988887777",
    "user_id": null,
    "username": null,
    "phone": "5511988887777",
    "profile_name": "Maria",
    "metadata": {}
  }
}

whatsapp.message.updated

Uma mensagem recebida chegou indisponível (type unsupported com o erro 131060 da Meta) e a Meta mandou o conteúdo depois, com o mesmo wamid. Se o whatsapp.message.received ainda não tinha sido enviado ao Endpoint, ele sai com o conteúdo real e este evento não é emitido para esse Endpoint. Quando a Meta não manda o conteúdo, só o contato reenviando resolve. X-Idempotency-Key: <wamid>:updated. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta que recebeu a mensagem.
  • message: O objeto de mensagem cru da Cloud API com o conteúdo que chegou (mesmo formato do whatsapp.message.received), mais external_id. O id é o wamid do received indisponível: atualize a mensagem que você já tem.
  • contact: wa_id (telefone ou, sem telefone, o BSUID), user_id, username, phone, profile_name e metadata (os campos personalizados do contato).

No stream, data.message vem normalizado como no whatsapp.message.received, já com type e content reais. O received do stream continua com type unknown e content.error_code 131060.

{
  "event": "whatsapp.message.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "message": {
    "from": "5511988887777",
    "id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
    "timestamp": "1790341200",
    "type": "text",
    "text": {
      "body": "Oi, quero saber do meu pedido"
    },
    "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE"
  },
  "contact": {
    "wa_id": "5511988887777",
    "user_id": null,
    "username": null,
    "phone": "5511988887777",
    "profile_name": "Maria",
    "metadata": {}
  }
}

Um Consentimento do contato é registrado ou revogado (painel, importação, API, Palavra de saída, Palavra de volta, botão de conversa, botão de saída do template ou recusa informada pela Meta), inclusive a cópia para os outros contatos da mesma pessoa no Cliente. X-Idempotency-Key: consent:<id do registro de consentimento>. Também entra no stream GET /api/v1/events.

  • contact: { id } do contato.
  • channel: Canal do Consentimento.
  • purpose: Finalidade: utility ou marketing.
  • state: granted ou revoked.
  • origin: manual, import, api, keyword (Palavra de saída), conversation_button (botão do pedido de consentimento), template_button (botão de saída marcado no template), meta_opt_out (erro 131050 da Meta), contact_keyword (Palavra de volta) ou owner_declaration (aceite gravado no envio de um follow-up de Marketing com a declaração do dono). Só conversation_button e contact_keyword, do próprio contato, desfazem uma recusa.
  • evidence: Texto de evidência (até 500 caracteres; vazio quando não informado).
  • occurred_at: Momento do registro.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.contact.consent_changed",
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
  },
  "purpose": "marketing",
  "state": "revoked",
  "origin": "keyword",
  "evidence": "SAIR",
  "occurred_at": "2026-09-25T13:00:00.000Z",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live"
}

instagram.message.received

Um contato envia uma mensagem direta para a conta do Instagram conectada. X-Idempotency-Key: <mid>. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid), resource_id (id da mensagem na BotoZap), conversation_id, contact_id, direction, type, status, content e timestamp.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata do contato, quando conhecidos.
{
  "event": "instagram.message.received",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "inbound",
    "type": "text",
    "status": "received",
    "content": {
      "body": "Vocês entregam no sábado?"
    },
    "timestamp": "2026-09-25T13:00:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "metadata": {}
  }
}

instagram.message.reaction

O contato reage (ou retira a reação) a uma mensagem, ou a BotoZap envia uma reação pela API. X-Idempotency-Key: <mid>:reaction:<actor|self>:<epoch em ms>. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid), resource_id (id da mensagem na BotoZap), conversation_id, contact_id, direction, type, status, content e timestamp.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata do contato, quando conhecidos.
  • reaction: action (react/unreact), emoji, reaction, actor, direction e timestamp.
{
  "event": "instagram.message.reaction",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "outbound",
    "type": "text",
    "timestamp": "2026-09-25T13:00:00.000Z"
  },
  "reaction": {
    "action": "react",
    "emoji": "❤",
    "reaction": "love",
    "actor": "17841400000000000",
    "direction": "inbound",
    "timestamp": "2026-09-25T13:01:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "metadata": {}
  }
}

instagram.message.edited

O contato edita uma mensagem direta que enviou. A edição feita pela própria conta no app do Instagram atualiza a conversa, mas não gera evento. X-Idempotency-Key: <mid>:edited:<num_edit> (sem num_edit: <mid>:edited:<epoch em ms>). Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid da mensagem editada), direction (inbound), e, quando a mensagem já está na BotoZap: resource_id, conversation_id, contact_id, type, timestamp e content como ficou (texto novo em body, ou caption na mídia, e edited com count e at).
  • edit: text (o texto novo), num_edit (quantas vezes a mensagem já foi editada, quando a Meta informa) e timestamp da edição.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata, quando conhecidos.

Se a edição chega antes da mensagem original, o evento sai sem resource_id, conversation_id, type e content; a mensagem nasce já editada quando chegar. GET /api/v1/messages mostra o content atualizado.

{
  "event": "instagram.message.edited",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "inbound",
    "type": "text",
    "content": {
      "body": "Vocês entregam no domingo?",
      "edited": {
        "count": 1,
        "at": "2026-09-25T13:03:00+00:00"
      }
    },
    "timestamp": "2026-09-25T13:00:00+00:00"
  },
  "edit": {
    "text": "Vocês entregam no domingo?",
    "num_edit": 1,
    "timestamp": "2026-09-25T13:03:00+00:00"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "username": "maria.cliente",
    "metadata": {}
  }
}

instagram.message.revoked

O contato apaga (cancela o envio de) uma mensagem direta. A remoção feita pela própria conta no app do Instagram marca a mensagem, mas não gera evento. X-Idempotency-Key: <mid>:revoked. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid da mensagem apagada), direction (inbound), revoked_at e, quando a mensagem já está na BotoZap, resource_id, conversation_id, contact_id, type e timestamp. O conteúdo apagado não vai no evento.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata, quando conhecidos.

Se a remoção chega antes da mensagem original, o evento sai sem resource_id, conversation_id e type; a mensagem nasce já apagada quando chegar. Em GET /api/v1/messages ela traz revoked_at preenchido.

{
  "event": "instagram.message.revoked",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "inbound",
    "type": "text",
    "revoked_at": "2026-09-25T13:04:00+00:00",
    "timestamp": "2026-09-25T13:00:00+00:00"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "username": "maria.cliente",
    "metadata": {}
  }
}

instagram.comment.received

Alguém comenta num post, reel ou live da conta conectada. X-Idempotency-Key: <comment_id>. Também entra no stream GET /api/v1/events.

  • comment: id, text, parent_id (em resposta a outro comentário), live, media e timestamp.
  • from: { id, username } de quem comentou.
{
  "event": "instagram.comment.received",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "17900000000000001",
  "comment": {
    "id": "17900000000000001",
    "text": "Quero o preço!",
    "live": false,
    "media": {
      "id": "17800000000000001",
      "media_product_type": "FEED"
    },
    "timestamp": "2026-09-25T13:00:00.000Z"
  },
  "from": {
    "id": "17841400000000000",
    "username": "maria.cliente"
  }
}

instagram.comment.replied

Uma Regra de comentário publica a resposta pública ao comentário. X-Idempotency-Key: <comment_id>:replied. Também entra no stream GET /api/v1/events.

  • comment: id do comentário, reply_id, text da resposta e timestamp.
  • automation: { kind: instagram_comment_rule, rule_id, comment_id }.
{
  "event": "instagram.comment.replied",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "17900000000000001",
  "comment": {
    "id": "17900000000000001",
    "reply_id": "17900000000000002",
    "text": "Te chamei no direct!",
    "timestamp": "2026-09-25T13:00:05.000Z"
  },
  "automation": {
    "kind": "instagram_comment_rule",
    "rule_id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "comment_id": "17900000000000001"
  }
}

Categoria statuses

O status do WhatsApp vira um nome fino por valor: whatsapp.message.sent, whatsapp.message.delivered, whatsapp.message.read, whatsapp.message.played (o contato ouviu uma mensagem de voz) e whatsapp.message.failed. Todos têm os mesmos campos, e status repete o sufixo do nome. Só são emitidos para mensagens registradas na BotoZap (enviadas pela API, pelo painel, por transmissão ou por Régua); status de mensagens desconhecidas e os valores deleted e warning não geram evento. A Meta pode entregar os status fora de ordem: use a máquina de estados do seu lado, não a ordem de chegada.

whatsapp.message.sent

A Meta confirma que aceitou e enviou uma mensagem da BotoZap (API, painel, transmissão ou Régua). X-Idempotency-Key: <wamid>:sent. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • status: O status cru da Meta: sent, delivered, read, played ou failed (igual ao sufixo do nome do evento).
  • message_id: O wamid da mensagem enviada (igual a external_id).
  • recipient_id: O destinatário informado pela Meta; null quando ausente.
  • pricing: O objeto pricing da Meta (billable, pricing_model, category…) quando vier; senão null.
  • conversation: Só nos envios dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): conversation.id e, no sent, expiration_timestamp com o fim da janela. Ausente nos demais.
  • errors: A lista errors da Meta (code, title, message, error_data) — relevante em failed; senão null.

No stream, campos nulos são omitidos e message_resource_id aponta para a mensagem quando ela existe em GET /api/v1/messages.

{
  "event": "whatsapp.message.sent",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "status": "sent",
  "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "recipient_id": "5511988887777",
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "marketing",
    "type": "regular"
  },
  "errors": null
}

whatsapp.message.delivered

A Meta confirma a entrega no aparelho do contato. X-Idempotency-Key: <wamid>:delivered. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • status: O status cru da Meta: sent, delivered, read, played ou failed (igual ao sufixo do nome do evento).
  • message_id: O wamid da mensagem enviada (igual a external_id).
  • recipient_id: O destinatário informado pela Meta; null quando ausente.
  • pricing: O objeto pricing da Meta (billable, pricing_model, category…) quando vier; senão null.
  • conversation: Só nos envios dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): conversation.id e, no sent, expiration_timestamp com o fim da janela. Ausente nos demais.
  • errors: A lista errors da Meta (code, title, message, error_data) — relevante em failed; senão null.

No stream, campos nulos são omitidos e message_resource_id aponta para a mensagem quando ela existe em GET /api/v1/messages.

{
  "event": "whatsapp.message.delivered",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "status": "delivered",
  "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "recipient_id": "5511988887777",
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "marketing",
    "type": "regular"
  },
  "errors": null
}

whatsapp.message.read

A Meta informa que o contato leu a mensagem. X-Idempotency-Key: <wamid>:read. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • status: O status cru da Meta: sent, delivered, read, played ou failed (igual ao sufixo do nome do evento).
  • message_id: O wamid da mensagem enviada (igual a external_id).
  • recipient_id: O destinatário informado pela Meta; null quando ausente.
  • pricing: O objeto pricing da Meta (billable, pricing_model, category…) quando vier; senão null.
  • conversation: Só nos envios dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): conversation.id e, no sent, expiration_timestamp com o fim da janela. Ausente nos demais.
  • errors: A lista errors da Meta (code, title, message, error_data) — relevante em failed; senão null.

No stream, campos nulos são omitidos e message_resource_id aponta para a mensagem quando ela existe em GET /api/v1/messages.

{
  "event": "whatsapp.message.read",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "status": "read",
  "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "recipient_id": "5511988887777",
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "marketing",
    "type": "regular"
  },
  "errors": null
}

whatsapp.message.played

A Meta informa que o contato ouviu pela primeira vez uma mensagem de voz (áudio enviado com voice: true). A mensagem fica com status read e played_at preenchido. X-Idempotency-Key: <wamid>:played. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • status: O status cru da Meta: sent, delivered, read, played ou failed (igual ao sufixo do nome do evento).
  • message_id: O wamid da mensagem enviada (igual a external_id).
  • recipient_id: O destinatário informado pela Meta; null quando ausente.
  • pricing: O objeto pricing da Meta (billable, pricing_model, category…) quando vier; senão null.
  • conversation: Só nos envios dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): conversation.id e, no sent, expiration_timestamp com o fim da janela. Ausente nos demais.
  • errors: A lista errors da Meta (code, title, message, error_data) — relevante em failed; senão null.

No stream, campos nulos são omitidos e message_resource_id aponta para a mensagem quando ela existe em GET /api/v1/messages.

{
  "event": "whatsapp.message.played",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "status": "played",
  "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "recipient_id": "5511988887777",
  "pricing": null,
  "errors": null
}

whatsapp.message.failed

A Meta informa que a mensagem falhou depois de aceita. X-Idempotency-Key: <wamid>:failed. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • status: O status cru da Meta: sent, delivered, read, played ou failed (igual ao sufixo do nome do evento).
  • message_id: O wamid da mensagem enviada (igual a external_id).
  • recipient_id: O destinatário informado pela Meta; null quando ausente.
  • pricing: O objeto pricing da Meta (billable, pricing_model, category…) quando vier; senão null.
  • conversation: Só nos envios dentro da janela grátis do Free Entry Point (anúncio Click-to-WhatsApp): conversation.id e, no sent, expiration_timestamp com o fim da janela. Ausente nos demais.
  • errors: A lista errors da Meta (code, title, message, error_data) — relevante em failed; senão null.

No stream, campos nulos são omitidos e message_resource_id aponta para a mensagem quando ela existe em GET /api/v1/messages.

{
  "event": "whatsapp.message.failed",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "phone_number_id": "1279498075235551",
  "status": "failed",
  "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
  "recipient_id": "5511988887777",
  "pricing": null,
  "errors": [
    {
      "code": 131026,
      "title": "Message undeliverable",
      "message": "Message undeliverable",
      "error_data": {
        "details": "Message Undeliverable."
      }
    }
  ]
}

automation.journey_run.finished

Uma execução de Régua termina: completed, stopped (parada manual, cancelamento de agendamento, etc.) ou failed. Só para contatos de um número do WhatsApp. X-Idempotency-Key: journey_run:<run_id>:<status>. Também entra no stream GET /api/v1/events.

  • status: completed, stopped ou failed.
  • stop_reason: Motivo da parada (ex.: manual, appointment_cancelled); null quando não se aplica.
  • journey: { id } da Régua.
  • run: { id, occurrence_key, opportunity_id, demand_id } da execução.
  • contact: { id } do contato.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "automation.journey_run.finished",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "status": "completed",
  "stop_reason": null,
  "journey": {
    "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e"
  },
  "run": {
    "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "occurrence_key": "stage:6c1b9d2f-3e4a-4b5c-9d7e-8f9a0b1c2d3e",
    "opportunity_id": null,
    "demand_id": null
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
  }
}

instagram.message.sent

A Meta aceita uma mensagem enviada pela BotoZap (API, painel ou resposta privada de uma Regra de comentário). X-Idempotency-Key: <mid>:sent. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid), resource_id (id da mensagem na BotoZap), conversation_id, contact_id, direction, type, status, content e timestamp.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata do contato, quando conhecidos.
  • automation: Identifica a Regra autora e o passo quando disponível. Regra de mensagem: { rule_id, trigger }; Regra de comentário: kind, rule_id, comment_id e dados do passo.
{
  "event": "instagram.message.sent",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "outbound",
    "type": "text",
    "status": "sent",
    "content": {
      "body": "Seu pedido saiu para entrega."
    },
    "timestamp": "2026-09-25T13:00:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "username": "maria.cliente",
    "metadata": {}
  }
}

instagram.message.read

O contato lê uma mensagem enviada pela conta. X-Idempotency-Key: <mid>:read. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid), resource_id (id da mensagem na BotoZap), conversation_id, contact_id, direction, type, status, content e timestamp.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata do contato, quando conhecidos.
{
  "event": "instagram.message.read",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "outbound",
    "type": "text",
    "status": "read",
    "timestamp": "2026-09-25T13:02:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "metadata": {}
  }
}

instagram.message.failed

A Meta recusa uma mensagem enviada pela BotoZap. X-Idempotency-Key: <mid>:failed. Também entra no stream GET /api/v1/events.

  • message: id e external_id (o mid), resource_id (id da mensagem na BotoZap), conversation_id, contact_id, direction, type, status, content e timestamp.
  • contact: id, wa_id (o IGSID), username, profile_name e metadata do contato, quando conhecidos.
{
  "event": "instagram.message.failed",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
  "message": {
    "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "external_id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQx",
    "resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
    "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "direction": "outbound",
    "type": "text",
    "status": "failed",
    "content": {
      "body": "Seu pedido saiu para entrega."
    },
    "errors": {
      "code": 551,
      "message": "This person isn't available right now."
    },
    "timestamp": "2026-09-25T13:00:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "17841400000000000",
    "username": "maria.cliente",
    "metadata": {}
  }
}

instagram.message_rule.failed

Uma ação de Regra de mensagem falha, fica sem confirmação ou encontra o respondedor publicado alterado. X-Idempotency-Key: <run_id>:failed. Também entra no stream GET /api/v1/events.

  • run_id: UUID do Disparo idempotente pela mensagem recebida.
  • rule_id: UUID da Regra, preservado mesmo após sua exclusão.
  • trigger: keyword, story_reply, story_mention, share, ref ou ad.
  • message_id: UUID interno da mensagem recebida que originou o Disparo.
  • error: { code, message }; binding_changed impede encaminhamento ao novo respondedor.
{
  "event": "instagram.message_rule.failed",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "instagram",
  "channel_account": {
    "id": "0b6c9e2d-4a1f-4c8e-8d7b-5f3e2a1c9b80",
    "channel": "instagram",
    "display": "@lojaexemplo"
  },
  "run_id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
  "rule_id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8b",
  "trigger": "keyword",
  "message_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
  "error": {
    "code": "binding_changed",
    "message": "O agente ou roteador publicado no canal mudou; a Regra não encaminhou a mensagem."
  }
}

Categoria crm

crm.contact.stage_changed

A etapa do contato muda: kanban, PATCH /api/v1/contacts/{id}, regra do Instagram, agente de IA, regra da etapa (o contato mandou mensagem), transmissão (entrada em Não respondeu e promoção por resposta) ou etapa excluída. X-Idempotency-Key: crm:stage:<contact_id>:<transação>:<etapa anterior|none>><nova etapa|none>. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número do contato; ausente fora do WhatsApp.
  • contact: id, wa_id, user_id, username, phone e profile_name (campos nulos omitidos).
  • previous_stage / new_stage: { id, key, label } da etapa anterior e da nova; ausentes ao entrar no funil ou sair dele.
  • changed_by: manual (kanban, API ou regra do Instagram), auto (transmissão, resposta à transmissão, agente de IA ou regra da etapa) ou system (etapa limpa ou excluída).
  • occurred_at: Momento da mudança.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.contact.stage_changed",
  "phone_number_id": "1279498075235551",
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "5511988887777",
    "phone": "5511988887777",
    "profile_name": "Maria"
  },
  "previous_stage": {
    "id": "5b0a8c1e-2d3f-4a5b-8c6d-7e8f9a0b1c2d",
    "key": "negociando",
    "label": "Negociando"
  },
  "new_stage": {
    "id": "6c1b9d2f-3e4a-4b5c-9d7e-8f9a0b1c2d3e",
    "key": "fechou",
    "label": "Fechou"
  },
  "changed_by": "manual",
  "occurred_at": "2026-09-25T13:00:00.000Z",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live"
}

crm.opportunity.created

Uma oportunidade é criada (painel, API, MCP ou agente). X-Idempotency-Key: crm:opportunity:<id>:<version>. Também entra no stream GET /api/v1/events.

  • entity_type: Sempre opportunity.
  • entity_id: O id da entidade.
  • before_data: null na criação.
  • after_data: A linha inteira depois da gravação (inclui version, status e contact_id).
  • actor_user_id: Usuário do painel que fez a alteração; null via API/automação.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.opportunity.created",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "entity_type": "opportunity",
  "entity_id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
  "before_data": null,
  "after_data": {
    "id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "title": "Plano anual",
    "status": "open",
    "value_cents": 120000,
    "currency": "BRL",
    "version": 1
  },
  "actor_user_id": null
}

crm.opportunity.updated

Qualquer alteração gravada na oportunidade (cada gravação incrementa version e gera um evento). X-Idempotency-Key: crm:opportunity:<id>:<version>. Também entra no stream GET /api/v1/events.

  • entity_type: Sempre opportunity.
  • entity_id: O id da entidade.
  • before_data: A linha inteira antes da alteração.
  • after_data: A linha inteira depois da gravação (inclui version, status e contact_id).
  • actor_user_id: Usuário do painel que fez a alteração; null via API/automação.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.opportunity.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "entity_type": "opportunity",
  "entity_id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
  "before_data": {
    "version": 1,
    "status": "open"
  },
  "after_data": {
    "id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "title": "Plano anual",
    "status": "open",
    "value_cents": 120000,
    "currency": "BRL",
    "version": 2
  },
  "actor_user_id": null
}

crm.demand.created

Uma demanda é criada (painel, API, MCP ou agente). X-Idempotency-Key: crm:demand:<id>:<version>. Também entra no stream GET /api/v1/events.

  • entity_type: Sempre demand.
  • entity_id: O id da entidade.
  • before_data: null na criação.
  • after_data: A linha inteira depois da gravação (inclui version, status e contact_id).
  • actor_user_id: Usuário do painel que fez a alteração; null via API/automação.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.demand.created",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "entity_type": "demand",
  "entity_id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
  "before_data": null,
  "after_data": {
    "id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "title": "Troca de produto",
    "status": "open",
    "version": 1
  },
  "actor_user_id": null
}

crm.demand.updated

Qualquer alteração gravada na demanda (cada gravação incrementa version e gera um evento). X-Idempotency-Key: crm:demand:<id>:<version>. Também entra no stream GET /api/v1/events.

  • entity_type: Sempre demand.
  • entity_id: O id da entidade.
  • before_data: A linha inteira antes da alteração.
  • after_data: A linha inteira depois da gravação (inclui version, status e contact_id).
  • actor_user_id: Usuário do painel que fez a alteração; null via API/automação.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.demand.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "entity_type": "demand",
  "entity_id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
  "before_data": {
    "version": 1,
    "status": "open"
  },
  "after_data": {
    "id": "9f8e7d6c-5b4a-4392-8a1b-0c9d8e7f6a5b",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "title": "Troca de produto",
    "status": "in_progress",
    "version": 2
  },
  "actor_user_id": null
}

crm.appointment_created

Um agendamento é criado. X-Idempotency-Key: crm:appointment:<id>:created. Também entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número do contato; ausente fora do WhatsApp.
  • appointment: id, contact_id, scheduled_at, note e created_at (campos nulos omitidos).
  • contact: id, wa_id, phone e profile_name do contato.
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.appointment_created",
  "phone_number_id": "1279498075235551",
  "appointment": {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "scheduled_at": "2026-09-30T14:00:00.000Z",
    "created_at": "2026-09-25T13:00:00.000Z"
  },
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "5511988887777",
    "phone": "5511988887777",
    "profile_name": "Maria"
  },
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live"
}

crm.appointment_updated

Qualquer alteração gravada num agendamento: remarcação, confirmação, cancelamento, falta ou edição. X-Idempotency-Key: appointment:<id>:<revision>. Também entra no stream GET /api/v1/events.

  • appointment: A linha inteira do agendamento depois da alteração (inclui status, scheduled_at e revision).
  • before_data: A linha antes da alteração.
  • after_data: A linha depois da alteração (igual a appointment).
{
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "event": "crm.appointment_updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "appointment": {
    "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
    "contact_id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "status": "cancelled",
    "scheduled_at": "2026-09-30T14:00:00.000Z",
    "revision": 2
  },
  "before_data": {
    "status": "confirmed",
    "revision": 1
  },
  "after_data": {
    "status": "cancelled",
    "revision": 2
  }
}

Categoria account

whatsapp.account.updated

A Meta envia o field account_update para a WABA (restrição, violação de política, banimento, desbloqueio). X-Idempotency-Key: whatsapp.account.updated:<sha256 do payload normalizado>. Também entra no stream GET /api/v1/events.

  • waba_id: A WABA afetada.
  • account_event: O evento da Meta, ex.: ACCOUNT_RESTRICTION, ACCOUNT_VIOLATION, DISABLED_UPDATE.
  • ban_state: O estado de banimento conhecido; null quando não informado.
  • restrictions: Lista de { restriction_type, expiration }; lista vazia = sem restrições; null quando não informado.
  • violation_type: Só em ACCOUNT_VIOLATION, ex.: SPAM.
  • disconnection_reason: Só em PARTNER_REMOVED de número em coexistência, quando a Meta informa: USER_RE_REGISTERED, CHANGE_NUMBER, BUSINESS_DOWNGRADE, PRIMARY_INACTIVITY, COMPANION_INACTIVITY ou ACCOUNT_DISCONNECTED.
  • disconnection_initiated_by: Junto do motivo: USER (o dono, no app) ou SYSTEM (a Meta).
  • occurred_at: Horário do evento na Meta; null quando ilegível.
{
  "event": "whatsapp.account.updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "account_event": "ACCOUNT_RESTRICTION",
  "ban_state": null,
  "restrictions": [
    {
      "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
      "expiration": "2026-08-31T00:00:00.000Z"
    }
  ],
  "occurred_at": "2026-08-27T12:00:00.000Z"
}

whatsapp.phone_number.quality_updated

A Meta envia o field phone_number_quality_update (apesar do nome, informa o tier de limite de mensagens do número). X-Idempotency-Key: whatsapp.phone_number.quality_updated:<sha256 do payload normalizado>. Também entra no stream GET /api/v1/events.

  • waba_id: A WABA do número.
  • phone_number_id: O phone_number_id da Meta do número afetado.
  • display_phone_number: O número como a Meta exibe.
  • messaging_limit_tier: O tier de limite, ex.: TIER_2K.
  • occurred_at: Horário do evento na Meta; null quando ilegível.
{
  "event": "whatsapp.phone_number.quality_updated",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "phone_number_id": "1279498075235551",
  "display_phone_number": "+1 555-078-3881",
  "messaging_limit_tier": "TIER_2K",
  "occurred_at": "2026-08-27T12:00:00.000Z"
}

whatsapp.phone_number.connected

O Embedded Signup termina e o número fica conectado à BotoZap, pelo Link de conexão ou pelo painel, em conexão dedicada ou coexistência. X-Idempotency-Key: whatsapp.phone_number.connected:<setup_link_id>:<phone_number_id>. Também entra no stream GET /api/v1/events.

  • waba_id: A WABA do número.
  • phone_number_id: O phone_number_id da Meta do número conectado.
  • display_phone_number: O número como a Meta exibe; null quando a Meta ainda não informou.
  • connection_mode: dedicated (número só na API) ou coexistence (o mesmo número segue no app WhatsApp Business).
  • setup_link_id: O Link de conexão usado. Uma nova conexão do mesmo número por outro link gera outro Evento; repetir o mesmo link, não.
  • occurred_at: Quando a BotoZap concluiu a conexão.
{
  "event": "whatsapp.phone_number.connected",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "waba_id": "4207187232868022",
  "phone_number_id": "1279498075235551",
  "display_phone_number": "+55 11 3333-4444",
  "connection_mode": "coexistence",
  "setup_link_id": "5b2f7c1e-8a4d-4e3f-9b6a-1c2d3e4f5a60",
  "occurred_at": "2026-09-30T13:05:00.000Z"
}

Categoria app_messages (opt-in)

Num número em coexistência (o mesmo número no app WhatsApp Business e na API), o que a equipe faz pelo app chega nesta categoria, com source app: whatsapp.message.echo quando alguém envia uma mensagem, whatsapp.message.edited quando edita e whatsapp.message.revoked quando apaga. Ela é opt-in para que um agente assinado em messages não leia a fala da equipe como fala do contato: marque "Mensagens do app (coexistência)" no painel ou inclua app_messages em events. Se o seu agente responde sozinho, use o whatsapp.message.echo para saber que um humano assumiu a conversa. Esses eventos não entram no stream GET /api/v1/events, que não filtra por tipo. Uma reentrega do eco pela Meta não cria um segundo evento; como em toda entrega, uma duplicata rara do mesmo POST é possível, então deduplique pelo X-Idempotency-Key.

whatsapp.message.echo

Num número em coexistência, alguém da equipe envia uma mensagem pelo app WhatsApp Business (celular ou dispositivo vinculado), fora da BotoZap. Use para saber que um humano respondeu e segurar o seu agente. Envios pela API, pelo painel, por transmissão ou por Régua não geram este evento; eles aparecem nos eventos de status. X-Idempotency-Key: <wamid>. Não entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número que enviou.
  • source: Sempre app: a mensagem saiu do app WhatsApp Business, não da BotoZap.
  • message: O objeto de eco cru da Meta (id, from, to, timestamp, type e o conteúdo do tipo), mais external_id. Em mídia, o id do objeto (ex.: image.id) é o media_id de GET /api/v1/media/{id}.
  • message_resource_id: O id da mensagem na BotoZap (o mesmo de GET /api/v1/messages).
  • conversation_id: A conversa da BotoZap onde a mensagem entrou.
  • contact: O destinatário: id do contato, wa_id, user_id, username, phone e metadata. profile_name vem null (o eco não traz o nome).

Não entra no stream: GET /api/v1/events não tem filtro por tipo, e quem lê o stream como fila de mensagens do contato passaria a ver a fala da equipe. A mensagem continua em GET /api/v1/messages com source app.

{
  "event": "whatsapp.message.echo",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
  "phone_number_id": "1279498075235551",
  "source": "app",
  "message": {
    "from": "551133334444",
    "to": "5511988887777",
    "id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
    "timestamp": "1790341260",
    "type": "text",
    "text": {
      "body": "Oi Maria, aqui é a Ana. Seu pedido sai hoje."
    },
    "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA"
  },
  "message_resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
  "conversation_id": "c7d8e9f0-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
  "contact": {
    "id": "a3c1e2f4-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "wa_id": "5511988887777",
    "user_id": null,
    "username": null,
    "phone": "5511988887777",
    "profile_name": null,
    "metadata": {}
  }
}

whatsapp.message.edited

Num número em coexistência, alguém da equipe edita pelo app WhatsApp Business uma mensagem já enviada. A edição feita pelo contato não gera evento. X-Idempotency-Key: <wamid do eco>:edited. Não entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número.
  • source: Sempre app.
  • original_message_id: O wamid da mensagem editada ou apagada (igual a external_id). Pode ser de uma mensagem que ainda não chegou à BotoZap; ela recebe a alteração quando chegar.
  • message: O eco cru da Meta: id (o wamid da própria edição, não da original), to, timestamp, type edit e edit com original_message_id e a mensagem nova em edit.message.
  • contact: O destinatário: wa_id, user_id, username e phone; null quando o eco não o identifica.

Não entra no stream, como o whatsapp.message.echo. O efeito aparece na própria mensagem: content atualizado na edição e revoked_at na remoção (GET /api/v1/messages).

{
  "event": "whatsapp.message.edited",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
  "phone_number_id": "1279498075235551",
  "source": "app",
  "original_message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
  "message": {
    "from": "551133334444",
    "to": "5511988887777",
    "id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5RURJVA",
    "timestamp": "1790341320",
    "type": "edit",
    "edit": {
      "original_message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
      "message": {
        "type": "text",
        "text": {
          "body": "Oi Maria, aqui é a Ana. Seu pedido sai amanhã."
        }
      }
    }
  },
  "contact": {
    "wa_id": "5511988887777",
    "user_id": null,
    "username": null,
    "phone": "5511988887777"
  }
}

whatsapp.message.revoked

Num número em coexistência, alguém da equipe apaga pelo app WhatsApp Business (apagar para todos) uma mensagem já enviada. A remoção feita pelo contato não gera evento. X-Idempotency-Key: <wamid do eco>:revoked. Não entra no stream GET /api/v1/events.

  • phone_number_id: O phone_number_id da Meta do número.
  • source: Sempre app.
  • original_message_id: O wamid da mensagem editada ou apagada (igual a external_id). Pode ser de uma mensagem que ainda não chegou à BotoZap; ela recebe a alteração quando chegar.
  • message: O eco cru da Meta: id (o wamid da própria remoção, não da original), to, timestamp, type revoke e revoke.original_message_id.
  • contact: O destinatário: wa_id, user_id, username e phone; null quando o eco não o identifica.

Não entra no stream, como o whatsapp.message.echo. O efeito aparece na própria mensagem: content atualizado na edição e revoked_at na remoção (GET /api/v1/messages).

{
  "event": "whatsapp.message.revoked",
  "customer_id": "4f5f0b1e-3ca6-4fd2-9c2f-3f3a5f90d2a1",
  "environment": "live",
  "channel": "whatsapp",
  "channel_account": {
    "id": "8d1f3c2a-6b7e-4f1a-9c3d-2e5b7a9c1d40",
    "channel": "whatsapp",
    "display": "+55 11 3333-4444"
  },
  "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
  "phone_number_id": "1279498075235551",
  "source": "app",
  "original_message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA",
  "message": {
    "from": "551133334444",
    "to": "5511988887777",
    "id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5UkVWTw",
    "timestamp": "1790341320",
    "type": "revoke",
    "revoke": {
      "original_message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABEYEjQ5QUZQUA"
    }
  },
  "contact": {
    "wa_id": "5511988887777",
    "user_id": null,
    "username": null,
    "phone": "5511988887777"
  }
}

Evento de teste

webhook.test

POST /api/v1/webhooks/{id}/test ou o botão Testar e ativar do painel. X-Idempotency-Key: test:<endpoint_id>. Não entra no stream GET /api/v1/events.

  • message: Texto fixo: Evento de teste do BotoZap.
  • sent_at: Momento do envio.
{
  "event": "webhook.test",
  "customer_id": null,
  "environment": null,
  "message": "Evento de teste do BotoZap.",
  "sent_at": "2026-09-25T13:00:00.000Z"
}

A chave é a mesma em todos os testes do Endpoint; não deduplique testes por ela. O teste fica registrado em GET /api/v1/webhook_deliveries com event_type=webhook.test.

O que não gera evento

  • Aprovação, rejeição ou pausa de template. A BotoZap atualiza o status do template, mas não emite evento. Consulte GET /api/v1/templates.
  • Edição e remoção feitas pelo contato no WhatsApp. Quando o contato edita ou apaga uma mensagem dele no WhatsApp, a BotoZap aplica a mudança na mensagem (content ou revoked_at em GET /api/v1/messages), sem evento. As feitas pela equipe no app WhatsApp Business geram whatsapp.message.edited e whatsapp.message.revoked (categoria opt-in app_messages). No Instagram, a edição e a remoção feitas pelo contato geram instagram.message.edited e instagram.message.revoked (categoria messages); as feitas pela própria conta no app do Instagram só atualizam a mensagem. Os dois Eventos chegam pelo webhook e por events.list do SDK como qualquer outro, e o SDK tipa content.edited e revoked_at da mensagem.
  • Histórico importado da coexistência. As conversas antigas que o app envia ao conectar o número (source history) entram na conversa sem gerar whatsapp.message.received nem whatsapp.message.echo. Se o dono deixou o compartilhamento do histórico desligado no app, nada é importado e o aviso aparece no painel, em Canais.
  • Desconexão de número. Só a conexão gera evento (whatsapp.phone_number.connected). Quando a Meta informa que o acesso à WABA acabou, chega whatsapp.account.updated com o account_event da Meta; desconectar a WABA pelo painel não gera evento.
  • Status de mensagem desconhecida. Status cujo wamid não corresponde a uma mensagem registrada na BotoZap são descartados.
  • Edições de CRM fora dos eventos listados. Criar ou editar o contato (nome, campos personalizados, notas), configurar as etapas do funil e excluir o contato (junto com as oportunidades, demandas e agendamentos dele) não geram evento. Criar ou alterar oportunidade e demanda gera crm.opportunity.*/crm.demand.*; mudar a etapa do contato gera crm.contact.stage_changed.
  • Início e passos de uma Régua. Só o término da execução gera automation.journey_run.finished.

Sandbox e produção no mesmo Endpoint

Endpoints de webhook pertencem à Conta, não ao ambiente. Eventos gerados pelo número Sandbox e pelos números de produção chegam ao mesmo Endpoint; separe-os pelo campo environment do corpo: sandbox para o que nasceu no Sandbox, live para produção. Eventos da Conta sem canal, como os de saúde da WABA (account), são sempre live: o Sandbox não os simula. O stream GET /api/v1/events já é separado por ambiente e traz o mesmo environment em cada item (veja abaixo).

Stream durável: GET /api/v1/events

Além do POST no seu Endpoint, a BotoZap grava os eventos num log append-only por Conta e ambiente. O stream não depende de Endpoint cadastrado nem de assinatura de categoria: ele recebe tudo o que a tabela acima marca como "sim", e é a forma de recuperar um evento que o seu Endpoint perdeu (queda, pausa por saúde ou retenção vencida).

  • Escopo events:read. A chave Sandbox lê o stream do Sandbox; a chave live lê o de produção. O cursor é independente em cada ambiente.
  • after: inteiro não negativo, exclusivo; omitido vale 0 (desde o mais antigo guardado). Qualquer outro valor responde 422 invalid_cursor.
  • limit: padrão 20, máximo 100. Valor acima do máximo é reduzido a 100; valor inválido volta ao padrão.
  • A ordem é ascendente por cursor, que cresce por Conta e ambiente: enquanto os eventos estão guardados, repetir a mesma chamada devolve a mesma página, e seguir paging.cursor percorre tudo o que está guardado, sem pular evento.
curl "https://botozap.com.br/api/v1/events?after=41&limit=50" \
  -H "X-API-Key: $BOTOZAP_KEY"
{
  "data": [
    {
      "id": "0e6f1c2a-9b3d-4e5f-8a7b-6c5d4e3f2a1b",
      "cursor": "42",
      "type": "whatsapp.message.delivered",
      "environment": "live",
      "message_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
      "external_id": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYIDNBMjE",
      "message_resource_id": "e1f2a3b4-c5d6-4e7f-8a9b-1c2d3e4f5a6b",
      "occurred_at": "2026-09-25T13:00:03.000Z",
      "created_at": "2026-09-25T13:00:04.120Z",
      "data": { "event": "whatsapp.message.delivered", "status": "delivered", "…": "…" }
    }
  ],
  "paging": { "cursor": "42", "next": "42", "has_more": true }
}
CampoSignificado
idUUID do evento no stream; estável, use para deduplicar leituras.
cursorPosição do evento, como string de inteiro.
typeO nome fino do evento (o mesmo do webhook).
environmentlive ou sandbox: o ambiente do evento, o mesmo da chave que leu o stream e o mesmo campo do corpo do webhook.
message_idO wamid quando o evento é de uma mensagem do WhatsApp; null nos demais.
external_idO identificador da mensagem no canal; null em eventos sem mensagem.
message_resource_idO id da mensagem na BotoZap (o mesmo de GET /api/v1/messages), quando existe.
occurred_atQuando o fato aconteceu (horário da Meta quando disponível).
created_atQuando a BotoZap gravou o evento.
dataO payload do evento; veja as diferenças por tipo acima.
paging.cursorCursor do último item da página (ou o próprio after numa página vazia). Persista-o.
paging.next / paging.has_morenext repete o cursor quando há mais itens; null quando has_more é false.

Retenção: cada evento fica 90 dias no stream, contados de quando a BotoZap o gravou (created_at), e depois sai na limpeza diária. Leia o stream com intervalo menor que esse: um after anterior ao evento mais antigo guardado continua dele, sem erro. Os eventos também saem junto com a exclusão da Conta ou com a exclusão dos dados de uma Conta de canal. Excluir um contato (DELETE /api/v1/contacts/{id}) apaga os eventos dele: os das mensagens dele e os que trazem o contato no payload. Excluir uma conversa (DELETE /api/v1/conversations/{id}) apaga os eventos das mensagens dela. Esses eventos deixam de aparecer no stream, e os cursores dos demais não mudam.

Stream e webhooks juntos

O mesmo fato pode chegar pelos dois caminhos, e as chaves são diferentes: no webhook, deduplique por X-Idempotency-Key; no stream, por id. Um padrão seguro é usar o webhook para reagir em tempo real e rodar, periodicamente ou depois de uma queda, a leitura do stream a partir do último paging.cursor salvo, processando só o que ainda não foi visto. O stream não depende da saúde do Endpoint: um Endpoint em paused ou unverified não impede a gravação dos eventos. O webhook.test nunca entra no stream.