@talqui-oss/talqui-sdk-reactnative 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,182 @@
1
+ # Talqui React Native SDK: instructions for AI coding agents
2
+
3
+ Quick install guide for AI agents adding Talqui live chat to a React Native or Expo app. Follow the steps in order. Every step ends with something to check before moving on.
4
+
5
+ Package: `@talqui-oss/talqui-sdk-reactnative`. Human docs: [README](./README.md).
6
+
7
+ **Full documentation:** [docs.talqui.chat/guides/chat-sdks/react-native](https://docs.talqui.chat/guides/chat-sdks/react-native). Open it whenever you need more than this guide: identifying users, metadata, every event, permissions per platform and troubleshooting. The rest of the Talqui platform (REST API, webhooks, chatbots, AI agents) is documented at [docs.talqui.chat](https://docs.talqui.chat).
8
+
9
+ ## 0. What you need from the user
10
+
11
+ Two IDs from their Talqui workspace. They are public (the same values go in a website snippet), so they can live in the app code or in env vars.
12
+
13
+ | Value | Where it is |
14
+ | --- | --- |
15
+ | `tenantId` | The workspace UUID. In the app URL: `https://app.talqui.chat/tenant/<tenantId>/...` |
16
+ | `connectionId` | The WebChat connection UUID. app.talqui.chat → Plugins → WebChat → Installation, or in the URL of that connection: `.../connections/<connectionId>` |
17
+
18
+ How to get them:
19
+
20
+ 1. **Ask the user** for both IDs.
21
+ 2. **No Talqui account yet?** Open `https://app.talqui.chat/initiate/signup/` in their browser and ask them to create the account. If you can see the browser, wait until they are logged in, then read `tenantId` from the address bar (`/tenant/<tenantId>/`).
22
+ 3. **No WebChat connection yet?** Ask them to add one in Plugins → WebChat, then read `connectionId` from the Installation screen or the connection URL.
23
+
24
+ Never ask for, type or read the user's password or any secret. You only need the two IDs. Both are UUIDs (`xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx`); if a value does not look like one, ask again.
25
+
26
+ ## 1. Detect the project type
27
+
28
+ | Signal | Project type | Go to |
29
+ | --- | --- | --- |
30
+ | `expo` in `package.json`, no `ios/` and `android/` folders | Expo managed (works in Expo Go) | 2a |
31
+ | `expo` in `package.json` and native folders exist | Expo with prebuild / dev build | 2a, then `npx expo prebuild` or rebuild the dev client |
32
+ | No `expo`, `ios/Podfile` exists | Bare React Native | 2b |
33
+ | `app/_layout.tsx` with `expo-router` | Expo Router | provider goes in `app/_layout.tsx` (step 3) |
34
+ | `@react-navigation/native` | React Navigation | provider goes around `NavigationContainer` (step 3) |
35
+
36
+ Requirements: React Native 0.73+ (Expo SDK 50+), iOS 15+, Android 7+ (API 24).
37
+
38
+ ## 2. Install
39
+
40
+ ### 2a. Expo
41
+
42
+ ```bash
43
+ npx expo install @talqui-oss/talqui-sdk-reactnative react-native-webview @react-native-async-storage/async-storage
44
+ ```
45
+
46
+ Use `npx expo install` (not `npm install`) so the two peer dependencies match the Expo SDK.
47
+
48
+ ### 2b. Bare React Native
49
+
50
+ ```bash
51
+ npm install @talqui-oss/talqui-sdk-reactnative react-native-webview @react-native-async-storage/async-storage
52
+ cd ios && pod install && cd ..
53
+ ```
54
+
55
+ Use the project's package manager (`yarn add`, `pnpm add`) if it has a lockfile for it.
56
+
57
+ **Check:** the three packages are in `package.json` dependencies.
58
+
59
+ ## 3. Add the provider once, at the root
60
+
61
+ ```tsx
62
+ import { TalquiProvider } from '@talqui-oss/talqui-sdk-reactnative';
63
+
64
+ export default function App() {
65
+ return (
66
+ <TalquiProvider tenantId="TENANT_ID" connectionId="CONNECTION_ID">
67
+ {/* the rest of the app, including NavigationContainer */}
68
+ </TalquiProvider>
69
+ );
70
+ }
71
+ ```
72
+
73
+ - **Expo Router:** wrap the `<Stack />` / `<Slot />` in `app/_layout.tsx`.
74
+ - **React Navigation:** put `TalquiProvider` outside `NavigationContainer`.
75
+ - Only one `TalquiProvider` per app. Every `useTalqui()` must be below it.
76
+ - Prefer env vars when the project already uses them: `process.env.EXPO_PUBLIC_TALQUI_TENANT_ID` (Expo) or the project's config module.
77
+ - During integration add `debug` to see every message exchanged with the chat in the Metro logs. Remove it before shipping.
78
+
79
+ ## 4. Open the chat
80
+
81
+ Full screen, from any button (support screen, settings, help menu):
82
+
83
+ ```tsx
84
+ import { useTalqui } from '@talqui-oss/talqui-sdk-reactnative';
85
+
86
+ function HelpButton() {
87
+ const talqui = useTalqui();
88
+ return <Button title="Talk to us" onPress={talqui.open} />;
89
+ }
90
+ ```
91
+
92
+ Or inline, as a tab or screen of its own:
93
+
94
+ ```tsx
95
+ import { TalquiChat } from '@talqui-oss/talqui-sdk-reactnative';
96
+ import { useIsFocused } from '@react-navigation/native';
97
+
98
+ function ChatScreen() {
99
+ return <TalquiChat style={{ flex: 1 }} visible={useIsFocused()} hideCloseButton />;
100
+ }
101
+ ```
102
+
103
+ - `visible` tells the SDK when the tab is on screen (unread counting). With Expo Router use `useIsFocused` from `@react-navigation/native` too.
104
+ - `hideCloseButton` removes the header's close button, which has nothing to close in a tab.
105
+ - Do not put the chat inside a `Modal` or a bottom sheet: `open()` already presents it full screen and handles the Android back button.
106
+
107
+ ## 5. Permissions (attachments, camera, voice messages)
108
+
109
+ Expo, in `app.json` / `app.config.*`:
110
+
111
+ ```json
112
+ {
113
+ "expo": {
114
+ "ios": {
115
+ "infoPlist": {
116
+ "NSCameraUsageDescription": "Take photos to send in the support chat.",
117
+ "NSMicrophoneUsageDescription": "Record voice messages for the support chat.",
118
+ "NSPhotoLibraryUsageDescription": "Choose photos to send in the support chat."
119
+ }
120
+ },
121
+ "android": {
122
+ "softwareKeyboardLayoutMode": "resize",
123
+ "permissions": ["android.permission.CAMERA", "android.permission.RECORD_AUDIO", "android.permission.MODIFY_AUDIO_SETTINGS"]
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ Bare: the same three keys in `ios/<App>/Info.plist`; `CAMERA`, `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS` in `android/app/src/main/AndroidManifest.xml`; `android:windowSoftInputMode="adjustResize"` on the main activity. Merge with existing entries; never replace the file.
130
+
131
+ ## 6. Connect it to the app's login (when the app has users)
132
+
133
+ ```ts
134
+ const talqui = useTalqui();
135
+
136
+ // after login
137
+ await talqui.identify({ name: user.name, email: user.email, phone: user.phone });
138
+
139
+ // on logout, always
140
+ await talqui.logout();
141
+ ```
142
+
143
+ - Find the app's existing login and logout handlers (auth context, store action, `signOut`) and call these there. Do not create a new auth flow.
144
+ - `phone` in international format (`+5511999990000`). Invalid values are ignored, the rest still applies.
145
+ - `userHash` keeps a user's history across devices. It must be computed **on the backend**: `HMAC_SHA256(secret, "<tenantId>:<userId>")`, lowercase hex. Never put the secret in the app. If the project has no backend endpoint for it, skip `userHash` and tell the user.
146
+
147
+ Optional context the support team sees next to the conversation:
148
+
149
+ ```ts
150
+ talqui.setContactMeta({ plan: 'pro' }); // about the person
151
+ talqui.setSessionMeta({ screen: 'checkout', order_id: '4821' }); // about this conversation
152
+ ```
153
+
154
+ Keys: `a-z 0-9 _ -`, up to 60 chars, 20 per call. Values: string, number, boolean (stored as text, 255 chars) or `null` to remove. Never send passwords, tokens or card data.
155
+
156
+ ## 7. Validate
157
+
158
+ Run these and report the result to the user:
159
+
160
+ 1. `npx tsc --noEmit` (TypeScript projects) has no new errors.
161
+ 2. Start the app (`npx expo start` or `npx react-native run-ios` / `run-android`) and trigger `open()`.
162
+ 3. With `debug` on, Metro shows `[talqui] ← ready {...}` within a few seconds.
163
+ 4. The chat shows the workspace name and a message box. Send "Test from the app".
164
+ 5. Ask the user to confirm the message arrived in their inbox at app.talqui.chat.
165
+ 6. If the app identifies users: after login the pre-chat form does not appear (when name, email and phone cover the fields the workspace requires); after logout and opening again, the chat starts as a new visitor.
166
+
167
+ ## 8. Troubleshooting
168
+
169
+ | Symptom | Fix |
170
+ | --- | --- |
171
+ | "Invalid link" screen | `tenantId` or `connectionId` is wrong or not a UUID. |
172
+ | `useTalqui must be used inside <TalquiProvider>` | The provider is not above that component. Move it to the root. |
173
+ | Attach / camera / mic does nothing | Permissions from step 5 are missing; rebuild native apps after editing them. |
174
+ | Keyboard covers the message box on Android | `softwareKeyboardLayoutMode: "resize"` (Expo) or `adjustResize` (bare). |
175
+ | `open()` does nothing | An inline `<TalquiChat />` is on screen; it already shows the chat. |
176
+ | Native module errors after install (bare) | Run `pod install` and rebuild; Expo Go needs no native step. |
177
+
178
+ ## Rules
179
+
180
+ - Do not fork the SDK, copy its source or call the chat page directly. Use the package API.
181
+ - Do not edit files inside `node_modules`.
182
+ - Keep the change small: provider, one entry point, permissions, login hooks. Ask before adding screens the user did not request.
package/README.md CHANGED
@@ -14,6 +14,8 @@
14
14
  <div align="center">
15
15
  <a href="https://docs.talqui.chat/guides/chat-sdks/react-native">Documentation</a>
16
16
  <span> · </span>
17
+ <a href="https://github.com/talqui-oss/talqui-sdk-reactnative/blob/main/AGENT_INSTRUCTIONS.md">AI agent instructions</a>
18
+ <span> · </span>
17
19
  <a href="https://www.npmjs.com/package/@talqui-oss/talqui-sdk-reactnative">npm</a>
18
20
  <span> · </span>
19
21
  <a href="./example">Example app</a>
@@ -23,7 +25,9 @@
23
25
 
24
26
  ## Introduction
25
27
 
26
- [Talqui](https://talqui.chat) brings WhatsApp, Instagram, Mercado Livre, your website and your app into one inbox. This package adds the Talqui chat to a React Native app: drop in a provider, call `open()` from any button, and the conversation lands in the same inbox your team already uses, with history, attachments, voice messages, bots and AI agents.
28
+ [Talqui](https://talqui.chat) is the communication layer for customer service and sales. It connects every channel your customers use, including your website and your app, to one workspace where AI agents, chatbots and human teams work together: build chatbots without code, put AI agents on the front line for support and sales, hand conversations over to people when it matters, and plug everything into your own systems.
29
+
30
+ This package brings that experience into your React Native app. Drop in a provider, call `open()` from any button, and each conversation lands in the same workspace as every other channel, with history, attachments, voice messages, chatbots and AI agents.
27
31
 
28
32
  ## Features
29
33
 
@@ -65,6 +69,8 @@ What your users see, from the [example app](https://github.com/talqui-oss/talqui
65
69
 
66
70
  ## Install
67
71
 
72
+ > Using an AI coding agent? Point it to [`AGENT_INSTRUCTIONS.md`](https://github.com/talqui-oss/talqui-sdk-reactnative/blob/main/AGENT_INSTRUCTIONS.md): a step-by-step install it can follow and validate on its own.
73
+
68
74
  ```bash
69
75
  npx expo install @talqui-oss/talqui-sdk-reactnative react-native-webview @react-native-async-storage/async-storage
70
76
  ```
@@ -184,6 +190,32 @@ Call it when your user logs out. It forgets the user on this device, clears ever
184
190
  await talqui.logout();
185
191
  ```
186
192
 
193
+ ## Push notifications
194
+
195
+ When your team, a bot or an AI agent answers while the user is away, Talqui can notify them. Pick how in app.talqui.chat → Plugins → WebChat → **Notificações**:
196
+
197
+ - **Through Talqui**: upload a service account of your Firebase project there, then hand the device token to the SDK. Talqui sends the push with your Firebase project.
198
+ - **Webhook**: Talqui posts a signed event to your backend, which notifies the user however you like. Nothing to do in the app. Send your own user id with `setContactMeta({ user_id: … })` to receive it in the event.
199
+
200
+ With [@react-native-firebase/messaging](https://rnfirebase.io/messaging/usage):
201
+
202
+ ```tsx
203
+ const talqui = useTalqui();
204
+
205
+ useEffect(() => {
206
+ messaging().getToken().then(talqui.setPushToken);
207
+ const unsubscribeRefresh = messaging().onTokenRefresh(talqui.setPushToken);
208
+ // Open the chat when the user taps a Talqui notification.
209
+ const unsubscribeTap = messaging().onNotificationOpenedApp((message) => talqui.handlePush(message.data));
210
+ return () => {
211
+ unsubscribeRefresh();
212
+ unsubscribeTap();
213
+ };
214
+ }, []);
215
+ ```
216
+
217
+ `logout()` unlinks the token from the user, so the next person on the phone never gets their replies. The user is only notified when the chat is not on screen.
218
+
187
219
  ## API
188
220
 
189
221
  ### `<TalquiProvider>`
@@ -208,6 +240,8 @@ await talqui.logout();
208
240
  | `setContactMeta(meta)` / `setSessionMeta(meta)` | Custom data, see [Metadata](#metadata). |
209
241
  | `prefill(text)` | Puts text in the message box. The user still decides to send it. |
210
242
  | `logout()` | Forgets the user and starts a fresh visitor. |
243
+ | `setPushToken(token)` | The device's FCM token, see [Push notifications](#push-notifications). |
244
+ | `handlePush(data)` | Opens the chat for a tapped Talqui notification; returns whether it was one. `isTalquiPush(data)` is also exported. |
211
245
  | `unreadCount`, `isReady`, `isOpen` | Current state. |
212
246
 
213
247
  ### `<TalquiChat>`
package/dist/index.d.mts CHANGED
@@ -85,6 +85,14 @@ interface TalquiApi {
85
85
  prefill(text: string): void;
86
86
  /** Call it when your user logs out: forgets this user and starts a fresh anonymous visitor. */
87
87
  logout(): Promise<void>;
88
+ /**
89
+ * The device's Firebase Cloud Messaging token, so a reply reaches the user while the app is
90
+ * closed. Works when the WebChat connection sends notifications "through Talqui" with your
91
+ * Firebase project (Settings → WebChat → Notificações). Call it at startup and on token refresh.
92
+ */
93
+ setPushToken(token: string): void;
94
+ /** Opens the chat for a tapped Talqui notification. Returns whether it was one. */
95
+ handlePush(data: Record<string, unknown> | null | undefined): boolean;
88
96
  /** Messages received while the chat was not on screen. */
89
97
  unreadCount: number;
90
98
  /** Whether the chat is loaded and accepting commands. */
@@ -124,6 +132,9 @@ declare function useTalqui(): TalquiApi;
124
132
  /** Runs `listener` for every `name` event from the chat while the component is mounted. */
125
133
  declare function useTalquiEvent<E extends TalquiEventName>(name: E, listener: TalquiEventListener<E>): void;
126
134
 
135
+ /** Whether a push message was sent by Talqui (check the message's `data`). */
136
+ declare function isTalquiPush(data: Record<string, unknown> | null | undefined): boolean;
137
+
127
138
  interface TalquiChatProps {
128
139
  style?: StyleProp<ViewStyle>;
129
140
  /**
@@ -147,4 +158,4 @@ interface TalquiChatProps {
147
158
  */
148
159
  declare function TalquiChat({ style, visible, onCloseRequested, hideCloseButton }: TalquiChatProps): react_jsx_runtime.JSX.Element;
149
160
 
150
- export { type TalquiApi, TalquiChat, type TalquiChatProps, type TalquiContact, type TalquiEventListener, type TalquiEventMap, type TalquiEventName, type TalquiMeta, TalquiProvider, type TalquiProviderProps, type TalquiUser, useTalqui, useTalquiEvent };
161
+ export { type TalquiApi, TalquiChat, type TalquiChatProps, type TalquiContact, type TalquiEventListener, type TalquiEventMap, type TalquiEventName, type TalquiMeta, TalquiProvider, type TalquiProviderProps, type TalquiUser, isTalquiPush, useTalqui, useTalquiEvent };
package/dist/index.d.ts CHANGED
@@ -85,6 +85,14 @@ interface TalquiApi {
85
85
  prefill(text: string): void;
86
86
  /** Call it when your user logs out: forgets this user and starts a fresh anonymous visitor. */
87
87
  logout(): Promise<void>;
88
+ /**
89
+ * The device's Firebase Cloud Messaging token, so a reply reaches the user while the app is
90
+ * closed. Works when the WebChat connection sends notifications "through Talqui" with your
91
+ * Firebase project (Settings → WebChat → Notificações). Call it at startup and on token refresh.
92
+ */
93
+ setPushToken(token: string): void;
94
+ /** Opens the chat for a tapped Talqui notification. Returns whether it was one. */
95
+ handlePush(data: Record<string, unknown> | null | undefined): boolean;
88
96
  /** Messages received while the chat was not on screen. */
89
97
  unreadCount: number;
90
98
  /** Whether the chat is loaded and accepting commands. */
@@ -124,6 +132,9 @@ declare function useTalqui(): TalquiApi;
124
132
  /** Runs `listener` for every `name` event from the chat while the component is mounted. */
125
133
  declare function useTalquiEvent<E extends TalquiEventName>(name: E, listener: TalquiEventListener<E>): void;
126
134
 
135
+ /** Whether a push message was sent by Talqui (check the message's `data`). */
136
+ declare function isTalquiPush(data: Record<string, unknown> | null | undefined): boolean;
137
+
127
138
  interface TalquiChatProps {
128
139
  style?: StyleProp<ViewStyle>;
129
140
  /**
@@ -147,4 +158,4 @@ interface TalquiChatProps {
147
158
  */
148
159
  declare function TalquiChat({ style, visible, onCloseRequested, hideCloseButton }: TalquiChatProps): react_jsx_runtime.JSX.Element;
149
160
 
150
- export { type TalquiApi, TalquiChat, type TalquiChatProps, type TalquiContact, type TalquiEventListener, type TalquiEventMap, type TalquiEventName, type TalquiMeta, TalquiProvider, type TalquiProviderProps, type TalquiUser, useTalqui, useTalquiEvent };
161
+ export { type TalquiApi, TalquiChat, type TalquiChatProps, type TalquiContact, type TalquiEventListener, type TalquiEventMap, type TalquiEventName, type TalquiMeta, TalquiProvider, type TalquiProviderProps, type TalquiUser, isTalquiPush, useTalqui, useTalquiEvent };
package/dist/index.js CHANGED
@@ -32,6 +32,7 @@ var index_exports = {};
32
32
  __export(index_exports, {
33
33
  TalquiChat: () => TalquiChat,
34
34
  TalquiProvider: () => TalquiProvider,
35
+ isTalquiPush: () => isTalquiPush,
35
36
  useTalqui: () => useTalqui,
36
37
  useTalquiEvent: () => useTalquiEvent
37
38
  });
@@ -47,7 +48,7 @@ var import_async_storage = __toESM(require("@react-native-async-storage/async-st
47
48
  // src/protocol.ts
48
49
  var PROTOCOL = 1;
49
50
  var DEFAULT_BASE_URL = "https://webchat.talqui.chat";
50
- var SDK_LABEL = "react-native@0.1.0";
51
+ var SDK_LABEL = "react-native@0.2.0";
51
52
  var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
52
53
  var IDENTITY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
53
54
  var USER_HASH_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
@@ -112,6 +113,9 @@ function normalizeMeta(meta, warn) {
112
113
  }
113
114
  return out;
114
115
  }
116
+ function isTalquiPush(data) {
117
+ return data?.talqui === "1";
118
+ }
115
119
 
116
120
  // src/identity.ts
117
121
  var key = (tenantId) => `talqui:identity:${tenantId}`;
@@ -331,19 +335,22 @@ function TalquiProvider(props) {
331
335
  }
332
336
  });
333
337
  }, []);
338
+ const pushToken = (0, import_react2.useRef)(null);
339
+ const platform = import_react_native2.Platform.OS === "ios" || import_react_native2.Platform.OS === "android" ? import_react_native2.Platform.OS : null;
334
340
  const replayAll = (0, import_react2.useCallback)(() => {
335
341
  const state = replay.current;
336
342
  if (state.contact) send("setContact", state.contact);
337
343
  if (Object.keys(state.contactMeta).length) send("setContactMeta", state.contactMeta);
338
344
  if (Object.keys(state.sessionMeta).length) send("setSessionMeta", state.sessionMeta);
339
345
  send("setVisibility", { visible: visibleRef.current });
346
+ if (pushToken.current) send("registerPushToken", { token: pushToken.current, platform });
340
347
  pageCloseButton.current = true;
341
348
  syncCloseButton();
342
349
  if (state.prefill) {
343
350
  send("prefill", { text: state.prefill });
344
351
  state.prefill = null;
345
352
  }
346
- }, [send, syncCloseButton]);
353
+ }, [send, syncCloseButton, platform]);
347
354
  const closeOverlay = (0, import_react2.useCallback)(() => setIsOpen(false), []);
348
355
  const inlineRef = (0, import_react2.useRef)(inline);
349
356
  inlineRef.current = inline;
@@ -433,6 +440,7 @@ function TalquiProvider(props) {
433
440
  unsubscribe();
434
441
  resolve();
435
442
  }
443
+ if (pushToken.current) send("unregisterPushToken", { token: pushToken.current });
436
444
  send("reset", {});
437
445
  });
