Event Types

Zavu sends webhook events for message lifecycle stages. There are several categories:

Event Structure

All events follow this structure:

JSONCopy
{
  "id": "evt_1705312200000_abc123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    // Event-specific payload
  }
}

---

Inbound Events

conversation.new

Triggered when a new contact sends you their first message. This is useful for tracking new leads or customers.

JSONCopy
{
  "id": "evt_1705312200000_new123",
  "type": "conversation.new",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "phoneNumber": "+14155551234",
    "channel": "whatsapp",
    "firstMessageId": "msg_xyz789",
    "firstMessageText": "Hi, I'm interested in your product",
    "profileName": "John Doe"
  }
}

Data Fields

---

message.inbound

Triggered when a customer sends you a message on any channel: SMS, WhatsApp, Telegram, Instagram, Messenger or email. This includes text, images, videos, audio, documents, stickers, locations, and contacts.

Text Message Example

JSONCopy
{
  "id": "evt_1705312200000_abc123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_xyz789",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Hi, I have a question about my order",
    "profileName": "John Doe",
    "providerTimestamp": 1705312199000
  }
}

Username Contact (BSUID) Example

WhatsApp users can adopt a username and hide their phone number. Their messages arrive through the same event, but from carries a business-scoped user ID (BSUID) instead of an E.164 phone number:

JSONCopy
{
  "id": "evt_1705312200000_bsu123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_bsu789",
    "conversationId": "js723987cyghwqxxaxcf590qd18axd95",
    "contactId": "jd7x2k3m4n5p6q7r8s9t0abc",
    "whatsapp": { "bsuid": "US.13491208655302741918", "username": "sheena" },
    "from": "US.13491208655302741918",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Hi, I saw your listing",
    "profileName": "Sheena",
    "providerTimestamp": 1705312199000
  }
}

Image Message Example

JSONCopy
{
  "id": "evt_1705312200000_img456",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_img789",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "image",
    "text": "Check out this product",
    "content": {
      "mediaId": "1234567890",
      "mimeType": "image/jpeg"
    },
    "profileName": "John Doe"
  }
}

Location Message Example

JSONCopy
{
  "id": "evt_1705312200000_loc789",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_loc123",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "location",
    "text": "",
    "content": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "San Francisco",
      "address": "San Francisco, CA, USA"
    },
    "profileName": "John Doe"
  }
}

Contact Message Example

JSONCopy
{
  "id": "evt_1705312200000_cnt456",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_cnt789",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "contact",
    "text": "",
    "content": {
      "contacts": [
        {
          "name": "Jane Smith",
          "phones": [
            { "phone": "+14155559999", "type": "MOBILE" }
          ],
          "emails": [
            { "email": "jane@example.com", "type": "WORK" }
          ]
        }
      ]
    },
    "profileName": "John Doe"
  }
}

Interactive Reply Example

When a user clicks a button or selects a list item that you sent, you'll receive the reply with the button/item ID:

JSONCopy
{
  "id": "evt_1705312200000_int123",
  "type": "message.inbound",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_int456",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Yes, I'm interested",
    "content": {
      "interactiveReply": {
        "type": "button_reply",
        "id": "btn_interested",
        "title": "Yes, I'm interested"
      }
    },
    "profileName": "John Doe"
  }
}

Reply / Quote Context Example

When a customer replies to (quotes) an earlier message, the content object carries the reply context so you can thread the conversation. When the quoted message exists in Zavu, you get its Zavu replyToMessageId, a text snippet, and its type:

JSONCopy
{
  "id": "evt_1705312300000_rep123",
  "type": "message.inbound",
  "timestamp": 1705312300000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_reply999",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Yes, that order is correct",
    "content": {
      "replyToMessageId": "msg_original123",
      "replyToProviderMessageId": "wamid.HBgL...ORIGINAL123",
      "replyToFrom": "+13125559876",
      "replyToText": "Your order #ORD-12345 has shipped.",
      "replyToMessageType": "text"
    },
    "profileName": "John Doe"
  }
}

