Getting started

To make the most of this guide, you will need:

1. A TalkJS account
2. React Native (version 0.64 or higher)
3. A React Native app that you will add TalkJS to. If you don't already have one, you can follow the official guide to get started.

The React Native SDK is built on top of the classic JavaScript SDK. To ensure you have access to all correct settings, go to your Project settings, select Show Classic SDK settings, and save your changes. You now have all the settings you need for your project, including to customize your chat UI.

If you use React Native without Expo, add the @talkjs/react-native package to your project along with its dependencies:

1yarn add @talkjs/react-native @notifee/react-native @react-native-community/push-notification-ios @react-native-firebase/app @react-native-firebase/messaging react-native-webview @react-native-async-storage/async-storage

If you are targeting iOS, you'll also need to add the following to your Podfile in your app's target section:

1pod 'Firebase', :modular_headers => true
2pod 'FirebaseCore', :modular_headers => true
3pod 'GoogleUtilities', :modular_headers => true
4$RNFirebaseAsStaticFramework = true

Afterwards, run:

1npx pod-install

For Expo projects, install the @talkjs/expo package instead alongside its dependencies:

1npx expo install @talkjs/expo @notifee/react-native react-native-webview @react-native-async-storage/async-storage expo-build-properties

The @talkjs/expo package is identical to @talkjs/react-native in terms of features. @talkjs/expo is just specifically designed to ensure compatibility with Expo.

The @talkjs/expo package doesn't work with Expo Go, because some of the package's dependencies contain native code.

JSON
1{
2  "expo": {
3    "plugins": [
4      // Other plugins
5      [
6        "expo-build-properties",
7        {
8          "android": {
9            "extraMavenRepos": [
10              "../../node_modules/@notifee/react-native/android/libs"
11            ]
12          }
13        }
14      ]
15    ]
16  }
17}

Import TalkJS in the component where you want the chatbox to live.

1import * as TalkRn from '@talkjs/react-native';

If you are using the Expo package:

1import * as TalkRn from '@talkjs/expo';

First, create a TalkJS user in your chat component. The User object is used to synchronize user data, so that TalkJS can display the data inside the chat UI.

For this guide you'll create a TalkJS user using hard-coded values. You can also create the User object with data retrieved from your database. Or you can pass the object as a prop to the component that renders the chatbox.

1function ChatComponent(props) {
2  const me = {
3    id: '123456789',
4    name: 'Alice',
5    email: 'alice@example.com',
6    photoUrl: 'https://talkjs.com/images/avatar-1.jpg',
7    welcomeMessage: 'Hey there! How are you? :-)',
8  };
9}

A conversation happens between two or more people. So far you have created one TalkJS user. Next, you'll create another hard-coded dummy user to have a conversation with.

1const other = {
2  id: '987654321',
3  name: 'Sebastian',
4  email: 'Sebastian@example.com',
5  photoUrl: 'https://talkjs.com/images/avatar-5.jpg',
6  welcomeMessage: 'Hey, how can I help? https://google.com',
7};

Next, get a ConversationBuilder to set up your conversation. A ConversationBuilder object creates a new conversation with the given participants and attributes, or modifies an existing conversation where necessary. Use the getConversationBuilder method to get the ConversationBuilder object.

The oneOnOneId method computes a conversation ID based on participants' IDs. Use this method if you want to create a conversation between two users. To create a group conversation or generate a conversation ID associated with a transaction on your platform, such as a purchase, follow the documentation on the conversation ID.

1const conversationBuilder = TalkRn.getConversationBuilder(
2  TalkRn.oneOnOneId(me, other)
3);

Next, set the participants of the conversation to the users you created:

1conversationBuilder.setParticipant(me);
2conversationBuilder.setParticipant(other);

The Session component represents a user's active TalkJS session. It also authenticates your app with TalkJS. The Session component has two required props: appId and me, which is the current TalkJS user. You can get your appId from the Settings page of the dashboard.

1return <TalkRn.Session appId="<APP_ID>" me={me} />;

You'll need to replace <APP_ID> with your TalkJS App ID. You can find your App ID in the Settings tab of the TalkJS dashboard. For this tutorial, we recommend using the App ID for TalkJS's Test Mode.

Finally, add the Chatbox component. The chatbox represents a messaging UI for a single conversation between two or more participants. It has only one required prop: conversationBuilder. For an overview of all the props that the Chatbox supports, see: Chatbox props.

A Chatbox must be a descendant of Session. It doesn't need to be a direct descendant. In this case, you don't need to add other components as children of Session other than Chatbox.

1return (
2  <TalkRn.Session appId="<APP_ID>" me={me}>
3    <TalkRn.Chatbox conversationBuilder={conversationBuilder} />
4  </TalkRn.Session>
5);

That's it. The chatbox should now be running on your app. Here is the full code for this:

1import React from 'react';
2import * as TalkRn from '@talkjs/react-native';
3
4function ChatComponent(props) {
5  const me = {
6    id: '123456789',
7    name: 'Alice',
8    email: 'alice@example.com',
9    photoUrl: 'https://talkjs.com/images/avatar-1.jpg',
10    welcomeMessage: 'Hey there! How are you? :-)',
11  };
12
13  const other = {
14    id: '987654321',
15    name: 'Sebastian',
16    email: 'Sebastian@example.com',
17    photoUrl: 'https://talkjs.com/images/avatar-5.jpg',
18    welcomeMessage: 'Hey, how can I help? https://google.com',
19  };
20
21  const conversationBuilder = TalkRn.getConversationBuilder(
22    TalkRn.oneOnOneId(me, other)
23  );
24
25  conversationBuilder.setParticipant(me);
26  conversationBuilder.setParticipant(other);
27
28  return (
29    <TalkRn.Session appId="<APP_ID>" me={me}>
30      <TalkRn.Chatbox conversationBuilder={conversationBuilder} />
31    </TalkRn.Session>
32  );
33}

If the code example isn't working even after reloading your app, you can reach out to us through support chat.

If you use React Native without Expo, follow the React Native mobile push notifications guide to set up push notifications for your app.

If you use Expo, follow the Expo mobile push notifications guide.

You can customize the look, feel, and behavior of your chat UI with HTML and CSS, using the Theme Editor in your TalkJS dashboard. The theme editor for React Native uses the same theming system as the classic JavaScript SDK. To get started, follow the theming guide.

This section provides troubleshooting instructions for issues that you may come across.

1node_modules/@notifee/react-native/android/src/main/java/io/invertase/notifee/NotifeeApiModule.java:244: error: cannot find symbol
2        new String[] {Manifest.permission.POST_NOTIFICATIONS},
3                                         ^
4  symbol:   variable POST_NOTIFICATIONS
5  location: class permission

In this guide, you've added powerful user-to-user chat to your React Native app. You also learned more about the fundamentals of TalkJS, and how it all fits together.

For more information on the options available, check out the reference pages for the Session and Chatbox components for an overview of all the props and methods that each component has.

For larger complete examples of how to integrate TalkJS into your app, see our examples repo.