Create a voice session

Call POST /v1/sessions from your server with a key that has sessions:create. Supply a fresh Idempotency-Key for each intended conversation; reuse it and the same body for retries.

curl --request POST 'https://api.livefaces.ai/v1/sessions' \
  --header "Authorization: Bearer $LIVEFACES_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $SESSION_ATTEMPT_ID" \
  --data '{
    "voice_id": "11111111-1111-4111-8111-111111111111",
    "participant_identity": "customer-123",
    "prompt": "Help the customer describe their order issue. Ask for the order number."
  }'

Set the environment variables on your server and replace the example voice UUID with one available to your organization. Keep the attempt ID stable if you retry.

Field	Use
`voice_id`	Required voice UUID.
`face_id`	Optional compatible face UUID; omit or use `null` for audio only.
`prompt`	Optional instructions, up to 32,000 characters. Omit or use `null` for the voice’s defaults.
`greeting`	Omit for the standard greeting; `null` disables it. Custom text is limited to 500 characters; delivery depends on the selected voice.
`participant_identity`	Participant identifier, 1–100 characters; defaults to `browser`.
`mcps`	Optional selection of up to eight MCP connections and their tools.
`tags`, `metadata`	Optional application labels and context. Do not include secrets.

Optional tool selection

Add this to the request body to select a registered connection and named tools:

{
  "mcps": [
    {
      "mcp_id": "22222222-2222-4222-8222-222222222222",
      "tools": ["lookup_order"]
    }
  ]
}

Use your actual connection UUID and discovered tool names. Select only the tools the conversation needs. The fragment above extends the request; voice_id is still required.

Response

A successful request returns 201 and a session containing:

{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "active",
  "room_name": "example-room",
  "livekit_url": "wss://YOUR_LIVEKIT_HOST",
  "participant_token": "SHORT_LIVED_PARTICIPANT_TOKEN",
  "created_at": "2026-01-01T12:00:00Z",
  "started_at": "2026-01-01T12:00:01Z",
  "ended_at": null,
  "workflow_run_id": null
}

This is an illustrative response; use the returned URL and token. Check that a token is present before connecting. Save id for status checks, token refresh, and ending the session.

Get started

Console

Workflows

Session API

API reference

Help

Create a voice session

Optional tool selection

Response

​Optional tool selection

​Response

Optional tool selection

Response