438
446
  }
@@ -486,6 +494,8 @@ function TalquiProvider(props) {
486
494
  setSessionMeta: unsupported,
487
495
  prefill: unsupported,
488
496
  logout: async () => unsupported(),
497
+ setPushToken: unsupported,
498
+ handlePush: () => false,
489
499
  unreadCount: 0,
490
500
  isReady: false,
491
501
  isOpen: false
@@ -514,11 +524,24 @@ function TalquiProvider(props) {
514
524
  else replay.current.prefill = trimmed;
515
525
  },
516
526
  logout,
527
+ setPushToken: (token) => {
528
+ const trimmed = typeof token === "string" ? token.trim() : "";
529
+ if (!trimmed) return;
530
+ pushToken.current = trimmed;
531
+ send("registerPushToken", { token: trimmed, platform });
532
+ },
533
+ handlePush: (data) => {
534
+ if (!isTalquiPush(data) || data?.tenantId !== tenantId) return false;
535
+ setOwner("overlay");
536
+ setOverlayMounted(true);
537
+ setIsOpen(true);
538
+ return true;
539
+ },
517
540
  unreadCount,
518
541
  isReady,
519
542
  isOpen
520
543
  };
521
- }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen]);
544
+ }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen, platform, tenantId]);
522
545
  const renderWebView = (0, import_react2.useCallback)(
523
546
  (style) => identityLoaded ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
524
547
  TalquiWebView,
@@ -608,6 +631,7 @@ function TalquiChat({ style, visible = true, onCloseRequested, hideCloseButton =
608
631
  0 && (module.exports = {
609
632
  TalquiChat,
610
633
  TalquiProvider,
634
+ isTalquiPush,
611
635
  useTalqui,
612
636
  useTalquiEvent
613
637
  });
package/dist/index.mjs CHANGED
@@ -16,7 +16,7 @@ import AsyncStorage from "@react-native-async-storage/async-storage";
16
16
  // src/protocol.ts
17
17
  var PROTOCOL = 1;
18
18
  var DEFAULT_BASE_URL = "https://webchat.talqui.chat";
19
- var SDK_LABEL = "react-native@0.1.0";
19
+ var SDK_LABEL = "react-native@0.2.0";
20
20
  var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
21
21
  var IDENTITY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
22
22
  var USER_HASH_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
@@ -81,6 +81,9 @@ function normalizeMeta(meta, warn) {
81
81
  }
82
82
  return out;
83
83
  }
84
+ function isTalquiPush(data) {
85
+ return data?.talqui === "1";
86
+ }
84
87
 
85
88
  // src/identity.ts
86
89
  var key = (tenantId) => `talqui:identity:${tenantId}`;
@@ -300,19 +303,22 @@ function TalquiProvider(props) {
300
303
  }
301
304
  });