If the quoted message is not stored in Zavu (e.g. an old or unknown message), the context degrades gracefully — you still get the provider ID and sender, but replyToMessageId, replyToText, and replyToMessageType are omitted:

JSONCopy
{
  "id": "evt_1705312400000_rep456",
  "type": "message.inbound",
  "timestamp": 1705312400000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_reply888",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "messageType": "text",
    "text": "Replying to an old message",
    "content": {
      "replyToProviderMessageId": "wamid.HBgL...OLD_UNKNOWN",
      "replyToFrom": "+13125559876"
    },
    "profileName": "John Doe"
  }
}

Data Fields

Example Handler

TypeScriptCopy
async function handleInboundMessage(data) {
  const { from, text, channel } = data;

  // Store the message
  await db.messages.create({
    from,
    text,
    channel,
    receivedAt: new Date()
  });

  // Send auto-reply if needed
  if (text.toLowerCase().includes("help")) {
    await zavu.messages.send({
      to: from,
      text: "Thanks for reaching out! A support agent will contact you shortly."
    });
  }
}

---

message.unsupported

Triggered when a customer sends a message type that cannot be fully represented on the channel. On WhatsApp Cloud API, this includes polls, deleted messages, ephemeral messages, and some third-party stickers.

JSONCopy
{
  "id": "evt_1705312200000_unsup123",
  "type": "message.unsupported",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_xyz789",
    "from": "+14155551234",
    "to": "+13125559876",
    "channel": "whatsapp",
    "timestamp": 1705312200000
  }
}

Data Fields

Example Handler

TypeScriptCopy
async function handleUnsupportedMessage(data) {
  const { from, messageId } = data;

  // Log unsupported message for analytics
  await db.unsupportedMessages.create({
    messageId,
    from,
    receivedAt: new Date()
  });

  // Optionally notify the customer
  await zavu.messages.send({
    to: from,
    text: "We received your message, but this message type is not supported. Please send a text message instead."
  });
}

---

message.reaction

Triggered when a customer reacts to a message with an emoji (WhatsApp only). This event is sent when a reaction is added or removed from a message.

JSONCopy
{
  "id": "evt_1705312200000_react123",
  "type": "message.reaction",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_xyz789",
    "providerMessageId": "wamid.HBgLMTU1NT...",
    "reaction": {
      "emoji": "👍",
      "from": "+14155551234",
      "timestamp": 1705312200000,
      "action": "added"
    }
  }
}

Data Fields

Example Handler

TypeScriptPythonRubyGoPHPCopy
async function handleReaction(data) {
  const { messageId, reaction } = data;
  const { emoji, from, action } = reaction;

  if (action === "added") {
    // Store the reaction
    await db.reactions.create({
      messageId,
      emoji,
      from,
      createdAt: new Date()
    });

    // Track engagement metrics
    await analytics.track("message_reaction", {
      messageId,
      emoji,
    });
  } else if (action === "removed") {
    // Remove the reaction
    await db.reactions.delete({
      messageId,
      from,
    });
  }
}

---

contact.identity_linked

Fired when a WhatsApp contact known by its business-scoped user ID (BSUID) is tied to a phone number, a contact known by phone receives a BSUID, or a contact changes their number. It fires once per link, not on every message. Subscribe to it on the sender's webhook.

JSONCopy
{
  "id": "evt_1705312300000_def456",
  "type": "contact.identity_linked",
  "timestamp": 1705312300000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "contactId": "jd7x2k3m4n5p6q7r8s9t0abc",
    "bsuid": "US.13491208655302741918",
    "phoneNumber": "+13125551234",
    "reason": "provider_reported"
  }
}

Data Fields

After this event, from on message.inbound is still the BSUID whenever WhatsApp leaves the phone number out of a message. Use contactId to recognise the person. See Usernames & BSUIDs.

---

Outbound Events

These events help you track the delivery status of messages you send. Subscribe to these if you need delivery confirmations or failure notifications.

message.queued

Triggered when your message is accepted and queued for delivery.

