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

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
  ```
package/dist/index.js CHANGED
@@ -47,7 +47,7 @@ var import_async_storage = __toESM(require("@react-native-async-storage/async-st
47
47
  // src/protocol.ts
48
48
  var PROTOCOL = 1;
49
49
  var DEFAULT_BASE_URL = "https://webchat.talqui.chat";
50
- var SDK_LABEL = "react-native@0.1.0";
50
+ var SDK_LABEL = "react-native@0.1.1";
51
51
  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
52
  var IDENTITY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
53
53
  var USER_HASH_PATTERN = /^[A-Za-z0-9_-]{32,128}$/;
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.1.1";
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}$/;
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.1.1",
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": {
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.1.1';
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}$/;