302
305
  }, []);
306
+ const pushToken = useRef2(null);
307
+ const platform = Platform2.OS === "ios" || Platform2.OS === "android" ? Platform2.OS : null;
303
308
  const replayAll = useCallback2(() => {
304
309
  const state = replay.current;
305
310
  if (state.contact) send("setContact", state.contact);
306
311
  if (Object.keys(state.contactMeta).length) send("setContactMeta", state.contactMeta);
307
312
  if (Object.keys(state.sessionMeta).length) send("setSessionMeta", state.sessionMeta);
308
313
  send("setVisibility", { visible: visibleRef.current });
314
+ if (pushToken.current) send("registerPushToken", { token: pushToken.current, platform });
309
315
  pageCloseButton.current = true;
310
316
  syncCloseButton();
311
317
  if (state.prefill) {
312
318
  send("prefill", { text: state.prefill });
313
319
  state.prefill = null;
314
320
  }
315
- }, [send, syncCloseButton]);
321
+ }, [send, syncCloseButton, platform]);
316
322
  const closeOverlay = useCallback2(() => setIsOpen(false), []);
317
323
  const inlineRef = useRef2(inline);
318
324
  inlineRef.current = inline;
@@ -402,6 +408,7 @@ function TalquiProvider(props) {
402
408
  unsubscribe();
403
409
  resolve();
404
410
  }