JSONCopy
{
  "id": "evt_1705312200000_abc456",
  "type": "message.queued",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_abc123",
    "to": "+14155551234",
    "channel": "sms",
    "status": "queued"
  }
}

Data Fields

---

message.sent

Triggered when your outbound message is successfully accepted by the carrier or Meta. This confirms the message has left Zavu's systems and is being processed by the provider.

JSONCopy
{
  "id": "evt_1705312200000_def456",
  "type": "message.sent",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_abc123",
    "to": "+14155551234",
    "channel": "sms",
    "status": "sent"
  }
}

Data Fields

WhatsApp Business App Echo (Coexistence)

When using WhatsApp in coexistence mode, messages sent directly from the WhatsApp Business App also trigger message.sent events. These events include the full message content so you can sync outbound messages that were not sent through the Zavu API.

You can distinguish these from regular status updates by checking the source field.

JSONCopy
{
  "id": "evt_1705312200000_echo456",
  "type": "message.sent",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_echo789",
    "from": "+13125559876",
    "to": "+14155551234",
    "channel": "whatsapp",
    "messageType": "text",
    "status": "delivered",
    "text": "Hi! Thanks for reaching out. We'll get back to you shortly.",
    "source": "whatsapp_business_app",
    "direction": "outbound"
  }
}

Additional Fields (Coexistence Only)

---

message.delivered

Triggered when your message is confirmed delivered to the recipient's device.

JSONCopy
{
  "id": "evt_1705312200000_ghi789",
  "type": "message.delivered",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_abc123",
    "to": "+14155551234",
    "channel": "whatsapp",
    "status": "delivered"
  }
}

Data Fields

---

message.failed

Triggered when message delivery fails.

JSONCopy
{
  "id": "evt_1705312200000_jkl012",
  "type": "message.failed",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "messageId": "msg_abc123",
    "to": "+14155551234",
    "channel": "sms",
    "status": "failed",
    "errorCode": "30003",
    "errorMessage": "Unreachable destination handset"
  }
}

Data Fields

Common Error Codes

Example Handler

TypeScriptPythonRubyGoPHPCopy
async function handleDeliveryFailure(data) {
  const { messageId, errorCode, errorMessage } = data;

  // Log the failure
  await db.messages.update(messageId, {
    status: "failed",
    errorCode,
    errorMessage,
    failedAt: new Date()
  });

  // Alert your team for critical failures
  if (["30007", "21610"].includes(errorCode)) {
    await alertTeam({
      type: "message_blocked",
      messageId,
      reason: errorMessage
    });
  }
}

---

Template Events

template.status_changed

Triggered when a WhatsApp template's approval status changes. This is useful for tracking when templates are approved, rejected, or disabled by Meta.

JSONCopy
{
  "id": "evt_1705312200000_tmpl123",
  "type": "template.status_changed",
  "timestamp": 1705312200000,
  "senderId": "snd_abc123",
  "projectId": "prj_xyz789",
  "data": {
    "templateId": "tmpl_xyz789",
    "templateName": "order_confirmation",
    "language": "en",
    "previousStatus": "pending",
    "currentStatus": "approved",
    "rejectionReason": null
  }
}

Data Fields

Status Values

Example Handler

TypeScriptPythonRubyGoPHPCopy
async function handleTemplateStatusChange(data) {
  const { templateId, templateName, currentStatus, rejectionReason } = data;

  // Update template status in your database
  await db.templates.update(templateId, {
    status: currentStatus,
    rejectionReason,
    updatedAt: new Date()
  });

  if (currentStatus === "approved") {
    await notifyTeam({
      message: `Template "${templateName}" has been approved!`,
      type: "success"
    });
  } else if (currentStatus === "rejected") {
    await notifyTeam({
      message: `Template "${templateName}" was rejected: ${rejectionReason}`,
      type: "error"
    });
  }
}

---

Partner Invitation Events

invitation.status_changed

Triggered when a partner invitation changes status. Use it to follow a client through onboarding without polling.

