Quickstart

Two calls against the Elizon Public API get you a LiveKit wsUrl and token — everything a client SDK needs to connect.

Step 1: Discover agents

List the agents in your organization that have a voice configuration:

curl -H "X-API-Key: elz_your_key_here" \
  https://api.elizon.com/api/v1/voice-agents

{
  "data": [
    {
      "agentId": "3f9c1a2e-...",
      "name": "Support Bot",
      "description": "Handles Tier 1 support tickets",
      "voiceConfigId": "8b1e0c4a-...",
      "voiceProvider": "elevenlabs",
      "sttProvider": "google",
      "projectId": null
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Copy an agentId from the response — you'll use it in the next step.

Step 2: Start a session

curl -X POST https://api.elizon.com/api/v1/voice-agents/3f9c1a2e-.../sessions \
  -H "X-API-Key: elz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"participantIdentity": "user-123", "end_user_ref": "9f2a1c...e0"}'

{
  "sessionId": "a1c4...",
  "wsUrl": "wss://lk.elizon.ai",
  "token": "eyJhbGciOi...",
  "agentId": "3f9c1a2e-...",
  "voiceConfigId": "8b1e0c4a-...",
  "end_user_ref": "9f2a1c...e0"
}

participantIdentity is any string that identifies the caller in your own system (a user ID, session ID, etc.) — it's used as the LiveKit participant identity.

Attributing cost to your own end users

end_user_ref is optional. If you're building on top of Elizon voice and want to attribute each session's cost to your own downstream customer (for their billing input), pass an opaque identifier for that customer:

{ "participantIdentity": "user-123", "end_user_ref": "9f2a1c...e0" }

end_user_ref must be opaque — never a raw email address or name. Accepted formats:

• A salted hash: sha256("user@example.com" + salt)
• A UUID you generate per customer: uuid-v4
• Your own internal customer ID: customer_12345

A value containing @ (i.e. a raw email) is rejected:

{
  "error": "end_user_ref_must_be_opaque",
  "message": "end_user_ref must be an opaque identifier or a salted hash — never a raw email or name"
}

— returned as 422 Unprocessable Entity. The maximum length is 512 characters.

When end_user_ref is omitted, the session is attributed to your API key instead.

Next: the wsUrl and token above are everything a LiveKit client SDK needs to join the call. See SDK Integration for how to connect from your platform.