411
+ if (pushToken.current) send("unregisterPushToken", { token: pushToken.current });
405
412
  send("reset", {});
406
413
  });
407
414
  }
@@ -455,6 +462,8 @@ function TalquiProvider(props) {
455
462
  setSessionMeta: unsupported,
456
463
  prefill: unsupported,
457
464
  logout: async () => unsupported(),
465
+ setPushToken: unsupported,
466
+ handlePush: () => false,
458
467
  unreadCount: 0,
459
468
  isReady: false,
460
469
  isOpen: false
@@ -483,11 +492,24 @@ function TalquiProvider(props) {
483
492
  else replay.current.prefill = trimmed;
484
493
  },
485
494
  logout,
495
+ setPushToken: (token) => {
496
+ const trimmed = typeof token === "string" ? token.trim() : "";
497
+ if (!trimmed) return;
498
+ pushToken.current = trimmed;
499
+ send("registerPushToken", { token: trimmed, platform });
500
+ },
501
+ handlePush: (data) => {
502
+ if (!isTalquiPush(data) || data?.tenantId !== tenantId) return false;
503
+ setOwner("overlay");
504
+ setOverlayMounted(true);
505
+ setIsOpen(true);
506
+ return true;
507
+ },
486
508
  unreadCount,
487
509
  isReady,
488
510
  isOpen
489
511
  };
