@talkjs/react-native/README.md

Official TalkJS SDK for React Native

# TalkJS React Native SDK

Official TalkJS SDK for React Native

## What is TalkJS?

[TalkJS](https://talkjs.com) is a developer friendly chat API with a pre-built UI that is highly customisable. You can build a chat feature in minutes instead of months.

With TalkJS, you can create chat features that boost user engagement, retention, and conversion rate.

![Screenshot of TalkJS header](https://talkjs.com/images/talkjs_header.png?v=060423-1)

Don't hesitate to [let us know](https://talkjs.com/?chat) if you have any questions about TalkJS.

## Installation

**Note:** React Native CLI does not autolink libraries with native modules when those libraries are transitive
dependencies. So you have to explicitly install the SDK's peer dependencies as shown below for the native modules to
be loaded correctly

Npm:

```sh
npm install @talkjs/react-native @notifee/react-native @react-native-community/push-notification-ios @react-native-firebase/app @react-native-firebase/messaging react-native-webview
```

Yarn:

```sh
yarn add @talkjs/react-native @notifee/react-native @react-native-community/push-notification-ios @react-native-firebase/app @react-native-firebase/messaging react-native-webview
```

## Usage

You can import the library in one of the following ways:

ES6 / TypeScript:

```js
import * as TalkjsRn from '@talkjs/react-native';
```

CommonJS:

```js
const TalkjsRn = require('@talkjs/react-native');
```

Then follow our [React Native guide](https://talkjs.com/docs/Getting_Started/Frameworks/React_Native/)
to start using TalkJS in your project.

## TalkJS is fully forward compatible

We promise to never break API compatibility. We may at times deprecate methods or fields, but we will
never remove them. If something that used to work stops working, then that's a bug.
Please [report it](https://talkjs.com/?chat) and we'll fix it asap.

The package is being released in a beta state. The reason for this is that there are things that one
can do with the TalkJS JavaScript SDK that aren't possible with the React Native SDK. We will
release v1.0.0 of this package once the two SDKs are similar in terms of features. This however
does not take away from our commitment to always maintain backward compatibility. So you can be
assured that the package is stable for production use.

## Changelog

Note: These are only the changes that have an effect on the React Native package and its interface.
TalkJS gets many improvements and fixes all the time. Consider subscribing to
[our changelog](https://changelog.talkjs.com) if you want to stay updated.

### 0.16.1

### Changes

- Update dependencies.

### 0.16.0

#### New Features

- Add `onError` prop to [Session](https://talkjs.com/docs/UI_Components/React_Native/Components/Session/#props).

### 0.15.0

#### New Features

- Session component now creates a User if they do not already exist. Previously, you needed to mount
  the `ConversationList` or `Chatbox` in order for the user to be created in the backend. This had the
  consequence that trying to register the push notification device token with a new user would fail if
  you only used the Session component.

#### Changes

- Due to how [@react-native-firebase/messaging](https://www.npmjs.com/package/@react-native-firebase/messaging)
  and [@notifee/react-native](https://www.npmjs.com/package/@notifee/react-native) are designed, Firebase messaging
  library will overide Notifee's Objective-C notification response handler since v7.9.0 of `@notifee/react-native`.

  This affected the SDK's functionality that relied on Notifee. If you are using Firebase for notifications
  on iOS, this update will ensure everything works accordingly. If you are using APNs, you'll need to update your
  `react-native.config.js` as shown in the [docs](https://talkjs.com/docs/Features/Notifications/Mobile_Push_Notifications/React_Native/#apple-push-notification-service-apns).

- In v0.13.0, there was an undocumented change where `getConversationBuilder()` would return the same object if the
  conversation ID did not change. This update reverts that change. Now, every call to `getConversationBuilder()` will
  return a new object.

- Update dependencies.

#### Fixes

- Fix `onNotificationPressed` not working on iOS when using Firebase for push notifications on iOS.
- Fix bug in iOS where registering the device token would some times not happen

### 0.14.0

#### New Features

- Add `hideKeyboardAccessoryView` prop to `Chatbox` and `ConversationList`. When set to `true` it
  removes the accessory view (^ ˅ and Done) from the top of the iOS keyboard.
  The default value is `false`.

#### Changes

- (Breaking Change): As part of supporting React Native 0.79, we have dropped the support for
  CommonJS source files. The package now only ships with ESM source files.
- Update dependencies

### 0.13.2

#### Fixes

- Fix `setPushRegistration` and `unsetPushRegistration` methods not working.

### 0.13.1

#### Fixes

- Fix extra padding on iOS that would intermittently occur after the keyboard is opened.

### 0.13.0

#### New Features

- The `keyboardVerticalOffset` prop is now also used in Android. This is part of the fix to ensure proper
  keyboard behaviour on apps targeting Android 15 and above.
  The default value on Android is `55 + StatusBar.currentHeight`.

#### Changes

- Update dependencies.

#### Fixes

- Fix keyboard issues on Android 15 due to Android's enforcement of edge-to-edge
- Fix internal event subscriptions not being cleaned up properly on re-renders.

### 0.12.1

####

- Changed the default value for the `keyboardVerticalOffset` to `95`.

#### Fixes

- Fix iOS bug when New Architecture is enabled where the whole UI would be scrollable when the keyboard
  is open.

### 0.12.0

#### New Features

- Added `customEmojis` prop to `Chatbox` and `ConversationList`. This prop adds a set of custom emoji images
  to the emoji picker, the emoji autocompleter, and emoji reactions. It allows users to send and
  receive custom emojis.
- Added `keyboardVerticalOffset` prop to `Chatbox`. This prop is basically identical to the one passed
  to [KeyboardAvoidingView](https://reactnative.dev/docs/keyboardavoidingview#keyboardverticaloffset).
  The default value is `90`.

  NB: This new prop is only used in iOS. It is used as part of a fix to a bug on iOS where the top part
  of the chat would get covered when the keyboard is opened. On Android, the `KeyboardAvoidingView`
  component is disabled.

#### Changes

- Update dependencies.

#### Fixes

- Fix bug in iOS where the Chat Header and/or the top most messages would get covered when the keyboard
  is opened.
- Fix ref methods not working when called after a delay.
- Fix `TypeError: _messageField.getTextResolver is not a function (it is undefined), js engine: hermes.` error.

### 0.11.0

### New Features

- Add `scrollToMessage` prop to the `Chatbox` component.

#### Fixes

- Fix registering of device tokens when a Session is used immediately after the app launches

### 0.10.1

#### Changes

- Improved error reporting.

#### Fixes

- Fix issue that prevented having multiple Sessions active at the same time.

### 0.10.0

#### New Features

- Add `token` and `tokenFetcher` props to [Session](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Session/#props). These props are part of our efforts at impoving [identity verification and authentication](https://talkjs.com/docs/Features/Security_Settings/Authentication/).

[See the reference documentation](https://talkjs.com/docs/Features/Security_Settings/Advanced_Authentication/#token-reference) for full details on the technical requirements for the JSON Web Token(JWT).

#### Deprecated

- Due to the above new props, we have deprecated the `signature` prop on the Session component.

### 0.9.1

#### Fixes

- Fix a regression with messages not getting marked as read when loading the Chatbox.

### 0.9.0

#### New Features

- Add `disableZoom` prop to `Chatbox` and `ConversationList`. This allows you to choose whether the user
  can pinch to zoom in and out of the UI. By default its value is `false` and the usr can zoom into the UI.

#### Changes

- Upgraded dependencies

#### Fixes

- Fix unnecessary warnings in iOS when calling `MessageField` methods.

### 0.8.4

#### Fixes

- Fix bug in Android with push notifications not showing when sender's photo is not defined.

### 0.8.3

#### Fixes

- Fix issue with `getNotificationHandler` being undefined.

### 0.8.2

#### Fixes

- Fix errors not showing up in debug mode.

### 0.8.1

#### Changes

- The `ConversationList` no longer highlights the first conversation by default.

### 0.8.0

#### New Features

- Add support for push notifications via Firebase on iOS.
- Add `onMessage` and `onUnreadsChange` props to [`Session`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Session/#props) component.
- Add `hasValidCredentials`, `clearPushRegistration`, `setPushRegistation` and `unsetPushRegistration` methods to
  [`Session`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Session/#methods) component.

#### Changes

- Remove implicit push notification permissions request. The users of this library will need to explicitly request for
  push notification permissions on iOS and Android 13+.
- Upgraded dependencies.
- Removed bounce in iOS when the UI reached the edge of the content.
- Renamed `AndroidChannel` and `IOSPermissions` interfaces to `AndroidSettings` and `IOSSettings` respectively.

#### Fixes

- Fix bug in `Session` when user synchronization is disabled.
- Fix bug with `MessageField.setText` and `MessageField.typeText` that would cause a crash given certain strings.
- Fix bug with `HTMLPanel` not loading.

### 0.7.1

#### Changes

- Update dependencies.
- Changed behaviour when [`onSelectConversation`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#onSelectConversation) prop is not given. Previously, in this scenario, clicking on a conversation
  would result in nothing happening. Now, the conversation will be selected and the TalkJS Inbox Mobile view
  will be shown.

#### Fixes

- Fix a regression with [`onSelectConversation`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#onSelectConversation) in `ConversationList`.
- Fix a bug with notifications not sent by TalkJS being displayed twice.

### 0.7.0

#### New Features

- Added `onLeaveConversation`, `onCustomMessageAction` and `onCustomConversationAction` props. These are intended to replace
  the methods with the same names. The methods have been deprecated. This change was made to ensure that this SDK's interface
  matched the [`React SDK's`](https://www.npmjs.com/package/@talkjs/react).

#### Changes

- Deprecated the `off` method in both `Chatbox` and `ConversationList`.

#### Fixes

- (iOS) Fixed a bug with videos in link previews automatically playing in fullscreen mode. The videos will
  now play inline instead.

### 0.6.0

#### New Features

- Make the WebView transparent. This means that whatever background colour you have applied to the parent `View` will be used in the empty areas around the TalkJS UI.
- Add [`getCurrentConversation`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#getcurrentconversation), [`onCustomConversationAction`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#oncustomconversationaction), [`onLeaveConversation`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#onleaveconversation) and [`sendLocation`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#sendlocation) methods to `Chatbox`.
- Add [`leave`](https://talkjs/docs/Reference/React_Native_SDK/Object_Types/ConversationBuilder/#leave) method to `ConversationBuilder`.
- Add support for passing data to themes in both [`Chatbox`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#theme) and [`ConversationList`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#theme).

#### Changes

- Upgraded dependencies.
- Changes the type of the `conversation` property in [`SelectConversationEvent`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#selectconversationevent) from `ConversationBuilder`to [`ConversationData`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#conversationdata).
- Add `isForegroundEvent` property to [`NotificationPressedEvent`](https://talkjs.com/docs/Reference/React_Native_SDK/Object_Types/NotificationHandler/#notificationpressedevent) to indicate if the user pressed the notification while the app was in the foreground or background.
  NOTE: In iOS this property is always true since, if the app was in the background, iOS will open the app first before calling the foreground event handler.
  The background event handler is never called in iOS in this case.

#### Fixes

- Fix zooming on iOS. A previous workaround to prevent the UI from zooming in when clicking the MessageField on iOS resulted in zooming being disabled entirely.
  This update removes the workaround. Should you encounter the issue, set the MessageField's font size to 16px to fix it. The default TalkJS theme already uses
  a font size of 16px.
- Fix bug when trying to display notifications on Android when the app has previously been killed.
- Fix bug in Android with the app not opening when a notification is clicked.

### 0.5.1

#### Fixes

- Fix bug in Android that caused the errors: `Cannot assign to property '_injectJavaScript' which has only a getter` or
  `Attempted to assign to readonly property` when using React Native version 0.70 and below.
- Fix `Error: No Firebase App '[DEFAULT]' has been created - call firebase.initializeApp()` in Android when attempting to use the
  SDK without enabling push notifications. With this fix, you no longer need to setup Firebase plugins in gradle if you
  don't intend to use push notifications

### 0.5.0

#### New Features

- **(BREAKING CHANGE)**: Added `@react-native-async-storage/async-storage` as a peer dependency.
  If you don't already depend on the package be sure install it by running: `npm install @react-native-async-storage/async-storage`
  or `yarn add @react-native-async-storage/async-storage` depending on your package manager
- Added support for [Custom Message Actions.](https://talkjs.com/docs/Features/Customizations/Actions/)
- A [loading component](https://talkjs.com/docs/Reference/React_Native_SDK/Components/Chatbox/#loadingComponent) can now be passed as a prop to `Chatbox` and `ConversationList` and it will be shown when
  the respective components are loading the UI. This is mostly useful on first load. Subsequent loads of the
  UI components are much faster.
- Add [`onTokenRefresh`](https://talkjs.com/docs/Reference/React_Native_SDK/Object_Types/NotificationHandler/#ontokenrefresh) and [`onNotificationPressed`](https://talkjs.com/docs/Reference/React_Native_SDK/Object_Types/NotificationHandler/#onnotificationpressed) methods to `NotificationHandler`.
- Add [`getNotificationHandler`](https://talkjs.com/docs/Reference/React_Native_SDK/API/getNotificationHandler/) function.

#### Changes

- Upgraded dependencies.
- [`registerPushNotificationHandlers`](https://talkjs.com/docs/Reference/React_Native_SDK/API/registerPushNotificationHandlers/) now returns `Promise<NotificationHandler>` instead of `Promise<void>`.

#### Fixes

- Fix bug in `sendMessage` where a message would get sent multiple times in certain scenarios.
- Fix bug with `captureKeyboardEvents` prop in `Chatbox` not working.
- Fix slow scrolling performance on the UI for Android devices.
- Fix bug when handling active notifications.

### 0.4.2

This is a minor update ensuring a great user experience when using [voice messages](https://talkjs.com/docs/Features/Customizations/Voice_Messages/),
particularly on iOS.

To enable [voice messages](https://talkjs.com/docs/Features/Customizations/Voice_Messages/),
you'll need to first enable it per role in the TalkJS dashboard. Then you'll need to
specify the necessary permissions for both Android and iOS.

For Android, add the following to your `AndroidManifest.xml` file:

```xml
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

For iOS, add the following to your `Info.plist` file:

```xml
<key>NSMicrophoneUsageDescription</key>
<string>Messages shown to your user when the microphone is accessed for the first time</string>
```

### 0.4.1

### Fixes

- Fix mark as read. This release ensures that messages are marked as read reliably as long as the chat is
  visible. If the app is in the background, or the chat is covered by the System UI (example: when receiving a call)
  then the messages won't be marked as read.

- Fix rare crash on Android for SDK 28+ when the @react-navigation/native library is used.

### 0.4.0

- Fix Notifee display notification error.

With this release, we have updated the SDK's dependencies and peer dependencies to keep them up to date
and also fix bugs in some of them.

As of npm v7, peer dependencies are installed by default so upgrading the TalkJS SDK should also upgrade
the peer dependencies accordingly. For yarn users, you may have to update the packages individually as shown:

```sh
yarn upgrade @notifee/react-native@^5.3.0 @react-native-community/push-notification-ios@^1.10.1 @react-native-firebase/app@^14.11.0 @react-native-firebase/messaging@^14.11.0 react-native-webview@^11.21.2
```

These libraries are defined as peer dependencies rather than dependencies since they contain native
code and currently, React Native does not auto link transitive dependencies.

The new version of the notifee library also eliminates the need to add the local maven repository
manually to your project. You can remove the section below. (Your app will still build and run if you
don't remove it)

```groovy
  maven {
    url "$rootDir/../node_modules/@notifee/react-native/android/libs"
  }
```

### 0.3.4

- Fix "Chat not found" error when joining as Guest.

### 0.3.3

- Fix regression in the support of devices with iOS 14 and lower.

### 0.3.2

- Fix Invariant Violation error due to transitive dependencies not being loaded.

To ensure the SDK's peer dependencies' native modules are loaded correctly, you have to explicitly
install them as direct dependencies for your app/project. This is to ensure React Native CLI can
autolink them. Below is how you'd accomplish that:

NPM:

```sh
npm install @notifee/react-native @react-native-community/push-notification-ios @react-native-firebase/app @react-native-firebase/messaging react-native-webview
```

Yarn:

```sh
yarn add @notifee/react-native @react-native-community/push-notification-ios @react-native-firebase/app @react-native-firebase/messaging react-native-webview
```

### 0.3.1

- Fix "Chat not found" bug when creating a new conversation.

### 0.3.0

When upgrading to this version, you'll need to update your `android/build.gradle` file by adding the
following block to the repositories section of allprojects:

```
allprojects {

  // ... you may have other items before the "repositories" section.

  repositories {

    // ... you will already have some local repositories defined ...

    // ADD THIS BLOCK
    maven {
      url "$rootDir/../node_modules/@notifee/react-native/android/libs"
    }
  }
}
```

#### New Features

- Improved Android Notifications. They are now shown as Conversations and grouped accordingly. Images sent will also appear in the notifications.
- Added more configuration options on Android Channels ([Reference](https://talkjs.com/docs/Reference/React_Native_SDK/API/registerPushNotificationHandlers/#androidchannel)).
- Improved Error Reporting.
- Add support for [Guest Access](https://talkjs.com/docs/Reference/Concepts/Guests/) through the addition of `asGuest` prop in Chatbox.
- Enable capturing of keyup events in Chatbox through the `captureKeyboardEvents` and `onKeyup` props.
- Added the methods: [`getText`](https://talkjs.com/docs/Reference/React_Native_SDK/Object_Types/MessageField/#gettext) and
  [`typeText`](https://talkjs.com/docs/Reference/React_Native_SDK/Object_Types/MessageField/#typetext) to MessageField.

#### Changes

- Changed [`oneOnOneId`](https://talkjs.com/docs/Reference/React_Native_SDK/API/oneOnOneId/) to also accept `User` Objects.
- Changed [`registerPushNotificationHandlers`](https://talkjs.com/docs/Reference/React_Native_SDK/API/registerPushNotificationHandlers/#parameters)
  to add support for iOS Permissions.
- Changed [`showFeedHeader`](https://talkjs.com/docs/Reference/React_Native_SDK/Components/ConversationList/#showFeedHeader) default to `false`.

#### Fixes

- Fix bug when user and/or conversation synchronization were disabled.

#### Deprecated

- The following props in ConversationList: `feedConversationTitleMode`, `thirdParties`, `onBlur` and `onFocus`.
- The following props in Chatbox: `chatSubtitleMode`, `chatTitleMode`, `thirdParties`, `translateConversations`, `onBlur` and `onFocus`.

### 0.2.1

- Fix bug in Chatbox when conversation synchronization was disabled.

### 0.2.0

- Added a ConversationList component.
- Added the messageField property to the Chatbox component
- Fix bug in ConversationBuilder.setAttributes that prevented setting a value to null or undefined
  after previously having given it a value.
- (iOS): Fix push notification registration token not getting received.
- (iOS): Fix zooming when messageField is clicked.

### 0.1.0

- Added the following components: Session, Chatbox and HtmlPanel.
- First release