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.

New to this? Browser calling explains what it does and when to use it, without the API detail.

PreviousGive an assistant a tool NextEmbedded web chat