End-to-end implementation guide

Business customer support integrations

Use this guide to create the business support account, connect customer signup and dashboard support actions, embed the website widget, and route every conversation into the OC agent dashboard.

Integration Checklist

Create business profile
Invite support agents
Generate integration key
Install widget or support link
Wire signup/dashboard handoff
Verify inbox, replies, and calls

Architecture

The complete customer support path

OC has two sides of the integration: your customer's product experience and your team's support dashboard. Customers can enter through a widget, a direct support page, or a handoff from your own dashboard. Agents answer everything from the OC inbox.

Business setup

Owner creates the tenant, domain, default channel, and support settings.

API key

A backend-only key authenticates support handoffs, conversations, and calls.

Customer entry

Widget, support link, or dashboard button shows the saved welcome message and sends the customer into support.

OC routing

OC creates or updates the customer and assigns an available support agent.

Agent inbox

Agents reply, show typing state, resolve, and escalate to audio or video inside OC dashboards.

Step 1

Create the business support account

Start from Business Setup. The setup form collects the business name and optional website domain.

What the setup creates

01
The setup request creates an active business tenant, makes the current user the owner, adds that user to the business support channel, and stores default support settings.

Why the domain matters

02
The domain becomes part of the allowed-domain configuration for the widget. Use the customer's production app domain for launch, and a staging domain for testing.
POST /api/business/setup
Content-Type: application/json
Cookie: next-auth session

{
  "businessName": "Acme Support",
  "domain": "https://app.acme.com"
}
After setup, configure the support team from Agents, the customer-facing welcome message from Settings, and the integration snippets from Widget Setup. The saved welcome message is returned by the public support config API and appears in the widget, WebChat, and business support page.

Step 2

Generate and store the integration key

Create an integration key from Widget Setup or the developer portal. The full key is only shown once. Store it in the customer's backend environment as OC_API_KEY.

Backend only

A
Never expose the full API key in custom browser code. Use it from server routes, jobs, and trusted backend services.

Widget snippet

B
The hosted widget reads the key from the script tag and opens OC's hosted webchat experience in an iframe.

Permissions

C
Generated keys include support read/write and call permissions needed by the guide's endpoints.

For normal websites, keep strict domain mode enabled and list each HTTPS origin in Widget Setup. For hotspot companies, router portals, captive portals, and local installs that do not have stable DNS, use key-only hotspot mode. In that mode OC validates the full widget key and does not require the parent page domain to match.

Step 3

Install the website widget

Use this path when the business wants chat, voice, and video available across a public website or product marketing pages.

<script
  src="https://oc.odixtec.net/widget.js"
  data-api-key="oc_live_your_full_key"
></script>

Where to paste it

01
Add the snippet before the closing bodytag or through the site's tag manager. The script creates the launcher and embeds/webchat?key=....

How to test it

02
Open the customer site, launch chat, register or sign in as a test customer, send a message, and watch for the conversation in the support inbox. Update the welcome message in Settings, reopen the widget, and confirm customers see the new text.
If a browser says weboc.odixtec.net refused to connect, first confirm the snippet contains the full generated key, not only the prefix. Then choose key-only hotspot mode when the parent page runs from changing DNS names, private IP addresses, router pages, or captive portal hosts.

Step 4

Connect signup and authenticated support handoff

Use support handoff when a known customer signs up or clicks Support inside the business app. Your backend sends customer identity to OC, OC upserts the customer, returns a short-lived URL, and the customer lands on the branded support page without creating a separate OC account.

// Your backend: call this after signup or when a logged-in customer clicks Support.
const response = await fetch("https://oc.odixtec.net/api/public/support/handoffs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.OC_API_KEY
  },
  body: JSON.stringify({
    customer: {
      externalUserId: customer.id,
      name: customer.name,
      email: customer.email,
      phone: customer.phone,
      metadata: {
        plan: customer.plan,
        accountUrl: customer.accountUrl
      }
    }
  })
});

const data = await response.json();
if (!data.success) throw new Error(data.error || "OC handoff failed");

return Response.redirect(data.redirectTo, 303);

Call the handoff endpoint from the customer's backend, not directly from their browser. The response includes redirectTo,supportUrl, andexpiresInSeconds: 600.

Step 5

Implement support inside the customer's dashboard