490
- }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen]);
512
+ }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen, platform, tenantId]);
491
513
  const renderWebView = useCallback2(
492
514
  (style) => identityLoaded ? /* @__PURE__ */ jsx2(
493
515
  TalquiWebView,
@@ -576,6 +598,7 @@ function TalquiChat({ style, visible = true, onCloseRequested, hideCloseButton =
576
598
  export {
577
599
  TalquiChat,
578
600
  TalquiProvider,
601
+ isTalquiPush,
579
602
  useTalqui,
580
603
  useTalquiEvent
581
604
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@talqui-oss/talqui-sdk-reactnative",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Live chat SDK for React Native and Expo: in-app customer support chat with your team, bots and AI agents.",
5
5
  "license": "MIT",
6
6
  "author": "Talqui",
@@ -51,7 +51,8 @@
51
51
  "dist",
52
52
  "src",
53
53
  "README.md",
54
- "LICENSE.md"
54
+ "LICENSE.md",
55
+ "AGENT_INSTRUCTIONS.md"
55
56
  ],
56
57
  "sideEffects": false,
57
58
  "scripts": {
@@ -15,6 +15,7 @@ import {
15
15
  buildChatUrl,
16
16
  commandScript,
17
17
  DEFAULT_BASE_URL,
18
+ isTalquiPush,
18
19
  isUuid,
19
20
  normalizeMeta,
20
21
  parseEvent,
@@ -211,12 +212,17 @@ export function TalquiProvider(props: TalquiProviderProps) {
211
212
  });
212
213
  }, []);
213
214
 
215
+ // The device's push token outlives a logout (it is the phone's, not the user's).
216
+ const pushToken = useRef<string | null>(null);
217
+ const platform = Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : null;
218
+
214
219
  const replayAll = useCallback(() => {
215
220
  const state = replay.current;
216
221
  if (state.contact) send('setContact', state.contact);
217
222
  if (Object.keys(state.contactMeta).length) send('setContactMeta', state.contactMeta);
218
223
  if (Object.keys(state.sessionMeta).length) send('setSessionMeta', state.sessionMeta);
219
224
  send('setVisibility', { visible: visibleRef.current });
225
+ if (pushToken.current) send('registerPushToken', { token: pushToken.current, platform });
220
226
  // A freshly loaded page shows the control again.
221
227
  pageCloseButton.current = true;
222
228
  syncCloseButton();
@@ -224,7 +230,7 @@ export function TalquiProvider(props: TalquiProviderProps) {
224
230
  send('prefill', { text: state.prefill });
225
231
  state.prefill = null;
226
232
  }
227
- }, [send, syncCloseButton]);
233
+ }, [send, syncCloseButton, platform]);
228
234
 
229
235
  const closeOverlay = useCallback(() => setIsOpen(false), []);
230
236
  const inlineRef = useRef(inline);
@@ -331,6 +337,8 @@ export function TalquiProvider(props: TalquiProviderProps) {
331
337
  unsubscribe();
332
338
  resolve();
333
339
  }
340
+ // The next person on this phone must not get this user's replies.
341
+ if (pushToken.current) send('unregisterPushToken', { token: pushToken.current });
334
342
  send('reset', {});
335
343
  });
