React Native SDK

The Orbit React Native SDK (@devotel-orbit/react-native) embeds Orbit’s end-user-facing surfaces into iOS and Android apps: in-app chat (the same omnichannel conversation/inbox the web widget uses), owned in-app messages and content cards, and video rooms. It ships a headless OrbitChatClient plus a useOrbitChat hook, an OrbitInAppClient for the in-app feed, and an engine-injected OrbitVideoRoomClient for video rooms. This is a client SDK: it authenticates only with a publishable key (dv_live_pk_…), because it ships inside a distributed app binary. It intentionally does not wrap the server-side management resources (messaging, voice, contacts, campaigns, verify) — those require a secret key and belong in your backend, via the Node SDK or the REST API. See Client / mobile SDKs (different scope, by design) on the SDK index.

Pre-publish — source-only. The React Native SDK is not yet on npm — the install line below fails today. Until first publish, vendor the source from the monorepo (packages/sdk-react-native/) or build against the same conversations API the web widget uses.

Installation

npm install @devotel-orbit/react-native

The package is TypeScript-first with published type declarations. react and react-native are optional peer dependencies — needed only if you use the hook.

The `useOrbitChat` hook

The hook subscribes a screen to an Orbit conversation: it connects on mount, tears down on unmount, and returns the live message list, connection status, typing indicator, and send methods.

import { useOrbitChat } from "@devotel-orbit/react-native/react";

function SupportScreen() {
  const { messages, status, typing, send } = useOrbitChat({
    publicKey: "dv_live_pk_…",   // publishable key ONLY — never a secret key
    appInfo: "acme-rn/2.3.1",
  });

  // …render `messages` with your own RN components…
}

Headless chat client (OrbitChatClient)

Prefer the hook for screens; use the headless client directly for non-React code paths. Pass a storage adapter (for example @react-native-async-storage/async-storage satisfies the shape unmodified) to keep the conversation across app launches.

import { OrbitChatClient } from "@devotel-orbit/react-native";

const chat = new OrbitChatClient({
  publicKey: "dv_live_pk_…",
  storage: AsyncStorage,   // keeps the conversation across launches
  appInfo: "acme-rn/2.3.1",
});

chat.on("message", (m) => console.log("agent:", m.body));
chat.on("messages", (all) => render(all));
chat.on("typing", (t) => setTyping(t));
chat.on("connection", (s) => setStatus(s));

await chat.connect();
await chat.sendMessage("Hi, I need help with my order");

// Upload a file attachment (10 MB client-side guard):
// await chat.sendAttachment({ uri: fileUri, name: "photo.jpg", type: "image/jpeg", size: 482_133 });

chat.on(...) returns an unsubscribe function; call chat.disconnect() to stop the real-time stream and retain the conversation id.

In-app messages and content cards (OrbitInAppClient)

Owned in-app surfaces — assembled server-side into a per-visitor feed with assembleInAppFeed ordering rules kept in lockstep with the server, rendered locally, with impression / click / dismiss reported back. Dismissals persist across launches through the storage adapter.

import { OrbitInAppClient } from "@devotel-orbit/react-native";

const inApp = new OrbitInAppClient({
  publicKey: "dv_live_pk_…",
  apiUrl: "https://api.orbit.devotel.io",
  storage: AsyncStorage,
});

const feed = await inApp.fetchFeed();
await inApp.reportEvent("impression", feed.cards[0].id);
await inApp.dismiss(feed.cards[0].id);

Video rooms (OrbitVideoRoomClient)

Headless and engine-injected: your backend mints the room token server-side (POST /api/v1/video/rooms/:id/join) and hands the token plus server URL to the app. Wire a VideoRoomEngine over your native WebRTC stack (for example @livekit/react-native) — the package carries no hard WebRTC dependency. Inbound WebRTC video only.

import { OrbitVideoRoomClient } from "@devotel-orbit/react-native";

const room = new OrbitVideoRoomClient({
  token: roomToken,          // minted by your backend — never an API key
  serverUrl: roomServerUrl,
  engine: myVideoEngine,
});

room.on("trackSubscribed", ({ track, participant }) => render(track, participant));
room.on("caption", (caption) => showCaption(caption));
await room.join();

await room.joinBreakout("support-tier-2", { token: breakoutToken });
await room.leave();

Error handling

API failures surface as a typed OrbitApiError carrying the HTTP status and responseExcerpt; when the server sends a Retry-After hint it is parsed onto retryAfterSeconds (check "retryAfterSeconds" in err), so a 429 can be throttled instead of retried in a hot loop. Construction misuse — an empty key or a server-side secret key (dv_live_sk_… / dv_test_sk_…) — throws Error at the constructor.

import { OrbitApiError } from "@devotel-orbit/react-native";

try {
  await chat.sendMessage("Where is my order?");
} catch (err) {
  if (err instanceof OrbitApiError && err.status === 429) {
    // respect err.retryAfterSeconds before retrying
  } else {
    throw err;
  }
}

Only the publishable key (dv_live_pk_… / dv_test_pk_…) may be embedded in the app — the client refuses a secret key at construction, because anything bundled in a distributed binary is extractable by any user. Real-time updates use header-authenticated polling, so the key never lands in a URL log.

​React Native SDK

​Installation

​The useOrbitChat hook

​Headless chat client (OrbitChatClient)

​In-app messages and content cards (OrbitInAppClient)

​Video rooms (OrbitVideoRoomClient)

​Error handling

React Native SDK

Installation

The `useOrbitChat` hook

Headless chat client (OrbitChatClient)

In-app messages and content cards (OrbitInAppClient)

Video rooms (OrbitVideoRoomClient)

Error handling