Get LiveKit Voice Token

Generate a LiveKit access token for real-time voice conversations with an agent. This token allows a client to join a WebRTC room and communicate with the agent using voice.

Endpoint

POST /api/v1/agents/{agentId}/livekit/token

Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header using the Bearer scheme.

Header Format:

Authorization: Bearer {PUBLIC_KEY}:{SECRET_KEY}

Request

Path Parameters

Parameter	Type	Required	Description
agentId	string (UUID)	Yes	The unique identifier of the agent

Headers

Header	Type	Required	Description
Authorization	string	Yes	Your API key in the format Bearer pk_xxx:sk_xxx
Content-Type	string	Yes	Must be application/json

Request Body

All fields are optional. If omitted, values are auto-generated.

Field	Type	Required	Description
roomName	string	No	Custom room name. Auto-generated if not provided
visitorId	string	No	Unique identifier for the visitor. Auto-generated if not provided
visitorName	string	No	Display name for the visitor. Defaults to "Visitor"

Example Request Body:

{
  "roomName": "support-room-001",
  "visitorId": "user-123",
  "visitorName": "John Doe"
}

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "roomName": "agentsgt-room-550e8400-org001-abc123def456",
  "serverUrl": "wss://your-livekit-server.livekit.cloud"
}

Response Fields

Field	Type	Description
token	string	JWT access token for LiveKit (valid for 1 hour)
roomName	string	The room name to connect to
serverUrl	string	The LiveKit server WebSocket URL

Token Permissions

The generated token grants the following permissions:

Permission	Description
roomJoin	Can join the specified room
canPublish	Can publish audio/video tracks
canSubscribe	Can subscribe to other participants' tracks
canPublishData	Can send data messages in the room

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Unauthorized"
}

{
  "error": "invalid_key",
  "message": "Invalid API key"
}

404 Not Found

{
  "error": "not_found",
  "message": "Agent not found"
}

500 Internal Server Error

{
  "error": "config_error",
  "message": "Voice chat not available"
}

{
  "error": "internal_error",
  "message": "Failed to generate token"
}

Example Usage

cURL

curl -X POST https://agentsgt.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/livekit/token \
  -H "Authorization: Bearer pk_1234567890abcdef:sk_abcdef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorName": "John Doe"
  }'

JavaScript (Fetch API)

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://agentsgt.com/api/v1/agents/${agentId}/livekit/token`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${publicKey}:${secretKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      visitorName: 'John Doe'
    })
  }
);

const data = await response.json();
console.log('Token:', data.token);
console.log('Room:', data.roomName);
console.log('Server:', data.serverUrl);

// Use with LiveKit client SDK
// import { Room } from 'livekit-client';
// const room = new Room();
// await room.connect(data.serverUrl, data.token);

Python (Requests)

import requests

public_key = 'pk_1234567890abcdef'
secret_key = 'sk_abcdef1234567890'
agent_id = '550e8400-e29b-41d4-a716-446655440000'

headers = {
    'Authorization': f'Bearer {public_key}:{secret_key}',
    'Content-Type': 'application/json'
}

response = requests.post(
    f'https://agentsgt.com/api/v1/agents/{agent_id}/livekit/token',
    headers=headers,
    json={
        'visitorName': 'John Doe'
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"Token: {data['token'][:50]}...")
    print(f"Room: {data['roomName']}")
    print(f"Server: {data['serverUrl']}")
else:
    print(f"Error: {response.status_code} - {response.json()}")

Node.js (Axios)

const axios = require('axios');

const publicKey = 'pk_1234567890abcdef';
const secretKey = 'sk_abcdef1234567890';
const agentId = '550e8400-e29b-41d4-a716-446655440000';

axios.post(`https://agentsgt.com/api/v1/agents/${agentId}/livekit/token`, {
  visitorName: 'John Doe'
}, {
  headers: {
    'Authorization': `Bearer ${publicKey}:${secretKey}`,
    'Content-Type': 'application/json'
  }
})
  .then(response => {
    const { token, roomName, serverUrl } = response.data;
    console.log(`Room: ${roomName}`);
    console.log(`Server: ${serverUrl}`);
    // Connect to LiveKit room with the token
  })
  .catch(error => {
    console.error('Error:', error.response?.data || error.message);
  });

Notes

• Tokens are valid for 1 hour after generation
• If no roomName is provided, one is auto-generated in the format: agentsgt-room-{agentId}-{orgId}-{randomId}
• The room name format is used by the AV worker for billing and routing purposes
• The API key's last_used_at timestamp is updated when this endpoint is called
• Voice chat requires LiveKit to be configured on the server side. If not configured, a 500 error with config_error is returned
• Use the LiveKit client SDK (livekit-client) to connect to the room with the generated token

Related Endpoints

• Get Agent Details - Get agent configuration
• Send Message - Text-based messaging alternative
• Chat - Streaming text chat alternative