> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/integration/mobile/mobile-notifications.md).

# Mobile Notifications

Cuoral automatically handles **web notifications** for new messages. If you also want to notify users on your mobile application, you can use Cuoral's **Message Webhook** to build your own mobile push notification flow.

The webhook allows your backend to receive new message events and forward them to your mobile notification service.

### How It Works

The mobile notification flow works as follows:

```
Customer sends message
        ↓
Cuoral receives message
        ↓
Cuoral sends Message Webhook
        ↓
Your Backend
        ↓
Your Push Notification Service
        ↓
Mobile App
        ↓
User receives notification
```

Cuoral is responsible for sending the webhook. Your application is responsible for processing the webhook and triggering the mobile push notification.

### Web Notifications vs. Mobile Notifications

| Notification Type         | Responsibility                  |
| ------------------------- | ------------------------------- |
| Web notifications         | Handled automatically by Cuoral |
| Mobile push notifications | Handled by your application     |

You do not need to implement anything for web notifications.

For mobile notifications, you need to:

1. Receive the `message` webhook.
2. Determine whether the message should trigger a mobile notification.
3. Identify the mobile user/device that should receive the notification.
4. Send the notification through your push notification provider.

### Message Webhook

When a new message is created, Cuoral sends a `message` webhook to your configured webhook endpoint.

Example payload:

```json
{
  "email": "customer@example.com",
  "name": "John Doe",
  "message": "Hello, I need help with my account.",
  "sender": "customer"
}
```

The `sender` field indicates who sent the message:

* `customer` — The message was sent by the customer.
* `internal` — The message was sent by an agent, internal user, or bot.

See [**Message Event**](#message-webhook) for the complete webhook payload and event documentation.

### Recommended Architecture

We recommend processing mobile notifications on your backend rather than directly from the mobile application.

```
                  ┌──────────────┐
                  │    Cuoral    │
                  └──────┬───────┘
                         │
                  Message Webhook
                         │
                         ▼
                  ┌──────────────┐
                  │ Your Backend │
                  └──────┬───────┘
                         │
                Push Notification
                         │
                         ▼
               ┌──────────────────┐
               │ Push Provider    │
               │                  │
               │ APNs / FCM / ... │
               └────────┬─────────┘
                        │
                        ▼
                  ┌──────────────┐
                  │  Mobile App  │
                  └──────────────┘
```

This approach keeps your push notification credentials and business logic on your server.

### Processing a Message

When your backend receives a message webhook:

#### 1. Verify the Webhook

Before processing the event, verify the `X-Cuoral-Webhook-Signature` header.

See **Webhook Authentication** for details.

#### 2. Check the Sender

Determine whether the message was sent by a customer or an internal user.

For example:

```javascript
if (payload.sender === "customer") {
  // Consider sending a mobile notification
}
```

Depending on your application's requirements, you may only want to notify mobile users for messages sent by customers.

#### 3. Identify the Recipient

Use the information in the webhook payload, such as the customer's `email`, to determine which user or device should receive the notification.

Your application should maintain the relationship between your users and their mobile push tokens.

For example:

```
customer@example.com
        ↓
Your User ID
        ↓
Mobile Device Token
```

#### 4. Send the Push Notification

Once you have identified the recipient, send a push notification through your preferred notification provider.

Common options include:

* **Apple Push Notification service (APNs)** for iOS
* **Firebase Cloud Messaging (FCM)** for Android
* Other push notification providers that support your mobile application

The push notification might contain:

```json
{
  "title": "New message",
  "body": "Hello, I need help with my account."
}
```

### Handling Retries

Cuoral may retry a webhook if your endpoint does not return a successful response.

Because of this, your webhook handler should be **idempotent**.

Avoid sending duplicate mobile notifications if the same webhook is delivered more than once.

> **Important:** Your webhook endpoint should acknowledge the webhook only after it has been successfully received and validated. Your application should also have a strategy for preventing duplicate push notifications.

### Example Flow

A customer sends:

> "Hello, I need help with my account."

Cuoral sends your backend:

```json
{
  "email": "customer@example.com",
  "name": "John Doe",
  "message": "Hello, I need help with my account.",
  "sender": "customer"
}
```

Your backend:

1. Verifies the webhook signature.
2. Checks that `sender` is `customer`.
3. Looks up the user associated with `customer@example.com`.
4. Retrieves the user's mobile push token.
5. Sends the notification through APNs, FCM, or your push provider.
6. Returns `200 OK` to Cuoral.

The user then receives the notification in your mobile application.

### What Cuoral Handles

Cuoral automatically handles:

* Receiving the original message
* Sending the message webhook
* Web notifications

### What Your Application Handles

Your application is responsible for:

* Receiving and verifying the webhook
* Determining who should receive a mobile notification
* Managing mobile device tokens
* Sending push notifications
* Handling notification preferences
* Preventing duplicate notifications

### Next Steps

To implement mobile notifications, you will need:

1. A configured **Message Webhook** endpoint.
2. Webhook signature verification.
3. A way to map Cuoral users to your mobile users.
4. A mobile push notification provider such as APNs or FCM.
5. Logic to process message events and send notifications.