Skip to navigation

Start a voice or text session with the expert in your app

Returns a LiveKit URL and token; the expert joins the room. Voice is billed as a web voice call, text like chat (per token); both use credits and the concurrent-call cap. A text session’s token cannot publish audio. The page’s client tools and the session’s guide come back too.

A publishable key (Authorization: Bearer rydhm_pk_…), from one of the key’s allowed websites: the Origin header must be on its list. Never a secret API key (401 secret_key_not_allowed). Rate limited per visitor and per key.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
modeenumRequired

voice: talk (the microphone and the expert’s voice). text: type, with no audio either way, billed like chat. One of the bubble’s modes (400 mode_not_available otherwise).

Allowed values:
userobjectOptional

Who the page’s user is. id with hash (hex HMAC-SHA256 of id under your workspace’s user-signing secret, computed on your server) is a signed user; id alone, or anonymousId, is stored as anon_ and the id.

contextmap from strings to anyOptional

Your app’s JSON context (at most 4 KB).

guideIdstringOptional

Start (or resume) this guide.

languagestringOptional

One of the expert’s languages (400 otherwise).

pageobjectOptional
toolslist of maps from strings to anyOptional

Custom tools the page registered: { name (2–41 lowercase letters, digits, _), description, parameters (a JSON Schema object, at most 4 KB) }.

previewstringOptional

A preview or teach token (rydhm_pv_…): needed while the coach is in testing.

Response

OK
sessionIdstring
A UUID.
livekitobject
expertmap from strings to any
As in bootstrap.
clientToolslist of maps from strings to any
pageMaplist of maps from strings to any
guidemap from strings to any or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error