Push notifications

Overview

Use Webhooks and your push provider to send push notifications for legacy Chat. Messaging supports the same notification options.

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 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):

{
  "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:

@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: Get started with Chat.
• Webhooks: Configure webhook subscriptions.
• Conversation API: Learn about conversation events.
• Handoffs: Configure handoffs to human agents.