Push Notifications

For Web Chat, you can implement custom push notifications by using webhooks within the Conversation APIs.

This functionality enables you to notify end-users when a live agent joins their conversation. These notifications alert users that an agent has joined and begun responding in the chat.

Overview

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

Step 1: Configure Ada Webhooks

1. In Ada Dashboard → Settings → Webhooks, create a POST endpoint, e.g. https://your-api.example.com/ada/webhooks.
2. Subscribe to conversation events, at minimum: v1.conversation.message.

Step 2: End User Device

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

In order to obtain the conversation_id, subscribe to one of the events offered in the SDK API Reference that return the conversation_id. We suggest using:

• ada:agent:joined
• ada:minimize_chat

We suggest maintaining a persistent mapping so you can reach the 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 token

• 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 revoked; periodically clean stale tokens.

Step 3: Handling Webhook Events

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 out by the role: "human_agent".
3. Fetch device tokens for conversation_id.
4. Fan-out a notification per active device token.

Python (FastAPI) — APNs example

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)