Push notifications

Overview

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 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 notification path for your platform.

Your application handles notification permissions and push notification taps.

Implementation & usage

Follow the steps for your 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() from a user gesture, such as a button click.
2. Subscribe to ada:web_notification:click to receive conversation_id and message_id when the end user clicks a browser notification.

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() to open the drawer.

Step 2: Configure webhooks

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.

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:

{
  "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.
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() 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.