Skip to main content

​
POST /api/voice/token

Get an ElevenLabs ConvAI conversation token for voice interaction. Authentication: Required

​
Request Body

​
customAgentId
string
Custom ElevenLabs agent ID (overrides ELEVENLABS_AGENT_ID)
​
customApiKey
string
Custom ElevenLabs API key (overrides ELEVENLABS_API_KEY)

​
Response

​
allowed
boolean
Whether voice is available
​
token
string
ElevenLabs conversation token (if allowed)
​
agentId
string
ElevenLabs agent ID used (if allowed)
​
error
string
Error message if not allowed

​
Example: Using Default Configuration

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}' \
  http://127.0.0.1:3006/api/voice/token

{
  "allowed": true,
  "token": "el_token_abc123xyz...",
  "agentId": "el_agent_456"
}

​
Example: Using Custom Agent

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customAgentId": "el_agent_custom",
    "customApiKey": "sk_custom_key"
  }' \
  http://127.0.0.1:3006/api/voice/token

{
  "allowed": true,
  "token": "el_token_xyz789abc...",
  "agentId": "el_agent_custom"
}

​
Error Response

{
  "allowed": false,
  "error": "ElevenLabs API key not configured"
}

​
Errors

  • 400 - Invalid request body or ElevenLabs API key not configured
  • 500 - Failed to create agent or get token from ElevenLabs

​
Configuration

Voice functionality requires ElevenLabs configuration:

​
Environment Variables

# Required
ELEVENLABS_API_KEY=sk_your_api_key

# Optional (auto-created if not set)
ELEVENLABS_AGENT_ID=el_agent_id

​
Agent Auto-Creation

If ELEVENLABS_AGENT_ID is not set, the hub will:
  1. Search for an existing “Hapi Voice Assistant” agent
  2. If not found, create a new agent automatically
  3. Cache the agent ID for future requests
The agent is configured with:
  • Name: “Hapi Voice Assistant”
  • Voice: Professional assistant voice
  • Behavior: Help with coding tasks

​
Custom Agent Configuration

You can use a custom agent by:
  1. Creating an agent in the ElevenLabs dashboard
  2. Passing customAgentId and customApiKey in the request
OR
  1. Setting ELEVENLABS_AGENT_ID environment variable

​
Using the Token

Once you have a conversation token, use it with the ElevenLabs ConvAI SDK: 
import { Conversation } from '@11labs/client'

const response = await fetch('/api/voice/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + jwtToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({})
})

const { token, agentId } = await response.json()

const conversation = await Conversation.startSession({
  signedUrl: token
})

// Start voice interaction
await conversation.startSession()

​
Token Lifetime

ElevenLabs conversation tokens are short-lived and should be:
  • Requested when starting a voice session
  • Not cached or stored long-term
  • Refreshed if the session expires

​
Voice Assistant Features

The Hapi Voice Assistant can help with:
  • Explaining code in your sessions
  • Answering questions about your project
  • Providing coding guidance
  • Reading session summaries aloud

​
Integration with Sessions

The voice assistant has access to:
  • Session metadata
  • Recent messages
  • Project context
  • Git status
This allows natural voice interaction with your coding sessions.

Build docs developers (and LLMs) love

Get started for freeTalk to us