336
344
  }
@@ -389,6 +397,8 @@ export function TalquiProvider(props: TalquiProviderProps) {
389
397
  setSessionMeta: unsupported,
390
398
  prefill: unsupported,
391
399
  logout: async () => unsupported(),
400
+ setPushToken: unsupported,
401
+ handlePush: () => false,
392
402
  unreadCount: 0,
393
403
  isReady: false,
394
404
  isOpen: false,
@@ -417,11 +427,24 @@ export function TalquiProvider(props: TalquiProviderProps) {
417
427
  else replay.current.prefill = trimmed;
418
428
  },
419
429
  logout,
430
+ setPushToken: (token) => {
431
+ const trimmed = typeof token === 'string' ? token.trim() : '';
432
+ if (!trimmed) return;
433
+ pushToken.current = trimmed;
434
+ send('registerPushToken', { token: trimmed, platform });
435
+ },
436
+ handlePush: (data) => {
437
+ if (!isTalquiPush(data) || data?.tenantId !== tenantId) return false;
438
+ setOwner('overlay');
439
+ setOverlayMounted(true);
440
+ setIsOpen(true);
441
+ return true;
442
+ },
420
443
  unreadCount,
421
444
  isReady,
422
445
  isOpen,
423
446
  };
424
- }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen]);
447
+ }, [supported, warn, closeOverlay, identify, setContact, setMeta, send, logout, unreadCount, isReady, isOpen, platform, tenantId]);
425
448
 