It is delivered to the project webhook of the project that created the invitation. If you create invitations with a sub-account's API key, configure the webhook on that sub-account: a parent project does not receive its sub-accounts' events. If that project's default sender has a webhook subscribed to this event, it receives a copy too, with a top-level senderId.

JSONCopy
{
  "id": "evt_1705312200000_inv123",
  "type": "invitation.status_changed",
  "timestamp": 1705312200000,
  "projectId": "prj_xyz789",
  "data": {
    "invitationId": "inv_xyz789",
    "clientName": "Acme Corp",
    "clientEmail": "contact@acme.com",
    "connectionType": "whatsapp_waba",
    "previousStatus": "in_progress",
    "currentStatus": "completed",
    "senderId": "snd_newclient123",
    "wabaAccountId": "waba_abc456",
    "connectedAccount": {
      "channel": "whatsapp",
      "id": "109876543210",
      "name": "Acme Corp"
    }
  }
}

Data Fields

When It Fires

A change to the same status sends nothing, so retrying a step never produces a duplicate event.

Example Handler

TypeScriptPythonRubyGoPHPCopy
async function handleInvitationStatusChanged(data) {
  const { invitationId, clientName, currentStatus, senderId } = data;

  if (currentStatus === "completed") {
    // Client successfully onboarded
    await notifyTeam({
      message: `${clientName} has connected their WhatsApp!`,
      senderId,
    });

    // Create templates for the new client
    await createDefaultTemplates(senderId);
  } else if (currentStatus === "in_progress") {
    // Client started the process
    console.log(`${clientName} is completing WhatsApp setup`);
  } else if (currentStatus === "failed") {
    // The link still works: the client can retry it
    console.log(`${clientName} did not finish: ${data.failureReason}`);
  }
}

---

Broadcast Events

broadcast.status_changed

Triggered when a broadcast changes status. This is a project-level event — configure it in your project webhook settings.

JSONCopy
{
  "id": "evt_1705312200000_brd123",
  "type": "broadcast.status_changed",
  "timestamp": 1705312200000,
  "projectId": "prj_xyz789",
  "data": {
    "broadcastId": "brd_abc123",
    "name": "Black Friday Campaign",
    "status": "approved",
    "previousStatus": "pending_review",
    "channel": "sms",
    "totalContacts": 5000
  }
}

Data Fields

Status Flow

CodeCopy
draft → pending_review → approved → sending → completed
              ↓
          rejected → escalated → rejected_final
              ↑
         (edit + retry)

Example Handler

TypeScriptPythonCopy
async function handleBroadcastStatusChanged(data) {
  const { broadcastId, name, status, previousStatus } = data;

  switch (status) {
    case "approved":
      console.log(`Broadcast "${name}" approved — will begin sending`);
      break;
    case "rejected":
      console.log(`Broadcast "${name}" rejected — edit content and retry`);
      await notifyTeam({ message: `Broadcast rejected: ${name}` });
      break;
    case "completed":
      console.log(`Broadcast "${name}" completed!`);
      await generateReport(broadcastId);
      break;
    case "cancelled":
      console.log(`Broadcast "${name}" was cancelled`);
      break;
  }
}

---

Best Practices

Idempotency

Webhook deliveries may be retried, so your handler should be idempotent:

JavaScriptCopy
async function handleEvent(event) {
  // Check if we've already processed this event
  const existing = await db.processedEvents.find(event.id);
  if (existing) {
    console.log(`Event ${event.id} already processed, skipping`);
    return;
  }

  // Process the event
  await processEventLogic(event);

  // Mark as processed
  await db.processedEvents.create({ eventId: event.id });
}

Error Handling

Always wrap your handlers in try-catch to prevent unhandled exceptions:

JavaScriptCopy
app.post('/webhooks/zavu', async (req, res) => {
  try {
    await handleEvent(req.body);
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook handling error:', error);
    // Return 200 to prevent retries if the error is not transient
    res.status(200).send('OK');
  }
});

Next Steps

• Security - Verify webhook signatures
• Webhooks - Configure your endpoints