Push notifications

Overview

For Web Chat, you can implement custom push notifications by using Webhooks within the Conversation API. This functionality enables you to notify end users when a live agent joins their conversation and begins responding.

When Ada emits conversation events (e.g., v1.conversation.message), your webhook receives them. Your backend looks up the recipient device tokens for the event’s end_user_id, then calls your push provider (APNs, FCM) to deliver a notification.

High-level flow:

1. Subscribe to webhooks in the Ada dashboard.
2. Map conversation_id → device token in your system.
3. Process webhook events and extract message and conversation_id.
4. Send a push via APNs/FCM to the mapped device(s).

sequenceDiagram
    participant Ada
    participant YourWebhook
    participant PushService
    participant UserDevice
    Ada->>YourWebhook: POST v1.conversation.message (includes end_user_id)
    YourWebhook->>PushService: Send push (lookup device token by end_user_id)
    PushService->>UserDevice: Deliver notification

Limitations

Push notifications have the following limitations:

• End users must keep the Web Chat interface open to receive notifications. If end users close or exit the chat window, they do not receive notifications.
• Mobile push notification support is not available at this time.

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 integration and device token management.

• Webhook subscriptions: Subscribe to Conversation API 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 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 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 events from the Conversation API.

Event of interest: v1.conversation.message

Example payload (illustrative):

1
{
2
  "data": {
3
    "author": {
4
      "avatar": "https://www.gravatar.com",
5
      "display_name": "Ada Lovelace",
6
      "id": "5df263b7db5a7e6ea03fae9b",
7
      "role": "end_user"
8
    },
9
    "channel": {
10
      "created_at": "2020-09-20T00:00:00+00:00",
11
      "description": "A custom messaging channel for my AI Agent",
12
      "id": "5f7e0e2c1e7c7e000f0f9c3a",
13
      "metadata": {
14
        "example_key1": "example_string_value",
15
        "example_key2": true,
16
        "example_key3": 123
17
      },
18
      "modality": "messaging",
19
      "name": "My Custom Channel",
20
      "type": "custom"
21
    },
22
    "content": {
23
      "body": "I need help with my order",
24
      "type": "text"
25
    },
26
    "conversation_id": "5f7e0e2c1e7c7e000f0f9c3a",
27
    "end_user_id": "chatter_123",
28
    "created_at": "2020-09-20T00:00:00+00:00",
29
    "message_id": "61f46e0b-fa39-4e44-850b-c1ca8f958dd3"
30
  },
31
  "timestamp": "2020-09-20T00:00:00+00:00",
32
  "type": "v1.conversation.message"
33
}

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:

1
@app.post('/ada/webhooks')
2
async def ada_webhook(request: Request):
3
    verify_ada_signature(request)
4
    evt = await request.json()
5
    if evt.get('type') != 'v1.conversation.message':
6
        return Response(status_code=204)
7
8
    conversation_id = evt['conversation_id']
9
    msg = evt.get('message', {}).get('text', 'New message')[:120]
10
    tokens = db.find_device_tokens(conversation_id)
11
12
    for t in tokens:
13
        apns.send(
14
            token=t.token,
15
            alert={"title": "New reply", "body": msg},
16
            custom={
17
                "conversation_id": evt.get('conversation_id'),
18
                "message_id": evt.get('message', {}).get('id')
19
            }
20
        )
21
    return Response(status_code=200)

Related features

• Chat onboarding: Get started with Chat.
• Webhooks: Configure webhook subscriptions.
• Conversation API: Learn about conversation events.
• Handoffs: Configure handoffs to human agents.