@kindly-ai/react-native

The official Kindly Chat SDK for React Native — a thin TurboModule wrapper around the public iOS xcframework and Android AAR. The native binaries ship inside the npm tarball, so customers don't need Swift Package Manager, Maven Central, or any extra Gradle config.

Status: Early access. Targets React Native New Architecture (TurboModules + Codegen). Requires RN ≥ 0.76.

Installation

yarn add @kindly-ai/react-native
cd ios && pod install

That's it — no extra setup. The bundled iOS framework is pre-signed with the Apple Distribution cert and passes App Store ITMS-91065 validation.

Usage

import { KindlySDK, hexColor } from '@kindly-ai/react-native';

// 1. Initialize once on app start
KindlySDK.start({
  botKey: 'your-bot-key',
  market: 'general', // required — your market slug (Settings → General → Details & markets)
  languageCode: 'en',
  // Optional: invoked by the SDK when it needs an authenticated JWT for
  // the current chat session. `chatId` is the backend-generated identifier
  // — include it when calling your auth backend so the token is scoped to
  // this chat. Return null for anonymous chats.
  authTokenCallback: async (chatId) => {
    return await yourAuthBackend.getKindlyJWT({ chatId });
  },
});

// 2. Open the chat UI when the user wants it
<Button title="Open chat" onPress={() => KindlySDK.launchChat()} />

// 3. (Optional) host-app callbacks for buttons / link interception
KindlySDK.setDelegate({
  onButtonPressed: (button, chatLog) => console.log('button', button),
  shouldHandleLink: (url) => {
    if (url.startsWith('myapp://')) {
      // Take over the deep link
      return false;
    }
    return true; // let the SDK open it
  },
});

API

Lifecycle

| Method | Purpose | |---|---| | start({botKey, market, languageCode?, authTokenCallback?}) | Initialize the SDK. Must be called before any other method. market is required (Markets feature); the SDK loads that market's settings with no fallback. | | displayChat({languageCode?, triggerDialogueId?}) | Show the chat UI. | | launchChat({triggerDialogueId?}) | Connect (if needed) and show chat. Recommended on Android. | | closeChat() | Dismiss the UI without ending the session. | | endChat() | End the chat session: clears messages, token, dismisses UI. | | kill() | Tear the SDK down completely; call start() again before reuse. | | setLanguage(code) | Update the language for the current session. |

Messaging

| Method | Purpose | |---|---| | sendMessage(text, {newContext?}) | Send a message programmatically. Returns the reconciled message. | | setNewContext({...}) / clearNewContext() | Stage / clear context attached to the next message. | | triggerDialogue(id) / clearTriggerDialogue() | Trigger a specific dialogue by id. | | handleUrl(url) | Handle a kindly://chat/dialogue/{id} deep link. Returns true if the URL was handled. | | callHandover(callback) | Initiate a handover to a human agent. |

Theme

| Method | Purpose | |---|---| | setCustomTheme({…}) | Apply a custom theme. Pass undefined fields to keep defaults. | | clearCustomTheme() | Revert to the default / API-supplied theme. | | hexColor(hex) | Helper: #RRGGBB / #AARRGGBB → ARGB int (used in the theme). |

Push

| Method | Purpose | |---|---| | setAPNSDeviceToken(token) | iOS only — register the APNS device token. | | saveNotificationToken(token) | Android only — register the FCM token. | | handleNotification(data) | Forward an incoming push payload to the SDK. | | isKindlyNotification(data) | Returns true if the given push originated from Kindly. |

State / settings

| Method | Purpose | |---|---| | isChatDisplayed() | Returns true if the chat UI is currently visible (iOS only — Android always false). | | saveAuthToken(token) | Save a JWT auth token (iOS keychain). | | setVerboseLogging(enabled) | Toggle verbose SDK logging. | | setCrashReporting(enabled) | Toggle Sentry crash reporting from inside the SDK. |

Delegate

| Method | Purpose | |---|---| | setDelegate({onButtonPressed?, shouldHandleLink?, shouldHandleNotification?}) | Register host-app callbacks. | | clearDelegate() | Remove all delegate callbacks. |

shouldHandleLink and shouldHandleNotification are awaited synchronously by the native SDK with a 5-second timeout. After timeout the SDK falls back to its default true (handle normally) so chat doesn't hang on a slow JS callback.

Compatibility

• React Native: 0.76+ (New Architecture only)
• iOS: 15.0+
• Android: API level 24+ (Android 7.0)

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT