Mobile Support

Use this page when you want customers to open chat inside your mobile app. These examples target Widget 5.0.0; check version availability before using the pinned script.

Build one support page, load it in a WebView, and let OpenCX handle the conversation.

Rendering chat with your own React Native components instead of a WebView? Use the headless packages.

What You Are Building

Add a Support screen to your app. That screen opens a WebView pointed at a small HTTPS page with the OpenCX widget already open.

Implementation Steps

Create a support page

Host a page like https://app.example.com/mobile-support. Your app will load this URL in a WebView.

Add the widget

Give the page a real viewport height. Without this, the widget can load but the chat input may sit too high on the screen.

support.html

<style>
  html,
  body {
    margin: 0;
    width: 100%;
    height: 100%;
    overflow: hidden;
  }

  #opencx-root {
    width: 100vw;
    height: 100dvh;
  }
</style>

<script defer src="https://unpkg.com/@opencx/[email protected]/dist-embed/script.js"></script>
<script>
  window.addEventListener('DOMContentLoaded', () => {
    initOpenScript({
      token: '<WIDGET_TOKEN>',
      inline: true,
      isOpen: true,
      router: {
        chatScreenOnly: true,
        goToChatIfNoSessions: true,
      },
      theme: {
        screens: {
          chat: {
            width: '100vw',
            height: '100vh',
          },
        },
      },
    });
  });
</script>

Open the page from your app

Add a Support button, Help Center row, or Account menu item that opens the WebView.

Test the mobile flow

Open the app, start a chat, close the screen, reopen it, and confirm the conversation still feels natural.

Open The WebView

React Native
iOS
Android

Install react-native-webview first if your app does not already use it.

SupportScreen.tsx

import { WebView } from 'react-native-webview';

export function SupportScreen({ supportUrl }: { supportUrl: string }) {
  return (
    <WebView
      source={{ uri: supportUrl }}
      javaScriptEnabled
      domStorageEnabled
      allowsInlineMediaPlayback
    />
  );
}

SupportViewController.swift

import UIKit
import WebKit

final class SupportViewController: UIViewController {
  private let webView = WKWebView()

  override func viewDidLoad() {
    super.viewDidLoad()
    view = webView

    let url = URL(string: "https://app.example.com/mobile-support")!
    webView.load(URLRequest(url: url))
  }
}

SupportActivity.kt

import android.os.Bundle
import android.webkit.WebView
import androidx.appcompat.app.AppCompatActivity

class SupportActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val webView = WebView(this)
    setContentView(webView)

    webView.settings.javaScriptEnabled = true
    webView.settings.domStorageEnabled = true
    webView.loadUrl("https://app.example.com/mobile-support")
  }
}

Recognize Signed-In Customers

If customers sign in to your app, pass a verified contact token to the widget. This lets the same customer see their support history across devices.

Request a token from your backend

Your backend calls OpenCX with your org API key. Do not call this from the mobile app.

const response = await fetch('https://api.open.cx/widget/authenticate-user', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENCX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: user.email,
    name: user.name,
    customData: {
      customerId: user.id,
      plan: user.plan,
    },
  }),
});

const { token } = await response.json();

Pass the token into the widget

Add the token to your support page config. Your backend can render it into the page or your app can request it before opening the WebView.

initOpenScript({
  token: '<WIDGET_TOKEN>',
  inline: true,
  isOpen: true,
  user: {
    token: '<AUTHENTICATED_CONTACT_TOKEN>',
    externalId: '<CURRENT_ACCOUNT_ID>',
  },
});

Never put your OpenCX API key in the mobile app. Keep it on your backend.

Send Useful Context

Give support enough context to help without asking the customer to repeat themselves.

initOpenScript({
  token: '<WIDGET_TOKEN>',
  inline: true,
  isOpen: true,
  context: { screen: 'order-details', orderId: 'ORD-123' },
  sessionCustomData: {
    platform: 'ios',
    appVersion: '8.4.0',
    accountId: 'acct_123',
  },
});

Keep this clean. Send account IDs, plan names, app version, and the screen the customer came from. Do not send secrets or device identifiers.

Handoff and native notifications

Human replies remain in the same widget session. There is no onHandoff widget option. hooks.onMessageReceived reports new messages and is not an immediate transfer event; do not use it to claim that a transfer has just completed. For a native banner on a delivered human reply, check message.type === 'AGENT' in that hook and send a small event through your WebView bridge. Validate bridge messages and the loaded page origin in your native app. Keep tokens and message content out of bridge events unless your application requires them. When switching accounts or logging out, update the verified widget identity and clear the previous native account’s state. Renew expiring tokens through your backend; see JWT renewal.

Mobile Checklist

Check	Why it matters
`inline: true`	Makes the widget feel like the screen, not a website popup.
`isOpen: true`	Opens chat immediately.
`router.chatScreenOnly`	Skips the website-style session browser.
Verified `user.token`	Keeps signed-in customers tied to the right contact.
Server-side API key	Keeps your OpenCX credentials out of the app bundle.

Install Widget

Web, React, and headless install paths.

Authentication

Verified contact tokens and history access.

Configuration

Inline mode, routing, theme, and context options.

Headless

Build custom rendering when WebView is not enough.

Overview

AI Chat Widget

AI X (Twitter) Support

AI App Review Support

AI WhatsApp Support

AI SMS Support

Phone & Telephony

AI Email Support

AI Actions

Resources

What You Are Building

Implementation Steps

Open The WebView

Recognize Signed-In Customers

Send Useful Context

Handoff and native notifications

Mobile Checklist

Install Widget

Authentication

Configuration

Headless

​What You Are Building

​Implementation Steps

​Open The WebView

​Recognize Signed-In Customers

​Send Useful Context

​Handoff and native notifications

​Mobile Checklist

​Related Documentation

Install Widget

Authentication

Configuration

Headless

What You Are Building

Implementation Steps

Open The WebView

Recognize Signed-In Customers

Send Useful Context

Handoff and native notifications

Mobile Checklist

Related Documentation