Skip to main content

Add a spoken conversation to your app (Preview)

Section: DOC-MA-voice-media#voice-sessions-preview.

Deployment prerequisites

Voice sessions require an enabled voice service and a registered agent. Confirm availability for your account and obtain the supported agent name before starting a session.

Let a user speak with the assistant in an existing conversation. Create a real-time voice session, then join its room from your client using the returned room URL and token. The platform provisions the room and joins a voice agent tied to the conversation's history and agent profile.

Before starting, have a conversation ID, the deployment's registered agent name, user-scoped credentials and a client capable of joining the room provider. Treat recording as a separate user choice; use disabled recording unless the user has opted in. This recipe starts with a new room and the registered agent's configured voice.

Step 1: Start the voice session for the existing thread​

Section: DOC-MA-voice-media#create-a-voice-session.

Replace support-chat-001 with the existing thread ID and my-voice-agent with the registered name supplied for your deployment. Call this once for the user's intent to start a session; if its response is lost, do not create more sessions just to discover whether the first one started.

curl -X POST https://api.travila.ai/api/v1/llm/create-daily-session \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "agentName": "my-voice-agent",
  "createDailyRoom": true,
  "dailyRoomProperties": {
    "enableRecording": "RECORDING_MODE_DISABLED"
  }
}'

Reference: Create a voice session (in progress) · Request fields.

Keep the returned session ID and join details. Session creation starts the room/agent setup; the next step checks that both are usable.

Step 2: Join the room and confirm the exchange​

Section: DOC-MA-voice-media#response.

Use the returned room name with your configured Daily domain and give the room SDK the returned meeting token. Wait for room connection and the agent-ready lifecycle signal before inviting the user to speak.

{
  "session": {
    "sessionId": "sess_abc123",
    "agentName": "my-voice-agent",
    "dailyRoom": "travila-abc123",
    "dailyToken": "eyJ...",
    "startedAt": "2026-08-17T10:00:00Z",
    "userData": {
      "fields": {
        "displayName": "Alex"
      }
    },
    "dailyRoomProperties": {
      "exp": "1786964400"
    },
    "dailyMeetingTokenProperties": {
      "isOwner": false
    }
  }
}

Reference: Create a voice session (in progress) · Response fields.

Voice transcripts and message history

Use conversation history to display the saved exchange. Do not automatically submit every transcript fragment again through send-message, which could duplicate a turn already saved by the voice session. If a session ends before a reply, refresh conversation state and keep any unsent draft separate.

Ask one question, listen for the reply, then read the same conversation's history. Finished result: the client connected to the expected room, the agent was ready, and the saved exchange is visible in the original thread. Keep an unanswered or unsaved exchange unresolved rather than treating session creation as a successful conversation.

When the user leaves, stop local audio capture and leave through the room client's supported lifecycle. If the session ends unexpectedly, refresh conversation state, preserve any unsent draft and explain the interruption. Local disconnect is not proof that every remote action stopped.

Variant: associate app metadata with the session​

Section: DOC-MA-voice-media#request-fields.

For an application that displays the speaker’s name beside the session, put that display information in userData.fields when creating the session and read it back from the response. Treat it as client metadata, not authentication.

The main recipe creates a new room. If your deployment uses a pre-existing room, follow its supported join setup and the session request reference; do not create another room merely to recover a lost join response.

Variant: select supported voice or audio settings​

Section: DOC-MA-voice-media#agent-config-socayoconfig.

Use the registered agent’s settings for the first conversation. To change the spoken experience:

  1. Choose a voice, language, provider and audio settings supported by your deployment.
  2. Apply those choices through socayoConfig using the session configuration reference.
  3. Repeat the connect, speak and saved-history check with the actual client audio path.

Inspect readiness errors and the resulting audio. An accepted setting does not prove the voice or provider is provisioned. Avatar/video and sample-rate options require their corresponding deployment support.

Variant: limit room lifetime, participants and recording​

Section: DOC-MA-voice-media#room-properties-dailyroomproperties.

Before inviting the user, choose the room lifetime, participant limit and permitted processing region through dailyRoomProperties. Set initial audio/video state for the user’s expected entry experience and verify the room behaves accordingly.

Keep recording disabled unless the user explicitly opts in. Permission to speak is not permission to retain a recording; the main request uses RECORDING_MODE_DISABLED. Review recording choices on the meeting token as well as the room before enabling them.

Separate recipe: dictate a draft without starting a voice agent​

Section: DOC-MA-voice-media#speech-to-text-tokens-preview.

Deployment prerequisite

Speech-to-text token issuance must be enabled for your account. The endpoint returns an error when the required service credentials are unavailable.

To let your client transcribe audio without exposing your backend API key, mint a short-lived speech-to-text token. The token is a single-purpose STT grant — the client calls Cartesia's STT API directly with it; your key never reaches the client.

curl -X POST https://api.travila.ai/api/v1/llm/stt-token \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Reference: Mint a speech-to-text token (in progress) · Request fields.

Response:

{
  "token": "stt_eph_...",
  "expiresInSeconds": 600
}

Reference: Mint a speech-to-text token (in progress) · Response fields.

Use the returned token lifetime and account for time elapsed during recording.

Use this path for a user recording a message draft. It does not create a voice room or automatically send an assistant turn. Present the resulting transcript for review before using the normal message-send flow.

Section: DOC-MA-voice-media#recommended-client-flow.

  1. Mint for an explicit recording — obtain the token when needed and account for its expiry during a long recording. Token issuance and transcription are subject to permissions, limits and cost.
  2. Transcribe the clip — send the audio to Cartesia's STT API using the token. The token is scoped to speech-to-text only; it cannot be used for anything else.
  3. Handle failure explicitly — if a permitted local recognizer is available, offer it; otherwise preserve the recording/draft according to the user's choices and report the failure. Do not silently claim fallback succeeded. A late final transcript must not overwrite user edits.

Your backend API key stays server-side throughout.

Finished result: the user has an editable transcript, or a visible transcription failure with their draft handled according to their choice. Send it as a new message only after the user chooses to send. An STT token response alone is not a transcription result.

Upcoming recipe: keep a spoken session on local infrastructure​

Status: Upcoming — not yet available.

Section: DOC-MA-voice-media#local-voice-sessions

Use this path when the conversation’s audio must remain on supported local infrastructure. Select a supported language, voice and deployment capacity; keep hosted fallback disabled when audio must stay local. Choose recording permission separately.

  1. Start the local session and confirm readiness before accepting speech.
  2. Allow thoughtful pauses, then process the completed utterance once.
  3. On deliberate interruption, stop playback and keep late audio from restarting it.
  4. Inspect the saved exchange or the explicit unavailable result when local capacity is exhausted.

Finished result: a local spoken exchange or a visible failure that has not silently routed audio to a hosted provider.

Local endpoints and deployment instructions are not yet available. The hosted session and speech-to-text token instructions above retain their current prerequisites.

Section: DOC-MA-voice-media#related.

Document ID: DOC-MA-voice-media. Section identities and revisions.