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

# Push notifications

## Overview

[Messaging](/docs/channels/messaging) supports the same notification options as legacy Chat. Use notifications for:

* **Agent join alerts**: Notify end users when a live agent joins and begins responding.
* **Message alerts**: Notify end users about live agent replies while chat is minimized or the app is in the background.

## Limitations

[Messaging](/docs/channels/messaging) notifications have these limits:

* Browser notifications require browser support, end-user permission, and an open page. The SDK does not use a service worker for browser notifications.
* Ada does not deliver mobile push notifications.
* Mobile headless mode is not a background service.

## Capabilities & configuration

Select the [Messaging](/docs/channels/messaging) notification path for your platform.

| Notification type                           | Integration                                                                                                                                         |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Browser notifications (web, page open)      | Use the browser notification methods in [step 1](#step-1-turn-on-browser-notifications-on-web).                                                     |
| Push notifications (mobile, or page closed) | Connect webhooks to your push provider in [steps 2 to 4](#step-2-configure-webhooks). Use APNs for iOS, FCM for Android, or your web push provider. |

Your application handles notification permissions and push notification taps.

## Implementation & usage

Follow the steps for your [Messaging](/docs/channels/messaging) notification type.

### Step 1: Turn on browser notifications on web

After permission approval, new live agent messages trigger browser notifications while the page is hidden or the drawer is closed.

**To request permission and observe clicks:**

1. After the SDK loads, call [`requestNotifications()`](/messaging/web/sdk-api-reference#requestnotifications) from a user gesture, such as a button click.
2. Subscribe to [`ada:web_notification:click`](/messaging/web/sdk-api-reference#subscribeevent) to receive `conversation_id` and `message_id` when the end user clicks a browser notification.

**`JavaScript`**

```javascript JavaScript
document.getElementById("enable-notifications")?.addEventListener("click", () => {
  window.adaEmbed.requestNotifications();
});

window.adaEmbed.subscribeEvent("ada:web_notification:click", ({ conversation_id, message_id }) => {
  console.log("Notification clicked:", conversation_id, message_id);
});
```

Clicking a browser notification focuses the window and opens the chat. If your host handles a notification itself, call [`handleNotification()`](/messaging/web/sdk-api-reference#handlenotification) to open the drawer.

### Step 2: Configure webhooks

[Webhooks](/reference/introduction/webhooks) send conversation events to your backend.

**To configure webhooks:**

1. In the Ada dashboard, go to **Config > PLATFORM > Webhooks**.
2. Add your backend's **POST** endpoint, such as `https://your-api.example.com/ada/webhooks`.
3. Subscribe to `v1.conversation.message`.

### Step 3: Map conversations to device tokens

Your backend needs a mapping between each `conversation_id` and the end user's device tokens.

**To collect the mapping:**

1. Request notification permission in your application.
2. Get the device token from your push provider.
3. Read `conversation_id` from SDK events through the platform callbacks below.
4. Store the `conversation_id`, device token, and platform in your backend.

| Platform     | Conversation events and callbacks                                                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Web          | Subscribe to [`ada:agent:joined`, `ada:minimize_chat`, or `ada:conversation:message`](/messaging/web/sdk-api-reference#subscribeevent). Each event includes `conversation_id`. |
| iOS          | Use [`eventCallbacks`](/messaging/ios/sdk-api-reference#events) to receive `ada:agent:joined`. Read `conversation_id` from `event["data"]`.                                    |
| Android      | Use [`addSdkEventCallback`](/messaging/android/sdk-api-reference#addsdkeventcallback) to receive the event key and JSON payload. Read `conversation_id` from the payload.      |
| React Native | Use [`onEvent`](/messaging/react-native/sdk-api-reference#events) to receive `ada:agent:joined` or `ada:conversation:message`. Read `conversation_id` from the event data.     |

The `deviceToken` setting and `setDeviceToken` store `device_token` and `device_os` in the end user's sensitive metadata.
The stored SDK value does not replace the conversation-to-device-token mapping in your backend.

When a device token rotates, update the mapping. When an end user signs out, revoke that device token's mapping for their conversations.

### Step 4: Handle webhook events

Your backend uses the webhook's conversation ID to find the recipient device tokens. The example shows the fields needed for delivery:

```json
{
  "type": "v1.conversation.message",
  "data": {
    "author": { "role": "human_agent" },
    "content": { "body": "Your order is ready.", "type": "text" },
    "conversation_id": "5f7e0e2c1e7c7e000f0f9c3a",
    "message_id": "61f46e0b-fa39-4e44-850b-c1ca8f958dd3"
  }
}
```

**To send push notifications:**

1. Verify webhook authenticity with the endpoint's signing secret, as described in the [Webhooks guide](/reference/introduction/webhooks).
2. Filter for `v1.conversation.message` events with `data.author.role: "human_agent"`.
3. Read `data.conversation_id`, `data.message_id`, and `data.content`.
4. Look up active device tokens for `data.conversation_id` in your backend.
5. Send a push notification to each active device token through APNs, FCM, or your web push provider.
6. Include the conversation and message identifiers so your application can open the intended conversation after a tap.

After a push tap, focus or open your page.
Once the SDK has started for the intended user, call [`handleNotification()`](/messaging/web/sdk-api-reference#handlenotification) from page code to open the current chat.

### Validate delivery

Test notifications in the complete application.

* Test permission denial and approval.
* Send a live agent reply while the conversation is not visible.
* Tap the notification. Confirm that the intended conversation opens.
* Rotate the device token. Confirm that your backend updates the mapping.
* Sign out. Confirm that the device stops receiving push notifications for the previous account.

---

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