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:

{
  "email": "[e-mail]",
  "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 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:

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:

[e-mail]
        ↓
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:

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

{
  "email": "[e-mail]",
  "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 [e-mail].

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.