426
449
  // --- rendering --------------------------------------------------------------------------------
427
450
  const renderWebView = useCallback(
package/src/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export { TalquiProvider, useTalqui, useTalquiEvent } from './TalquiProvider';
2
+ export { isTalquiPush } from './protocol';
2
3
  export type { TalquiProviderProps } from './TalquiProvider';
3
4
  export { TalquiChat } from './TalquiChat';
4
5
  export type { TalquiChatProps } from './TalquiChat';
package/src/protocol.ts CHANGED
@@ -7,7 +7,7 @@ import type { TalquiEventMap, TalquiEventName, TalquiMeta } from './types';
7
7
  */
8
8
  export const PROTOCOL = 1;
9
9
  export const DEFAULT_BASE_URL = 'https://webchat.talqui.chat';
10
- export const SDK_LABEL = 'react-native@0.1.0';
10
+ export const SDK_LABEL = 'react-native@0.2.0';
11
11
 
12
12
  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
13
13
  export const IDENTITY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
@@ -99,3 +99,8 @@ export function normalizeMeta(meta: TalquiMeta, warn: (message: string) => void)
99
99
  }
100
100
  return out;
101
101
  }
102
+
103
+ /** Whether a push message was sent by Talqui (check the message's `data`). */
104
+ export function isTalquiPush(data: Record<string, unknown> | null | undefined): boolean {
105
+ return data?.talqui === '1';
106
+ }
package/src/types.ts CHANGED
@@ -62,6 +62,14 @@ export interface TalquiApi {
62
62
  prefill(text: string): void;
63
63
  /** Call it when your user logs out: forgets this user and starts a fresh anonymous visitor. */
64
64
  logout(): Promise<void>;
65
+ /**
66
+ * The device's Firebase Cloud Messaging token, so a reply reaches the user while the app is
67
+ * closed. Works when the WebChat connection sends notifications "through Talqui" with your
68
+ * Firebase project (Settings → WebChat → Notificações). Call it at startup and on token refresh.
69
+ */
70
+ setPushToken(token: string): void;
71
+ /** Opens the chat for a tapped Talqui notification. Returns whether it was one. */
72
+ handlePush(data: Record<string, unknown> | null | undefined): boolean;
65
73
  /** Messages received while the chat was not on screen. */
66
74
  unreadCount: number;
67
75
  /** Whether the chat is loaded and accepting commands. */