# Sendbird

Add real-time in-app messaging and push notifications to your app — powered by Sendbird's native SDKs.

[Sendbird](https://sendbird.com/) is a communication platform that provides pre-built chat UI, real-time messaging, and push notifications. Instead of building a messaging system from scratch — handling message delivery, read receipts, typing indicators, offline queuing, and notification routing — Sendbird handles all of it through its SDKs and cloud infrastructure.

WebToNative's Sendbird plugin integrates the official Sendbird iOS and Android SDKs directly into your app. This gives your users a **native messaging experience** with a full-featured chat UI, group channels, user management, and push notifications via APNs (iOS) and Firebase Cloud Messaging (Android) — all controllable from your web layer through the JavaScript bridge.

### Why use the native Sendbird plugin?

Embedding a web-based chat widget inside a WebView leads to poor performance, unreliable push notifications, and a UX that feels out of place on mobile. The WebToNative Sendbird plugin uses Sendbird's native UI kit, which means your users get a chat experience that looks and performs like a first-class native feature — smooth scrolling, native push delivery, and proper background behavior.

{% hint style="info" %}
**Prerequisites:** Import the WebToNative JavaScript bridge into your website before using any of the functions below. See the [Getting Started](https://docs.webtonative.com/javascript-apis/getting-started) guide.
{% endhint %}

***

## Key Concepts

Before diving into setup, here are a few terms you'll encounter throughout this guide:

**Application ID (`appId`)** — Identifies your Sendbird application. The SDK needs it to initialize. You'll find it in your Sendbird dashboard under your application's overview.

**Group Channel** — A channel where multiple users can chat. Creating one returns a `channelUrl` that you use to open the channel in the native UI.

**Distinct Channel (`isDistinct`)** — When set to `true`, if a group channel with the exact same members already exists, Sendbird reuses it instead of creating a duplicate. Useful for 1-on-1 conversations.

***

## Step 1 — Set Up Your Sendbird Account

### 1.1 Create a Sendbird Application

1. Sign up or log in at the [Sendbird Dashboard](https://dashboard.sendbird.com/).
2. Create a new application (or use an existing one).
3. Copy your **Application ID** from the application overview page — you'll need this for the WebToNative dashboard.

### 1.2 Configure Push Notifications in Sendbird

To deliver push notifications when users receive messages while the app is backgrounded, you need to provide Sendbird with your push credentials.

Navigate to **Settings → Push Notifications** in your Sendbird dashboard, enable push notifications, and add the following credentials:

**For iOS (Apple Push Notification service):**

| Credential                           | Where to find it                                                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| App Bundle ID                        | WebToNative Dashboard → App Info                                                                                                 |
| `.p8` or `.p12` authentication token | [Apple Developer Portal → Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/certificates/list) |
| Key ID                               | Apple Developer Portal → Keys section                                                                                            |
| Team ID                              | Apple Developer Portal → Membership details                                                                                      |

**For Android (Firebase Cloud Messaging):**

| Credential                    | Where to find it                                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Service Account Key (HTTP v1) | [Firebase Console](https://console.firebase.google.com/) → Project Settings → Service Accounts → Generate New Private Key |
| `google-services.json`        | Firebase Console → Project Settings → General → Your Apps → Download                                                      |

{% hint style="info" %}
If you don't have a `google-services.json` file yet, follow the [Firebase Notification Integration Guide](https://docs.webtonative.com/plugin/firebase-notification-integration-ios-setup) to create one.
{% endhint %}

***

## Step 2 — Configure the Plugin in WebToNative

Open your **WebToNative Dashboard → Add-ons → Sendbird** and configure the following settings:

### 2.1 Enable Sendbird

Turn on the **Enable Sendbird** toggle to activate the plugin.

### 2.2 Enter Your App ID

Enter the Sendbird **Application ID** you copied from the Sendbird dashboard in Step 1.

### 2.3 Upload Firebase Service JSON (Android)

Firebase Cloud Messaging requires a `google-services.json` file embedded in your Android build for push notifications to work.

Click **"Click to upload"** and select the `google-services.json` file you downloaded from the Firebase Console.

{% hint style="info" %}
**Note:** The `google-services.json` file is required for push notifications on Android. It is not required for iOS.
{% endhint %}

### 2.4 Disable Notification in App Foreground (Optional)

When enabled, push notifications will **not** appear while the user is actively using the app. This prevents disruptive notification banners during an active chat session.

### 2.5 Ask for Notification Permission on Launch

When enabled, the app will request push notification permission from the user the first time the app is launched.

If you disable this setting, you can request permission later using a **Trigger URL** — a specific URL path that, when visited by the user inside the app, triggers the notification permission prompt. This gives you control over when and where in your app flow the user sees the permission dialog.

### 2.6 Save and Rebuild

After configuring the settings, click **Save & Rebuild** to generate a new build with the Sendbird plugin enabled.

***

## JavaScript API Reference

### Initialize

Initializes the Sendbird SDK with a user ID and connects the user. You can optionally set a nickname and profile image at the same time.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdInitialize({
  userId: "user123",
  nickname: "John",
  profileurl: "https://example.com/avatar.png",
  callback: function (response) {
    if (response.error) {
      console.error("Init failed:", response.error);
      return;
    }
    console.log("Sendbird initialized for user:", response.userId);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdInitialize } from "webtonative/build/SendBird";

sendbirdInitialize({
  userId: "user123",
  nickname: "John",
  profileurl: "https://example.com/avatar.png",
  callback: (response) => {
    if (response.error) {
      console.error("Init failed:", response.error);
      return;
    }
    console.log("Sendbird initialized for user:", response.userId);
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key          | Type       | Required | Description                                                                                       |
| ------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------- |
| `userId`     | `String`   | Yes      | The unique user ID to connect with. If the user doesn't exist in Sendbird, a new user is created. |
| `nickname`   | `String`   | No       | Display name for the user.                                                                        |
| `profileurl` | `String`   | No       | URL of the user's profile image.                                                                  |
| `callback`   | `Function` | No       | Function invoked with the initialization response.                                                |

***

### Is Initialized

Checks whether the Sendbird SDK has been initialized. Useful on app resume or page load to determine if you need to call `sendbirdInitialize` again.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdIsInitialized({
  callback: function (response) {
    if (response.initialized) {
      console.log("SDK ready, appId:", response.appId);
    } else {
      console.log("SDK not initialized — call sendbirdInitialize()");
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdIsInitialized } from "webtonative/build/SendBird";

sendbirdIsInitialized({
  callback: (response) => {
    if (response.initialized) {
      console.log("SDK ready, appId:", response.appId);
    } else {
      console.log("SDK not initialized — call sendbirdInitialize()");
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key           | Type      | Description                                                |
| ------------- | --------- | ---------------------------------------------------------- |
| `initialized` | `Boolean` | `true` if the Sendbird SDK has been initialized.           |
| `appId`       | `String`  | The Sendbird Application ID (present only if initialized). |

***

### Is Connected

Checks whether the user is currently connected to the Sendbird server. A user can be initialized but temporarily disconnected (e.g. after calling `sendbirdDisconnect`).

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdIsConnected({
  callback: function (response) {
    console.log("Connected:", response.connected);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdIsConnected } from "webtonative/build/SendBird";

sendbirdIsConnected({
  callback: (response) => {
    console.log("Connected:", response.connected);
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key         | Type      | Description                                  |
| ----------- | --------- | -------------------------------------------- |
| `connected` | `Boolean` | `true` if the user is connected to Sendbird. |

***

### Get User ID

Retrieves the user ID of the currently connected user.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdGetUserId({
  callback: function (response) {
    console.log("Current user:", response.userId);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdGetUserId } from "webtonative/build/SendBird";

sendbirdGetUserId({
  callback: (response) => {
    console.log("Current user:", response.userId);
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key      | Type     | Description                          |
| -------- | -------- | ------------------------------------ |
| `userId` | `String` | The current user's Sendbird user ID. |

***

### Update User Info

Updates the current user's nickname and/or profile image URL in Sendbird.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdUpdateUserInfo({
  nickname: "New Display Name",
  profileurl: "https://example.com/new-avatar.png",
  callback: function (response) {
    if (response.success) {
      console.log("User info updated");
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdUpdateUserInfo } from "webtonative/build/SendBird";

sendbirdUpdateUserInfo({
  nickname: "New Display Name",
  profileurl: "https://example.com/new-avatar.png",
  callback: (response) => {
    if (response.success) {
      console.log("User info updated");
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key          | Type       | Required | Description                             |
| ------------ | ---------- | -------- | --------------------------------------- |
| `nickname`   | `String`   | No       | The new display name for the user.      |
| `profileurl` | `String`   | No       | The new profile image URL for the user. |
| `callback`   | `Function` | No       | Function invoked with the response.     |

**Response:**

| Key       | Type      | Description                          |
| --------- | --------- | ------------------------------------ |
| `success` | `Boolean` | `true` if the user info was updated. |

***

### Create Group Channel

Creates a new group channel with the specified users. Returns the `channelUrl` which you can use with `sendbirdShowChannelUI` to open the channel directly.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdCreateGroupChannel({
  name: "Project Chat",
  userIds: ["user1", "user2", "user3"],
  isDistinct: true,
  callback: function (response) {
    if (response.success) {
      console.log("Channel created:", response.channelUrl);
      // Open the channel immediately
      window.WTN.SendBird.sendbirdShowChannelUI({
        url: response.channelUrl,
      });
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import {
  sendbirdCreateGroupChannel,
  sendbirdShowChannelUI,
} from "webtonative/build/SendBird";

sendbirdCreateGroupChannel({
  name: "Project Chat",
  userIds: ["user1", "user2", "user3"],
  isDistinct: true,
  callback: (response) => {
    if (response.success) {
      console.log("Channel created:", response.channelUrl);
      sendbirdShowChannelUI({ url: response.channelUrl });
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key          | Type       | Required | Description                                                                                                          |
| ------------ | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`       | `String`   | No       | Display name for the channel.                                                                                        |
| `userIds`    | `String[]` | Yes      | Array of user IDs to add to the channel. At least one user ID is required.                                           |
| `isDistinct` | `Boolean`  | No       | If `true`, reuses an existing channel with the exact same members instead of creating a duplicate. Default: `false`. |
| `callback`   | `Function` | No       | Function invoked with the response.                                                                                  |

**Response:**

| Key          | Type      | Description                                    |
| ------------ | --------- | ---------------------------------------------- |
| `success`    | `Boolean` | `true` if the channel was created (or reused). |
| `channelUrl` | `String`  | The URL identifier of the group channel.       |

***

### Show UI

Opens the full Sendbird native chat UI, showing the user's channel list. From here, users can enter channels, create new channels, and navigate back.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdShowUI({
  callback: function (response) {
    console.log("UI status:", response.status);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdShowUI } from "webtonative/build/SendBird";

sendbirdShowUI({
  callback: (response) => {
    console.log("UI status:", response.status);
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key       | Type      | Description                              |
| --------- | --------- | ---------------------------------------- |
| `success` | `Boolean` | `true` if the UI was shown successfully. |
| `status`  | `String`  | Status of the UI display operation.      |

***

### Show Channel UI

Opens the Sendbird native chat UI and navigates directly to a specific channel by its URL.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdShowChannelUI({
  url: "sendbird_group_channel_123",
  callback: function (response) {
    console.log("Opened channel:", response.channelUrl);
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdShowChannelUI } from "webtonative/build/SendBird";

sendbirdShowChannelUI({
  url: "sendbird_group_channel_123",
  callback: (response) => {
    console.log("Opened channel:", response.channelUrl);
  },
});
```

{% endtab %}
{% endtabs %}

**Parameters:**

| Key        | Type       | Required | Description                              |
| ---------- | ---------- | -------- | ---------------------------------------- |
| `url`      | `String`   | Yes      | The `channelUrl` of the channel to open. |
| `callback` | `Function` | No       | Function invoked with the response.      |

**Response:**

| Key          | Type      | Description                         |
| ------------ | --------- | ----------------------------------- |
| `success`    | `Boolean` | `true` if the channel UI was shown. |
| `status`     | `String`  | Status of the UI display operation. |
| `channelUrl` | `String`  | The URL of the displayed channel.   |

***

### UI Closed Callback

Define this function on your webpage to run custom logic when the user closes the Sendbird native UI (e.g. navigates back from the channel list). This is a global callback, not a parameter.

```javascript
function wtn_sendbird_uiclosed() {
  console.log("Sendbird UI was closed");
  // Navigate back, refresh data, etc.
}
```

***

### Disconnect

Disconnects the current user's session from Sendbird. The user remains logged in — their details stay saved on the device, and the device continues to receive push notifications. Use this for temporary disconnections (e.g. switching tabs, backgrounding).

To reconnect, call `sendbirdInitialize` again.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdDisconnect({
  callback: function (response) {
    if (response.success) {
      console.log("Disconnected (session preserved)");
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdDisconnect } from "webtonative/build/SendBird";

sendbirdDisconnect({
  callback: (response) => {
    if (response.success) {
      console.log("Disconnected (session preserved)");
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key       | Type      | Description                              |
| --------- | --------- | ---------------------------------------- |
| `success` | `Boolean` | `true` if the disconnect was successful. |

***

### Logout

Fully logs out the current user from Sendbird. This disconnects the session, unregisters the device's push notification token, and clears all stored Sendbird data from the device. Use this when the user is signing out of your app.

> **Disconnect vs. Logout:** `sendbirdDisconnect` is a soft pause — the user stays logged in and push continues. `sendbirdLogout` is a full cleanup — push is unregistered and all local Sendbird data is cleared.

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdLogout({
  callback: function (response) {
    if (response.success) {
      console.log("Logged out — push unregistered, data cleared");
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import { sendbirdLogout } from "webtonative/build/SendBird";

sendbirdLogout({
  callback: (response) => {
    if (response.success) {
      console.log("Logged out — push unregistered, data cleared");
    }
  },
});
```

{% endtab %}
{% endtabs %}

**Response:**

| Key       | Type      | Description                          |
| --------- | --------- | ------------------------------------ |
| `success` | `Boolean` | `true` if the logout was successful. |

***

## Typical Implementation Flow

Here's how a typical Sendbird integration works end-to-end:

1. **App launch** — Call `sendbirdIsInitialized()` to check if the SDK is already set up.
2. **Initialize** — If not initialized, call `sendbirdInitialize()` with the user's ID, nickname, and profile image. This both initializes the SDK and connects the user.
3. **Show chat** — Call `sendbirdShowUI()` to open the full channel list, or `sendbirdCreateGroupChannel()` followed by `sendbirdShowChannelUI()` to create and open a specific channel.
4. **Handle UI close** — Define `wtn_sendbird_uiclosed()` on your page to run logic when the user exits the Sendbird UI.
5. **User signs out** — Call `sendbirdLogout()` to fully clear the session and unregister push. If the user is just switching views, use `sendbirdDisconnect()` instead.

### Recipe: Create a Channel and Open It

This common pattern creates a group channel (or reuses an existing one if `isDistinct` is `true`) and immediately opens it in the native chat UI:

{% tabs %}
{% tab title="Plain JavaScript" %}

```javascript
window.WTN.SendBird.sendbirdCreateGroupChannel({
  name: "Support Chat",
  userIds: ["support_agent", "customer_42"],
  isDistinct: true,
  callback: function (response) {
    if (response.success) {
      window.WTN.SendBird.sendbirdShowChannelUI({
        url: response.channelUrl,
      });
    } else {
      console.error("Failed to create channel");
    }
  },
});
```

{% endtab %}

{% tab title="ES5+ Module" %}

```javascript
import {
  sendbirdCreateGroupChannel,
  sendbirdShowChannelUI,
} from "webtonative/build/SendBird";

sendbirdCreateGroupChannel({
  name: "Support Chat",
  userIds: ["support_agent", "customer_42"],
  isDistinct: true,
  callback: (response) => {
    if (response.success) {
      sendbirdShowChannelUI({ url: response.channelUrl });
    } else {
      console.error("Failed to create channel");
    }
  },
});
```

{% endtab %}
{% endtabs %}

***

## Implementation Checklist

### Sendbird Dashboard

* [ ] Created a Sendbird application and copied the **Application ID**
* [ ] Enabled **Push Notifications** under Settings → Push Notifications
* [ ] Added **APNs credentials** (iOS): `.p8`/`.p12` token, Key ID, Team ID, Bundle ID
* [ ] Added **FCM credentials** (Android): Service Account Key (HTTP v1)

### WebToNative Dashboard

* [ ] Enabled the **Sendbird** add-on
* [ ] Entered the Sendbird **Application ID**
* [ ] Uploaded **`google-services.json`** (required for Android push notifications)
* [ ] Configured **Disable Notification in App Foreground** based on your preference
* [ ] Configured **Ask for Notification Permission on Launch** (or set a Trigger URL for deferred permission)
* [ ] Clicked **Save & Rebuild** to generate a new build

### Your Website

* [ ] Imported the [WebToNative JavaScript bridge](https://docs.webtonative.com/javascript-apis/getting-started)
* [ ] Implemented `sendbirdInitialize()` with user ID on login
* [ ] Implemented `sendbirdShowUI()` or `sendbirdShowChannelUI()` for chat access
* [ ] Defined `wtn_sendbird_uiclosed()` callback for UI close handling
* [ ] Implemented `sendbirdLogout()` in your sign-out flow
* [ ] Tested push notifications on a real device (both iOS and Android)

***

## Frequently Asked Questions

<details>

<summary>What's the difference between <code>disconnect</code> and <code>logout</code>?</summary>

`sendbirdDisconnect` is a soft pause — the user stays logged in, their data is preserved on the device, and push notifications continue to be delivered. Use it for temporary disconnections like backgrounding or switching views. `sendbirdLogout` is a full cleanup — it disconnects the session, unregisters the device's push token, and clears all local Sendbird data. Use it when the user signs out of your app.

</details>

<details>

<summary>Push notifications aren't arriving. What should I check?</summary>

Verify the following in order: (1) Push notifications are enabled in the Sendbird dashboard under Settings → Push Notifications. (2) Your APNs or FCM credentials are correctly added in the Sendbird dashboard. (3) For Android, `google-services.json` is uploaded in the WebToNative dashboard. (4) The user is logged in (not logged out) — `sendbirdLogout` unregisters the push token. (5) You're testing on a real device, not a simulator.

</details>

<details>

<summary>Do I need to call <code>sendbirdInitialize</code> on every page load?</summary>

Not necessarily. Once initialized, the SDK persists across the app session. Use `sendbirdIsInitialized()` on page load to check — if it returns `initialized: true`, the SDK is already connected and you can proceed directly to showing UI or managing channels.

</details>

<details>

<summary>What happens if I call <code>sendbirdCreateGroupChannel</code> with <code>isDistinct: true</code> and the channel already exists?</summary>

Sendbird returns the existing channel's `channelUrl` instead of creating a duplicate. This is the recommended approach for 1-on-1 conversations or any scenario where you want to avoid duplicate channels between the same set of users.

</details>

<details>

<summary>Can I control when the notification permission prompt appears?</summary>

Yes. If you disable **Ask for Notification Permission on Launch** in the WebToNative dashboard, you can set a **Trigger URL** instead. The permission prompt will appear when the user navigates to that specific URL path inside the app. This lets you ask for permission at a contextually appropriate moment (e.g. when the user first opens the chat section).

</details>

<details>

<summary>Can I test Sendbird in a simulator?</summary>

The messaging UI and channel management work in simulators. However, push notifications require a physical device with APNs (iOS) or FCM (Android) support — simulators cannot receive push notifications.

</details>

<details>

<summary>Is <code>google-services.json</code> required for iOS?</summary>

No. The `google-services.json` file is only required for Android push notifications via Firebase Cloud Messaging. iOS push notifications use APNs credentials configured directly in the Sendbird dashboard.

</details>

***

*Feature taken live on 30/03/26*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.webtonative.com/javascript-apis/sendbird.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.