> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stories & Status

> Receive WhatsApp status/story updates from contacts as opt-in message.status webhook events.

When a contact posts a WhatsApp **status** (a story), the linked number receives it. Zavu delivers it as a dedicated **`message.status`** webhook event — **not** as an inbound message. It never enters the inbox and never creates a conversation, so it can't flood your threads. You only receive it if you explicitly subscribe.

<Note>
  `message.status` is currently emitted for the **WhatsApp Alternative** channel only. It is **opt-in**: add `message.status` to your sender's `webhookEvents`. Media bytes are not downloaded — only metadata and any text/caption is delivered.
</Note>

## Subscribe

Add `message.status` to the sender's subscribed events (via the API or the dashboard):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.zavu.dev/v1/senders/sender_12345 \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "webhookUrl": "https://api.example.com/webhooks/zavu",
      "webhookEvents": ["message.inbound", "message.status"]
    }'
  ```

  ```typescript TypeScript theme={null}
  await zavu.senders.update("sender_12345", {
    webhookUrl: "https://api.example.com/webhooks/zavu",
    webhookEvents: ["message.inbound", "message.status"],
  });
  ```
</CodeGroup>

<Warning>
  If a sender is not subscribed to `message.status`, story updates are silently dropped — they are never delivered by default. This keeps existing integrations unaffected.
</Warning>

## The `message.status` event

```json message.status theme={null}
{
  "id": "evt_1736850000000_abc123",
  "type": "message.status",
  "timestamp": 1736850000000,
  "senderId": "sender_12345",
  "projectId": "proj_abc",
  "data": {
    "messageId": "jx77...",
    "channel": "whatsapp_alt",
    "from": "+14155551234",
    "to": "+13125551212",
    "messageType": "image",
    "text": "At the beach",
    "mimetype": "image/jpeg",
    "providerTimestamp": 1736849999000
  }
}
```

### Fields on `data`

| Field               | Present       | Description                                             |
| ------------------- | ------------- | ------------------------------------------------------- |
| `from`              | always        | The contact who posted the status, in E.164.            |
| `to`                | always        | Your linked number.                                     |
| `channel`           | always        | `whatsapp_alt`.                                         |
| `messageType`       | always        | The story type: `text`, `image`, `video`, or `audio`.   |
| `text`              | when present  | The caption, or the text of a text story.               |
| `mimetype`          | media stories | MIME type of the story media (bytes are not included).  |
| `providerTimestamp` | when known    | When WhatsApp originally received the status (Unix ms). |

## Handling it

<CodeGroup>
  ```typescript TypeScript theme={null}
  app.post("/webhooks/zavu", (req, res) => {
    const { type, data } = req.body;
    if (type === "message.status") {
      console.log(`${data.from} posted a ${data.messageType} story${data.text ? `: ${data.text}` : ""}`);
    }
    res.sendStatus(200);
  });
  ```

  ```python Python theme={null}
  @app.post("/webhooks/zavu")
  async def zavu_webhook(payload: dict):
      if payload["type"] == "message.status":
          data = payload["data"]
          caption = f": {data['text']}" if data.get("text") else ""
          print(f"{data['from']} posted a {data['messageType']} story{caption}")
      return {"ok": True}
  ```
</CodeGroup>

<Note>
  Your own status posts are not delivered — only statuses from your contacts trigger the event. Media bytes are intentionally omitted; use `messageType` and `mimetype` to know the story kind.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Groups" icon="users" href="/guides/whatsapp-alt/groups">
    Identify group messages and their author.
  </Card>

  <Card title="Receiving Messages" icon="inbox" href="/guides/receiving-messages/webhooks">
    Configure and verify your sender webhook.
  </Card>
</CardGroup>