> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Push notifications for mobile apps

> Talqui sends the push through your own Firebase project when a reply arrives and the user is away from the chat in your React Native or Flutter app.

With the **Pela Talqui** (Through Talqui) mode, Talqui sends the push through **your** Firebase project. Notifications show your app's name and icon, and they reach iOS and Android through Firebase Cloud Messaging (FCM).

You need:

* the Talqui SDK for [React Native](https://docs.talqui.chat/guides/chat-sdks/react-native.md) or [Flutter](https://docs.talqui.chat/guides/chat-sdks/flutter.md), version 0.2.0 or later;
* Firebase Cloud Messaging set up in your app ([React Native Firebase](https://rnfirebase.io/messaging/usage) or [FlutterFire](https://firebase.google.com/docs/cloud-messaging/flutter/client));
* for iOS, your APNs authentication key uploaded to your Firebase project (**Project settings → Cloud Messaging**).

## 1. Create a service account

Talqui sends with a service account key of your Firebase project, restricted to sending notifications.

1. In the [Google Cloud console](https://console.cloud.google.com/iam-admin/serviceaccounts), select your Firebase project and open **IAM & Admin → Service accounts**.
2. **Create service account**, name it (for example `talqui-push`) and give it the role **Firebase Cloud Messaging API Admin**. No other role is needed.
3. Open the account, go to **Keys → Add key → Create new key → JSON**. A `.json` file downloads.

> [!WARNING]
>
> Upload the **service account key**, a JSON with `"type": "service_account"` and a `private_key`. The `google-services.json` and `GoogleService-Info.plist` files of your app are something else and are refused.

## 2. Upload it to Talqui

1. In [app.talqui.chat](https://app.talqui.chat), open **Plugins → WebChat**, open the connection and go to the **Notificações** (Notifications) tab.
2. Under **Como avisar** (How to notify), choose **Pela Talqui** (Through Talqui).
3. In **Aplicativo (Firebase)** (App), click **Enviar chave JSON** (Upload JSON key) and pick the file.

Talqui checks the key with Google before saving it. Once saved, only the project ID and the service account email are shown: the key is stored encrypted and never comes back through the screen or the API. To change it, upload a new one.

## 3. Hand the device token to the SDK

Pass the FCM token to the SDK and keep it fresh. Then open the chat when the user taps a Talqui notification.

```tsx React Native theme={null}
import messaging from '@react-native-firebase/messaging';
import { useTalqui } from '@talqui-oss/talqui-sdk-reactnative';

const talqui = useTalqui();

useEffect(() => {
  messaging().requestPermission();
  messaging().getToken().then(talqui.setPushToken);
  const unsubscribeRefresh = messaging().onTokenRefresh(talqui.setPushToken);

  // The user tapped a Talqui notification: with the app in the background...
  const unsubscribeTap = messaging().onNotificationOpenedApp((message) => talqui.handlePush(message.data));
  // ...or with the app closed.
  messaging().getInitialNotification().then((message) => message && talqui.handlePush(message.data));

  return () => {
    unsubscribeRefresh();
    unsubscribeTap();
  };
}, []);
```

```dart Flutter theme={null}
import 'package:firebase_messaging/firebase_messaging.dart';

await FirebaseMessaging.instance.requestPermission();
final token = await FirebaseMessaging.instance.getToken();
if (token != null) talqui.setPushToken(token);
FirebaseMessaging.instance.onTokenRefresh.listen(talqui.setPushToken);

// The user tapped a Talqui notification: with the app in the background...
FirebaseMessaging.onMessageOpenedApp.listen((message) => talqui.handlePush(context, message.data));
// ...or with the app closed.
final initial = await FirebaseMessaging.instance.getInitialMessage();
if (initial != null) talqui.handlePush(context, initial.data);
```

`handlePush` opens the chat and returns `true` for a Talqui notification, and does nothing for yours, so you can call it for every tap. The token is linked to the visitor once the chat loads, and `logout()` unlinks it, so the next person on the phone never gets the previous user's replies.

> [!NOTE]
>
> React Native Firebase needs native code, so push notifications don't work in Expo Go: use a [development build](https://docs.expo.dev/develop/development-builds/introduction/). The chat itself still works in Expo Go.

## 4. Test it

1. Open the chat in your app and send a message.
2. Send the app to the background (or lock the phone).
3. Reply from your Talqui inbox.
4. About 20 seconds later the notification arrives. Tap it: the chat opens.

The **Últimos avisos** (Last deliveries) table on the Notifications tab shows each attempt with the channel **App (Firebase)**.

## When the app is open

Talqui only notifies a user who isn't looking at the chat. If the app is open on another screen, the push still arrives. On Android, FCM hands it to your foreground handler instead of showing it: tell it apart from your own pushes with `isTalquiPush` and show your own banner, or update the unread badge.

```ts React Native theme={null}
import { isTalquiPush } from '@talqui-oss/talqui-sdk-reactnative';

messaging().onMessage((message) => {
  if (isTalquiPush(message.data)) showInAppBanner(message.notification?.title, message.notification?.body);
});
```

```dart Flutter theme={null}
FirebaseMessaging.onMessage.listen((message) {
  if (TalquiController.isTalquiPush(message.data)) showInAppBanner(message.notification);
});
```

## What the push carries

| | |
| - | - |
| `notification.title` | The operator's name, or "Nova mensagem" |
| `notification.body` | The start of the reply, a label for media, or "Você recebeu uma nova mensagem" when previews are hidden |
| `data.talqui` | Always `"1"`: how `isTalquiPush` recognizes it |
| `data.type` | `operator_message`, `bot_message` or `automated_message` |
| `data.sessionId` | The conversation. Also the collapse key: a new push for the same conversation replaces the previous one |
| `data.notificationId`, `data.tenantId`, `data.pluginConnectionId` | Identifiers, for your logs |

## Troubleshooting

| Problem | Cause and fix |
| - | - |
| The key is refused when uploading | It isn't a service account key (see the warning in step 1), or the account lacks the **Firebase Cloud Messaging API Admin** role, or the Cloud Messaging API is disabled in the project. |
| "Último erro" (Last error) shows under the Firebase project | Talqui couldn't send with the saved key (a deleted key, a removed role). Create a new key and upload it. |
| Nothing arrives on iOS | The APNs key isn't uploaded to Firebase, or the app lacks the **Push Notifications** capability, or the user didn't allow notifications. |
| Nothing arrives, and nothing shows in Last deliveries | The user was looking at the chat, the app never called `setPushToken`, or the mode isn't **Pela Talqui**. |
| Only one notification for several replies | Expected: one per conversation every 5 minutes. |
| The previous user gets notified | `logout()` isn't called on logout. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.