> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Push notifications

> **Warning**
>
> Ada has deprecated Chat. Messaging fully replaces Chat on December 15, 2026. Read [Introducing Messaging](https://docs.ada.cx/2026-09-30-introducing-messaging) to learn how to migrate.

## Overview

Use [Webhooks](/reference/introduction/webhooks) and your push provider to send push notifications for legacy Chat. [Messaging supports the same notification options](/docs/channels/messaging/push-notifications).

**To deliver notifications:**

1. Subscribe to the `v1.conversation.message` webhook in the Ada dashboard.
2. Map `conversation_id` to device tokens in your system.
3. Read the message and `conversation_id` from each webhook event. Look up the device tokens for that `conversation_id`.
4. Send a notification through APNs or FCM.

## Limitations

Push notifications have the following limitations:

* Browser notifications stop when the end user closes or exits the Web Chat page.
* Ada does not deliver mobile push notifications.

## Use cases

Push notifications help you keep end users informed about their conversations.

* **Agent join alerts**: Notify end users when a live agent joins their conversation and begins responding.
* **Message notifications**: Alert end users to new messages when they have minimized the chat window.

## Capabilities & configuration

Push notifications require [Webhooks](/reference/introduction/webhooks) integration and device token management.

* **Webhook subscriptions**: Subscribe to [Conversation API](/reference/conversations/overview) events (e.g., `v1.conversation.message`) to receive real-time updates.
* **Device token mapping**: Maintain a mapping between Ada's `conversation_id` and end user device tokens.
* **Push provider integration**: Connect to APNs (iOS), FCM (Android), or browser push (VAPID) to deliver notifications.

## Implementation & usage

Set up push notifications for your Chat integration.

### Step 1: Configure webhooks

Set up [Webhooks](/reference/introduction/webhooks) to receive conversation events from Ada.

**To configure webhooks:**

1. On the Ada dashboard, go to **Config > PLATFORM > Webhooks**.
2. Create a **POST** endpoint, e.g. `https://your-api.example.com/ada/webhooks`.
3. Subscribe to conversation events, at minimum: `v1.conversation.message`.

### Step 2: Set up device mapping

From the end user device, you need to obtain the `conversation_id` and the device token.

To obtain the `conversation_id`, subscribe to one of the events offered in the [SDK API Reference](/chat/web/sdk-api-reference#subscribeevent) that return the `conversation_id`. The following events are recommended:

* `ada:agent:joined`
* `ada:minimize_chat`

Maintain a persistent mapping so you can reach the end user's devices when you have Ada's `conversation_id`.

**Keys:** `conversation_id` (Ada's Conversation Identifier) and `device_token`

**Recommended table (example):**

```
EndUserDevice(
  conversation_id STRING PK,
  device_token STRING PK,
  platform ENUM('ios','android','web'),
  last_seen_at TIMESTAMP,
  status ENUM('active','revoked')
)
```

**Collecting device tokens:**

* Mobile apps: Request notification permission at a sensible moment, then register token on login or app launch.
* Web: Use browser push (VAPID) if applicable.
* On logout/uninstall: Mark tokens as revoked; periodically clean stale tokens.

### Step 3: Handle webhook events

Process [Webhook](/reference/introduction/webhooks) events from the [Conversation API](/reference/conversations/overview).

**Event of interest:** `v1.conversation.message`

**Example payload (illustrative):**

```json
{
  "data": {
    "author": {
      "avatar": "https://www.gravatar.com",
      "display_name": "Ada Lovelace",
      "id": "5df263b7db5a7e6ea03fae9b",
      "role": "end_user"
    },
    "channel": {
      "created_at": "2020-09-20T00:00:00+00:00",
      "description": "A custom messaging channel for my AI Agent",
      "id": "5f7e0e2c1e7c7e000f0f9c3a",
      "metadata": {
        "example_key1": "example_string_value",
        "example_key2": true,
        "example_key3": 123
      },
      "modality": "messaging",
      "name": "My Custom Channel",
      "type": "custom"
    },
    "content": {
      "body": "I need help with my order",
      "type": "text"
    },
    "conversation_id": "5f7e0e2c1e7c7e000f0f9c3a",
    "end_user_id": "chatter_123",
    "created_at": "2020-09-20T00:00:00+00:00",
    "message_id": "61f46e0b-fa39-4e44-850b-c1ca8f958dd3"
  },
  "timestamp": "2020-09-20T00:00:00+00:00",
  "type": "v1.conversation.message"
}
```

**Processing steps:**

1. Verify webhook authenticity.
2. Parse `conversation_id`, `message.text`, and any metadata you want in the push. For messages sent by an agent, clients can filter by the `role: "human_agent"`.
3. Fetch device tokens for `conversation_id`.
4. Fan-out a notification per active device token.

### Code example

The following Python (FastAPI) example demonstrates APNs integration:

```python
@app.post('/ada/webhooks')
async def ada_webhook(request: Request):
    verify_ada_signature(request)
    evt = await request.json()
    if evt.get('type') != 'v1.conversation.message':
        return Response(status_code=204)

    conversation_id = evt['conversation_id']
    msg = evt.get('message', {}).get('text', 'New message')[:120]
    tokens = db.find_device_tokens(conversation_id)

    for t in tokens:
        apns.send(
            token=t.token,
            alert={"title": "New reply", "body": msg},
            custom={
                "conversation_id": evt.get('conversation_id'),
                "message_id": evt.get('message', {}).get('id')
            }
        )
    return Response(status_code=200)
```

## Related features

* [Chat onboarding](/docs/channels/chat/chat-onboarding): Get started with Chat.
* [Webhooks](/reference/introduction/webhooks): Configure webhook subscriptions.
* [Conversation API](/reference/conversations/overview): Learn about conversation events.
* [Handoffs](/docs/handoffs): Configure handoffs to human agents.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).