agents Checked

const conversation = await Conversation.startSession({

agentId: "your-agent-id",

environment: "staging",

onMessage: (msg) => console.log("Agent:", msg.message),

onUserTranscript: (t) => console.log("User:", t.message),

onError: (e) => console.error(e)

});

**React Hook:**

import { useConversation } from "@elevenlabs/react";

const conversation = useConversation({ onMessage: (msg) => console.log(msg) });

// Get a signed URL for the target environment from your backend, then:

await conversation.startSession({ signedUrl: token });

## Configuration

| Provider | Models |
|----------|--------|
| OpenAI | `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
| Anthropic | `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-haiku` |
| Google | `gemini-3.1-flash-lite-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, `gemini-2.0-flash-lite` |
| ElevenLabs | `glm-45-air-fp8`, `qwen3-30b-a3b`, `gpt-oss-120b` |
| Custom | `custom-llm` (bring your own endpoint) |

Use `GET /v1/convai/llm/list` to inspect the current model catalog, including deprecation state, token/context limits, and capability flags such as image-input support.

**Popular voices:** `JBFqnCBsd6RMkjVDRZzb` (George), `EXAVITQu4vr4xnSDxMaL` (Sarah), `onwK4e9ZLuTAKqWW03F9` (Daniel), `XB0fDUnXU5powFXDhCwa` (Charlotte)

**Turn eagerness:** `patient` (waits longer for user to finish), `normal`, or `eager` (responds quickly)

See [Agent Configuration](references/agent-configuration.md) for all options.

## Tools

Extend agents with webhook, client, or built-in system tools. Tools are defined inside `conversation_config.agent.prompt`:

Workspace environment variables can resolve per-environment server tool URLs, headers, and auth connections, and runtime system variables such as `{{system__conversation_history}}` can pass full conversation context into tool calls when needed.

"prompt": {

"prompt": "You are a helpful assistant that can check the weather.",

"llm": "gemini-2.0-flash",

"tools": [

Webhook: server-side API call

{"type": "webhook", "name": "get_weather", "description": "Get weather",

"api_schema": {"url": "https://api.example.com/weather", "method": "POST",

"request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}},

Client: runs in the browser

{"type": "client", "name": "show_product", "description": "Display a product",

"parameters": {"type": "object", "properties": {"productId": {"type": "string"}}, "required": ["productId"]}}

],

"built_in_tools": {

"end_call": {},

"transfer_to_number": {"transfers": [{"transfer_destination": {"type": "phone", "phone_number": "+1234567890"}, "condition": "User asks for human support"}]}

}

}

**Client tools** run in browser:

clientTools: {

show_product: async ({ productId }) => {

document.getElementById("product").src = /products/${productId};

return { success: true };

}

}

See [Client Tools Reference](references/client-tools.md) for complete documentation.

## Widget Embedding

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>

<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

Customize with attributes: `avatar-image-url`, `action-text`, `start-call-text`, `end-call-text`.

See [Widget Embedding Reference](references/widget-embedding.md) for all options.

## Outbound Calls

Make outbound phone calls using your agent via Twilio integration:

### Python

response = client.conversational_ai.twilio.outbound_call(

agent_id="your-agent-id",

agent_phone_number_id="your-phone-number-id",

to_number="+1234567890",

call_recording_enabled=True

)

print(f"Call initiated: {response.conversation_id}")

### JavaScript

const response = await client.conversationalAi.twilio.outboundCall({

agentId: "your-agent-id",

agentPhoneNumberId: "your-phone-number-id",

toNumber: "+1234567890",

callRecordingEnabled: true,

});

### cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \

-H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \

-d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890", "call_recording_enabled": true}'

See [Outbound Calls Reference](references/outbound-calls.md) for configuration overrides and dynamic variables.

## Managing Agents

### Using CLI (Recommended)

List agents and check status

elevenlabs agents list

elevenlabs agents status

Import agents from platform to local config

elevenlabs agents pull # Import all agents

elevenlabs agents pull --agent <agent-id> # Import specific agent

Push local changes to platform

elevenlabs agents push # Upload configurations

elevenlabs agents push --dry-run # Preview changes first

Add tools

elevenlabs tools add-webhook "Weather API"

elevenlabs tools add-client "UI Tool"

### Project Structure

The CLI creates a project stru