The simplest dashboard integration is a Support button that calls your backend and opens the returned OC support URL. This keeps authentication, customer identity, and API keys under server control.

// Example Next.js API route used by the customer app dashboard.
export async function POST(req: Request) {
  const session = await requireYourCustomerSession(req);

  const oc = await fetch("https://oc.odixtec.net/api/public/support/handoffs", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.OC_API_KEY!
    },
    body: JSON.stringify({
      customer: {
        externalUserId: session.user.id,
        name: session.user.name,
        email: session.user.email
      }
    })
  });

  const data = await oc.json();
  return Response.json({ supportUrl: data.redirectTo });
}

Redirect or new tab

Option 1
Use window.locationor open a new tab with the returned support URL. This gives the customer the full OC support page with chat, audio, and video controls.

Dashboard modal

Option 2
Open the returned support URL in a dashboard modal or iframe only if the customer app's security policy allows camera and microphone permissions.

Advanced embedded dashboard APIs

If the business wants a fully custom support panel inside its own product dashboard, create conversations and calls through backend routes, then render the customer's UI with the returned IDs and LiveKit connection details.

Create a conversation

const response = await fetch("https://oc.odixtec.net/api/public/support/conversations", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.OC_API_KEY
  },
  body: JSON.stringify({
    customer: {
      externalUserId: "cus_123",
      name: "Jane Customer",
      email: "jane@example.com"
    },
    message: {
      type: "text",
      text: "I need help with my order."
    }
  })
});

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

Start a support call

const response = await fetch("https://oc.odixtec.net/api/public/support/calls", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.OC_API_KEY
  },
  body: JSON.stringify({
    conversationId: "conversation_id_from_previous_step",
    type: "video"
  })
});

const { token, roomName, serverUrl, agent } = await response.json();

Step 6

Route work into the OC agent dashboard

Customer traffic from the widget, handoff page, and direct API arrives in the same support workflow. Your team does not need to watch multiple tools.

Conversations

Inbox
Agents open Support Inbox to view customer history, reply to messages, filter open/resolved items, and continue from the dashboard activity links. While an agent types, the customer chat shows a transient typing indicator.

Audio and video

Calls
Agents can start or join calls from an active conversation. The call room uses the existing LiveKit integration, shows the agent/customer name, includes a live timer, and stays connected to the conversation record.

Agent management

Team
Owners, admins, managers, and agents can be added from the business portal. OC's routing looks for active tenant members who are available.

Launch

Verify the integration before production

Run the complete path in staging with a real test customer, a real agent account, and the same dashboard entry points that production users will use.

Create a business profile from /business-admin/setup and confirm the business name appears in the sidebar.
Generate an integration key from /business-admin/widget and store the full key in the customer application's backend environment.
Choose strict domain mode for normal websites, or key-only hotspot mode for captive portals and local installs without stable DNS.
Set the OpenChat welcome message from /business-admin/settings and confirm the widget shows it.
Open the support channel link from Widget Setup and confirm the branded support page loads.
Trigger the signup handoff from a test customer and confirm the returned redirect opens /business/{businessId}/handoff.
Send a test message from the widget or support page and confirm it appears in /admin/support-inbox.
Type a reply from the agent inbox and confirm the customer sees the typing indicator.
Start an audio or video call and confirm the customer sees the agent name and live timer.

Common responses

Errors
401: missing or invalid X-API-Key.403: key does not include the required permission.429: rate limit exceeded for that key.

Production habits

Ops
Use separate staging and production keys, rotate keys during team changes, and revoke unused keys from the business admin API key screen.

Reference

Endpoint summary

These are the endpoints used by the integration flow. All API endpoints listed here use the X-API-Keyheader unless noted otherwise.

Method
Purpose
POST

/api/public/support/handoffs

Create a short-lived support link for a known customer.

POST

/api/public/support/conversations

Create a support conversation and first customer message.

POST

/api/public/support/calls

Start an audio or video support call for an existing conversation.

GET

/api/public/support/config

Read business branding, welcome message, and support settings for a widget or app.

POST

/api/business/admin/settings

Save the OpenChat welcome message and support preferences.

POST

/api/admin/support/conversations/[id]/typing

Update transient agent typing state for customer chat UI.

GET

/widget.js

Load the hosted website chat widget.