Channels & Embeds

Browser voice calls (WebRTC)

Let visitors talk to your OnCore assistant straight from a web page.

Embedded WebRTC calls let your end-users talk to a OnCore assistant from a web browser — no phone required. The flow has two halves:

Your backend calls POST /webrtc-call/connect with your API key and gets back short-lived connection details.
Your browser code uses those details to join the call with the livekit-client library.

Keep the API key server-side

The tenant API key is a server-side secret. Call /webrtc-call/connect from your backend, never from browser JavaScript — if you embed it in client code, any visitor can read it from DevTools and use your account.

Step 1 — Connect (backend)#

phoneNumber must be E.164 and assigned to one of your tenant's assistants (configured in the OnCore dashboard). The assistant that answers is the one that owns that number.

Terminal

curl -X POST https://core-api.heysadie.ai/webrtc-call/connect \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15555550123" }'

Body field	Required	Description
`phoneNumber`	yes	E.164 number owned by your tenant and assigned to an assistant
`firstMessage`	no	Per-call greeting (max 500 characters) that overrides the assistant's saved first message for this WebRTC call only. Omit to use the saved greeting

Success — `200 OK`#

Response

{
  "token": "eyJhbGciOi...",
  "url": "wss://...",
  "room": "webrtc-<uuid>"
}

Return token and url to your browser. Do not send your API key to the browser.

Token TTL

The token has a 10-minute TTL — that's the join window, not the maximum call duration. Already-joined participants stay connected until the call ends.

Step 2 — Join the call (browser)#

In the browser, connect via livekit-client:

browser.js

const room = new LivekitClient.Room();
await room.connect(url, token);
await room.localParticipant.setMicrophoneEnabled(true);
// visitor is now talking to the assistant

Errors#

Status	Cause
`400`	`phoneNumber` missing or not E.164
`401`	Missing or invalid `Authorization: ApiKey <token>` header
`404`	Phone unknown or not in your tenant — returns the bare `{ "error": "not_found" }` body (see Errors)
`500`	Transient OnCore failure — retry once

The 404 body is deliberately identical for unknown, cross-tenant, and deleted numbers, so it cannot be used to enumerate which numbers exist.

Webhooks#

WebRTC calls fire the same webhooks as phone calls: an assistant-request event when the call starts (with call_source: "webrtc") and an end-of-call report when it finishes.

See the API reference for the full endpoint specification.

PreviousWhatsApp NextEmbedded web chat