elevenlabs-webhook-nodejs 1.0.0

package/elevenlabs-convai-api-reference.md

@@ -0,0 +1,1171 @@
+# ElevenLabs Conversational AI API Reference
+
+> Extracted from [ElevenLabs Documentation](https://elevenlabs.io/docs/api-reference)
+> Base URL: `https://api.elevenlabs.io`
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Agents](#agents)
+  - [List Agents](#list-agents)
+  - [Create Agent](#create-agent)
+  - [Get Agent](#get-agent)
+  - [Update Agent](#update-agent)
+  - [Delete Agent](#delete-agent)
+  - [Get Agent Link](#get-agent-link)
+  - [Simulate Conversation](#simulate-conversation)
+  - [Stream Simulate Conversation](#stream-simulate-conversation)
+  - [Calculate LLM Usage](#calculate-llm-usage)
+- [Conversations](#conversations)
+  - [List Conversations](#list-conversations)
+  - [Get Conversation Details](#get-conversation-details)
+  - [Delete Conversation](#delete-conversation)
+  - [Get Conversation Audio](#get-conversation-audio)
+  - [Send Conversation Feedback](#send-conversation-feedback)
+  - [Get Conversation Token (WebRTC)](#get-conversation-token-webrtc)
+  - [Get Signed URL](#get-signed-url)
+- [Batch Calling](#batch-calling)
+  - [Submit Batch Calling Job](#submit-batch-calling-job)
+  - [List Workspace Batch Calling Jobs](#list-workspace-batch-calling-jobs)
+  - [Get Batch Call Information](#get-batch-call-information)
+  - [Cancel Batch Calling Job](#cancel-batch-calling-job)
+  - [Retry Batch Calling Job](#retry-batch-calling-job)
+
+---
+
+## Authentication
+
+All endpoints accept an optional `xi-api-key` header for authentication.
+
+```
+xi-api-key: YOUR_API_KEY
+```
+
+---
+
+## Agents
+
+### List Agents
+
+Returns a list of your agents and their metadata.
+
+```
+GET /v1/convai/agents
+```
+
+#### Query Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `page_size` | integer | No | 30 | Maximum agents to return (max 100) |
+| `search` | string | No | — | Filter agents by name |
+| `archived` | boolean | No | — | Filter by archived status |
+| `show_only_owned_agents` | boolean | No | false | Omit agents shared with you by others |
+| `sort_direction` | string | No | — | `asc` or `desc` |
+| `sort_by` | string | No | — | `name` or `created_at` |
+| `cursor` | string | No | — | Pagination cursor from previous response |
+
+#### Response `200`
+
+```json
+{
+  "agents": [
+    {
+      "agent_id": "string",
+      "name": "string",
+      "tags": ["string"],
+      "created_at_unix_secs": 0,
+      "access_info": {
+        "is_creator": true,
+        "creator_name": "string",
+        "creator_email": "string",
+        "role": "admin | editor | commenter | viewer"
+      },
+      "last_call_time_unix_secs": 0,
+      "archived": false
+    }
+  ],
+  "next_cursor": "string",
+  "has_more": false
+}
+```
+
+---
+
+### Create Agent
+
+Create an agent from a config object.
+
+```
+POST /v1/convai/agents/create
+```
+
+#### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `conversation_config` | ConversationalConfig | **Yes** | Conversation configuration for the agent |
+| `platform_settings` | AgentPlatformSettings | No | Non-conversation platform settings |
+| `workflow` | AgentWorkflow | No | Conversation flow definition |
+| `name` | string | No | Agent name for easier discovery |
+| `tags` | string[] | No | Classification and filtering tags |
+
+#### ConversationalConfig
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `asr` | AsrConversationalConfig | Transcription: provider, quality, audio format, keywords |
+| `turn` | TurnConfig | Turn detection: timeout, eagerness, spelling patience |
+| `tts` | TtsConversationalConfig | TTS: model, voice, stability, speed, similarity |
+| `conversation` | ConversationConfig | Event config, monitoring, max duration |
+| `language_presets` | object | Language-specific overrides |
+| `vad` | VadConfig | Voice activity detection |
+| `agent` | AgentConfig | First message, language, prompt, dynamic variables |
+
+#### AgentConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `first_message` | string | `""` | Initial agent greeting |
+| `language` | string | `"en"` | Language for ASR and TTS |
+| `hinglish_mode` | boolean | `false` | Hindi-English mixed mode |
+| `dynamic_variables` | DynamicVariablesConfig | — | Runtime variable placeholders |
+| `disable_first_message_interruptions` | boolean | `false` | Prevent interruptions during greeting |
+| `prompt` | PromptAgentConfig | — | LLM prompt and tool configuration |
+
+#### PromptAgentConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `prompt` | string | — | Agent system prompt |
+| `llm` | enum | — | Model: `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4`, `gemini-2.5-flash`, etc. |
+| `temperature` | number | `0` | LLM response randomness |
+| `max_tokens` | integer | `-1` | Token limit (-1 = unlimited) |
+| `tool_ids` | string[] | — | Custom tool references |
+| `built_in_tools` | BuiltInTools | — | System tools: `end_call`, `transfer_to_agent`, etc. |
+| `knowledge_base` | KnowledgeBaseLocator[] | — | Document sources |
+| `custom_llm` | CustomLlm | — | Custom LLM endpoint configuration |
+| `rag` | RagConfig | — | Retrieval-augmented generation settings |
+
+#### Tool Types
+
+Agents support multiple tool types via the `tools` array:
+
+| Type | Description |
+|------|-------------|
+| `webhook` | Custom HTTP endpoints with request/response schemas |
+| `client` | Browser/application-side operations |
+| `system` | Built-in (call termination, transfers, DTMF) |
+| `api_integration_webhook` | Pre-configured API integrations |
+| `mcp` | Model Context Protocol servers |
+
+Each tool includes:
+- `response_timeout_secs` (integer, default: 20)
+- `disable_interruptions` (boolean)
+- `force_pre_tool_speech` (boolean)
+- `execution_mode`: `immediate`, `post_tool_speech`, `async`
+
+#### Platform Settings
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `evaluation` | EvaluationSettings | Conversation quality criteria |
+| `widget` | WidgetConfig | Embedded UI: colors, placement, feedback |
+| `data_collection` | object | Custom data fields |
+| `auth` | AuthSettings | Token requirements and allowlists |
+| `call_limits` | AgentCallLimits | Concurrency and daily caps |
+| `privacy` | PrivacyConfig | Recording, retention, PII deletion |
+
+#### Example Request
+
+```json
+{
+  "name": "Customer Support Agent",
+  "tags": ["support", "production"],
+  "conversation_config": {
+    "agent": {
+      "prompt": {
+        "prompt": "You are a helpful support agent",
+        "llm": "gpt-4o",
+        "temperature": 0.7
+      },
+      "first_message": "Hello! How can I assist you?",
+      "language": "en"
+    },
+    "tts": {
+      "model_id": "eleven_turbo_v2_5",
+      "voice_id": "cjVigY5qzO86Huf0OWal"
+    },
+    "turn": {
+      "turn_timeout": 7
+    }
+  },
+  "platform_settings": {
+    "widget": {
+      "variant": "compact",
+      "placement": "bottom-right"
+    }
+  }
+}
+```
+
+#### Response `200`
+
+Returns `CreateAgentResponseModel` with the created agent configuration plus:
+- `agent_id`
+- Creation timestamp
+- Agent status
+
+---
+
+### Get Agent
+
+Retrieve config for an agent.
+
+```
+GET /v1/convai/agents/{agent_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID (returned on creation) |
+
+#### Response `200`
+
+Returns `GetAgentResponseModel` containing:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent_id` | string | Unique identifier |
+| `agent_name` | string | Name of the agent |
+| `created_at_unix_secs` | integer | Creation timestamp |
+| `updated_at_unix_secs` | integer | Last update timestamp |
+| `asr` | object | Speech recognition settings |
+| `turn` | object | Turn detection settings |
+| `tts` | object | Text-to-speech configuration |
+| `conversation` | object | Event configuration and monitoring |
+| `language_presets` | object | Language-specific overrides |
+| `vad` | object | Voice activity detection config |
+| `agent` | object | Agent settings (first message, language, prompt) |
+| `prompt` | object | LLM configuration (model, temperature, tools) |
+| `built_in_tools` | object | System tools (end_call, transfer_to_number, etc.) |
+| `tools` | array | Custom webhook and client tools |
+| `knowledge_base` | array | Referenced knowledge bases |
+| `dynamic_variables` | object | Variable placeholder definitions |
+| `widget` | object | Embed widget configuration |
+| `evaluation` | object | Conversation evaluation criteria |
+| `auth` | object | Authentication requirements |
+| `call_limits` | object | Concurrency and daily limits |
+| `privacy` | object | Recording and retention policies |
+| `safety` | object | Safety evaluation settings |
+| `phone_numbers` | array | Assigned phone numbers (SIP/Twilio) |
+| `whatsapp_accounts` | array | WhatsApp business account assignments |
+
+#### Example
+
+```bash
+curl -X GET "https://api.elevenlabs.io/v1/convai/agents/YOUR_AGENT_ID" \
+  -H "xi-api-key: YOUR_API_KEY"
+```
+
+---
+
+### Update Agent
+
+Patches an agent's settings. Accepts partial updates — only specified fields are modified.
+
+```
+PATCH /v1/convai/agents/{agent_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `conversation_config` | object | No | Conversation orchestration settings |
+| `platform_settings` | object | No | Non-conversation configuration |
+| `workflow` | object | No | Conversation flow and tool interaction logic |
+| `name` | string | No | Agent name |
+| `tags` | string[] | No | Classification tags |
+| `version_description` | string | No | Change notes for versioned agents |
+| `procedure_refs` | array | No | Procedure references for this version |
+
+#### Response `200`
+
+Returns full `GetAgentResponseModel` with complete agent state post-modification.
+
+---
+
+### Delete Agent
+
+Delete an agent.
+
+```
+DELETE /v1/convai/agents/{agent_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Response `200`
+
+Successful deletion (empty response).
+
+#### Example
+
+```typescript
+// TypeScript
+await client.conversationalAi.agents.delete("agent_3701k3ttaq12ewp8b7qv5rfyszkz");
+```
+
+```python
+# Python
+client.conversational_ai.agents.delete(agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz")
+```
+
+---
+
+### Get Agent Link
+
+Get the current link used to share the agent with others.
+
+```
+GET /v1/convai/agents/{agent_id}/link
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Response `200`
+
+```json
+{
+  "agent_id": "string",
+  "token": {
+    "agent_id": "string",
+    "conversation_token": "string",
+    "expiration_time_unix_secs": 0,
+    "conversation_id": "string",
+    "purpose": "signed_url | shareable_link",
+    "token_requester_user_id": "string"
+  }
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.agents.link.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz");
+```
+
+---
+
+### Simulate Conversation
+
+Run a conversation between the agent and a simulated user.
+
+```
+POST /v1/convai/agents/{agent_id}/simulate-conversation
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `simulation_specification` | object | **Yes** | Simulation configuration |
+| `simulation_specification.simulated_user_config` | AgentConfig | **Yes** | Simulated user behavior config |
+| `simulation_specification.tool_mock_config` | object | No | Mock configurations for tools |
+| `simulation_specification.partial_conversation_history` | array | No | Partial history to start from |
+| `simulation_specification.dynamic_variables` | object | No | Dynamic variable values |
+| `extra_evaluation_criteria` | array | No | Additional evaluation criteria |
+| `new_turns_limit` | integer | No (default: 10000) | Maximum new turns to generate |
+
+#### Tool Mock Config
+
+```json
+{
+  "tool_name": {
+    "default_return_value": "Tool Called.",
+    "default_is_error": false
+  }
+}
+```
+
+#### Response `200`
+
+```json
+{
+  "simulated_conversation": [
+    {
+      "role": "user | agent",
+      "message": "string",
+      "time_in_call_secs": 0,
+      "tool_calls": [],
+      "tool_results": [],
+      "interrupted": false,
+      "llm_usage": {}
+    }
+  ],
+  "analysis": {
+    "evaluation_criteria_results": {},
+    "data_collection_results": {},
+    "call_successful": "success | failure | unknown",
+    "transcript_summary": "string",
+    "call_summary_title": "string"
+  }
+}
+```
+
+#### Example
+
+```python
+client.conversational_ai.agents.simulate_conversation(
+    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
+    simulation_specification={
+        "simulated_user_config": {
+            "first_message": "Hello, how can I help?",
+            "language": "en"
+        }
+    }
+)
+```
+
+---
+
+### Stream Simulate Conversation
+
+Run a conversation between the agent and a simulated user, streaming back the response. Responses are partial lists of messages that should be concatenated. A final message with conversation analysis is sent on completion.
+
+```
+POST /v1/convai/agents/{agent_id}/simulate-conversation/stream
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Request Body
+
+Same as [Simulate Conversation](#simulate-conversation).
+
+#### Response `200` (Streamed JSON)
+
+Partial message lists followed by a final analysis message:
+
+```json
+{
+  "messages": [
+    {
+      "role": "user | agent",
+      "message": "string",
+      "time_in_call_secs": 0,
+      "tool_calls": [],
+      "tool_results": []
+    }
+  ],
+  "conversation_analysis": {
+    "evaluation_results": [],
+    "metrics": {}
+  }
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.agents.simulateConversationStream(
+    "agent_3701k3ttaq12ewp8b7qv5rfyszkz",
+    {
+        simulationSpecification: {
+            simulatedUserConfig: {
+                firstMessage: "Hello, how can I help you today?",
+                language: "en",
+            },
+        },
+    }
+);
+```
+
+---
+
+### Calculate LLM Usage
+
+Calculates expected number of LLM tokens needed for the specified agent.
+
+```
+POST /v1/convai/agent/{agent_id}/llm-usage/calculate
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | Yes | Agent ID |
+
+#### Request Body
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prompt_length` | integer | Length of the prompt in characters |
+| `number_of_pages` | integer | Pages of PDF content or URLs in Knowledge Base |
+| `rag_enabled` | boolean | Whether RAG is enabled |
+
+#### Response `200`
+
+```json
+{
+  "llm_prices": [
+    {
+      "llm": "gpt-4o | claude-sonnet-4 | gemini-2.5-flash | ...",
+      "price_per_minute": 0.0
+    }
+  ]
+}
+```
+
+---
+
+## Conversations
+
+### List Conversations
+
+Get all conversations of agents that a user owns. With option to restrict to a specific agent.
+
+```
+GET /v1/convai/conversations
+```
+
+#### Query Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `cursor` | string | No | — | Pagination cursor from previous response |
+| `agent_id` | string | No | — | Filter by agent ID |
+| `call_successful` | enum | No | — | `success`, `failure`, `unknown` |
+| `call_start_before_unix` | integer | No | — | Filter conversations before this unix timestamp |
+| `call_start_after_unix` | integer | No | — | Filter conversations after this unix timestamp |
+| `call_duration_min_secs` | integer | No | — | Minimum call duration in seconds |
+| `call_duration_max_secs` | integer | No | — | Maximum call duration in seconds |
+| `rating_min` | integer | No | — | Minimum overall rating (1-5) |
+| `rating_max` | integer | No | — | Maximum overall rating (1-5) |
+| `has_feedback_comment` | boolean | No | — | Filter by presence of user feedback comments |
+| `user_id` | string | No | — | Filter by initiating user ID |
+| `evaluation_params` | string | No | — | Evaluation filters: `criteria_id:result` |
+| `data_collection_params` | string | No | — | Data collection filters using operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `exists`, `missing` |
+| `tool_names` | string | No | — | Filter by tool names used during the call |
+| `main_languages` | string | No | — | Filter by detected main language code |
+| `page_size` | integer | No | 30 | Max results (max 100) |
+| `summary_mode` | enum | No | `exclude` | `exclude` or `include` transcript summaries |
+| `search` | string | No | — | Full-text or fuzzy search over transcript messages |
+| `conversation_initiation_source` | enum | No | — | Source: `unknown`, `android_sdk`, `node_js_sdk`, `react_native_sdk`, `react_sdk`, `js_sdk`, `python_sdk`, `widget`, `sip_trunk`, `twilio`, `genesys`, `swift_sdk`, `whatsapp`, `flutter_sdk`, `zendesk_integration`, `slack_integration` |
+| `branch_id` | string | No | — | Filter by branch ID |
+
+#### Response `200`
+
+```json
+{
+  "conversations": [
+    {
+      "agent_id": "string",
+      "branch_id": "string",
+      "version_id": "string",
+      "agent_name": "string",
+      "conversation_id": "string",
+      "start_time_unix_secs": 0,
+      "call_duration_secs": 0,
+      "message_count": 0,
+      "status": "initiated | in-progress | processing | done | failed",
+      "call_successful": "success | failure | unknown",
+      "transcript_summary": "string",
+      "call_summary_title": "string",
+      "direction": "inbound | outbound",
+      "rating": 0.0
+    }
+  ],
+  "next_cursor": "string",
+  "has_more": false
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.list({
+  agentId: "agent_id",
+  pageSize: 30,
+  summaryMode: "exclude"
+});
+```
+
+```python
+client.conversational_ai.conversations.list(
+  agent_id="agent_id",
+  page_size=30,
+  summary_mode="exclude"
+)
+```
+
+---
+
+### Get Conversation Details
+
+Get the details of a particular conversation.
+
+```
+GET /v1/convai/conversations/{conversation_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `conversation_id` | string | Yes | Conversation ID |
+
+#### Response `200`
+
+```json
+{
+  "agent_id": "string",
+  "agent_name": "string",
+  "conversation_id": "string",
+  "status": "initiated | in-progress | processing | done | failed",
+  "user_id": "string",
+  "branch_id": "string",
+  "version_id": "string",
+  "transcript": [
+    {
+      "role": "user | agent",
+      "message": "string",
+      "tool_calls": [],
+      "tool_results": [],
+      "feedback": {}
+    }
+  ],
+  "metadata": {
+    "start_time": 0,
+    "duration": 0,
+    "cost": 0.0,
+    "deletion_settings": {},
+    "feedback": {},
+    "charging_details": {}
+  },
+  "analysis": {
+    "evaluation_criteria_results": {},
+    "data_collection_results": {},
+    "summaries": {}
+  },
+  "conversation_initiation_client_data": {
+    "config_overrides": {},
+    "dynamic_variables": {}
+  },
+  "has_audio": true,
+  "has_user_audio": true,
+  "has_response_audio": true
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.get("conversation_id");
+```
+
+```python
+client.conversational_ai.conversations.get(conversation_id="conversation_id")
+```
+
+---
+
+### Delete Conversation
+
+Delete a particular conversation.
+
+```
+DELETE /v1/convai/conversations/{conversation_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `conversation_id` | string | Yes | Conversation ID |
+
+#### Response `200`
+
+Successful deletion.
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.delete("conversation_id");
+```
+
+```python
+client.conversational_ai.conversations.delete(conversation_id="conversation_id")
+```
+
+---
+
+### Get Conversation Audio
+
+Get the audio recording of a particular conversation.
+
+```
+GET /v1/convai/conversations/{conversation_id}/audio
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `conversation_id` | string | Yes | Conversation ID |
+
+#### Response `200`
+
+- **Content-Type:** `application/octet-stream`
+- Returns binary audio file data.
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.audio.get("conversation_id");
+```
+
+```python
+client.conversational_ai.conversations.audio.get(conversation_id="conversation_id")
+```
+
+---
+
+### Send Conversation Feedback
+
+Send feedback for a given conversation.
+
+```
+POST /v1/convai/conversations/{conversation_id}/feedback
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `conversation_id` | string | Yes | Conversation ID |
+
+#### Request Body
+
+```json
+{
+  "feedback": "like | dislike"
+}
+```
+
+#### Response `200`
+
+Successful response.
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.feedback.create("conversation_id", {
+  feedback: "like"
+});
+```
+
+```python
+client.conversational_ai.conversations.feedback.create(
+    conversation_id="conversation_id",
+    feedback="like"
+)
+```
+
+---
+
+### Get Conversation Token (WebRTC)
+
+Get a WebRTC session token for real-time communication.
+
+```
+GET /v1/convai/conversation/token
+```
+
+#### Query Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_id` | string | **Yes** | Agent ID |
+| `participant_name` | string | No | Custom participant name (defaults to user ID) |
+| `branch_id` | string | No | Branch ID to use |
+
+#### Response `200`
+
+```json
+{
+  "token": "string"
+}
+```
+
+---
+
+### Get Signed URL
+
+Get a signed URL to start a conversation with an agent that requires authorization.
+
+```
+GET /v1/convai/conversation/get-signed-url
+```
+
+#### Query Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `agent_id` | string | **Yes** | — | Agent ID |
+| `include_conversation_id` | boolean | No | `false` | Include a conversation_id (makes the signature single-use) |
+| `branch_id` | string | No | — | Branch ID to use |
+
+#### Response `200`
+
+```json
+{
+  "signed_url": "string"
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.conversations.getSignedUrl({
+    agentId: "agent_id",
+    includeConversationId: true,
+    branchId: "branch_id"
+});
+```
+
+```python
+client.conversational_ai.conversations.get_signed_url(
+    agent_id="agent_id",
+    include_conversation_id=True,
+    branch_id="branch_id"
+)
+```
+
+---
+
+## Batch Calling
+
+### Submit Batch Calling Job
+
+Submit a batch call request to schedule calls for multiple recipients.
+
+```
+POST /v1/convai/batch-calling/submit
+```
+
+#### Request Body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `call_name` | string | **Yes** | Name identifier for the batch call |
+| `agent_id` | string | **Yes** | Agent ID to handle the calls |
+| `recipients` | array | **Yes** | Collection of call recipients |
+| `scheduled_time_unix` | integer | No | Unix timestamp to schedule calls |
+| `agent_phone_number_id` | string | No | Phone number ID for agent |
+| `timezone` | string | No | Timezone for scheduling |
+| `whatsapp_params` | object | No | WhatsApp configuration |
+
+#### Recipient Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Recipient identifier |
+| `phone_number` | string | Phone number to call |
+| `whatsapp_user_id` | string | WhatsApp user identifier |
+| `conversation_initiation_client_data` | object | Config overrides and dynamic variables |
+
+#### WhatsApp Params
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `whatsapp_phone_number_id` | string | No | WhatsApp phone number ID |
+| `whatsapp_call_permission_request_template_name` | string | **Yes** | Template name |
+| `whatsapp_call_permission_request_template_language_code` | string | **Yes** | Template language code |
+
+#### Response `200`
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "agent_id": "string",
+  "agent_name": "string",
+  "status": "pending | in_progress | completed | failed | cancelled",
+  "created_at_unix": 0,
+  "scheduled_time_unix": 0,
+  "last_updated_at_unix": 0,
+  "total_calls_dispatched": 0,
+  "total_calls_scheduled": 0,
+  "total_calls_finished": 0
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.batchCalls.submit({
+    callName: "Survey Batch",
+    agentId: "agent_id",
+    recipients: [
+        { phoneNumber: "+1234567890" }
+    ]
+});
+```
+
+```python
+client.conversational_ai.batch_calls.submit(
+    call_name="Survey Batch",
+    agent_id="agent_id",
+    recipients=[{"phone_number": "+1234567890"}]
+)
+```
+
+---
+
+### List Workspace Batch Calling Jobs
+
+Get all batch calls for the current workspace.
+
+```
+GET /v1/convai/batch-calling/workspace
+```
+
+#### Query Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `limit` | integer | No | 100 | Maximum number of results |
+| `last_doc` | string | No | — | Pagination cursor |
+
+#### Response `200`
+
+```json
+{
+  "batch_calls": [
+    {
+      "id": "string",
+      "name": "string",
+      "agent_id": "string",
+      "agent_name": "string",
+      "phone_number_id": "string",
+      "phone_provider": "twilio | sip_trunk",
+      "whatsapp_params": {},
+      "created_at_unix": 0,
+      "scheduled_time_unix": 0,
+      "timezone": "string",
+      "total_calls_dispatched": 0,
+      "total_calls_scheduled": 0,
+      "total_calls_finished": 0,
+      "last_updated_at_unix": 0,
+      "status": "pending | in_progress | completed | failed | cancelled",
+      "retry_count": 0
+    }
+  ],
+  "next_doc": "string",
+  "has_more": false
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.batchCalls.list({ limit: 100 });
+```
+
+```python
+client.conversational_ai.batch_calls.list(limit=100)
+```
+
+---
+
+### Get Batch Call Information
+
+Get detailed information about a batch call including all recipients.
+
+```
+GET /v1/convai/batch-calling/{batch_id}
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `batch_id` | string | Yes | Batch call ID |
+
+#### Response `200`
+
+Returns `BatchCallDetailedResponse`:
+
+```json
+{
+  "id": "string",
+  "name": "string",
+  "agent_id": "string",
+  "agent_name": "string",
+  "phone_number_id": "string",
+  "phone_provider": "twilio | sip_trunk",
+  "whatsapp_params": {},
+  "created_at_unix": 0,
+  "scheduled_time_unix": 0,
+  "timezone": "string",
+  "total_calls_dispatched": 0,
+  "total_calls_scheduled": 0,
+  "total_calls_finished": 0,
+  "last_updated_at_unix": 0,
+  "status": "pending | in_progress | completed | failed | cancelled",
+  "retry_count": 0,
+  "recipients": [
+    {
+      "id": "string",
+      "phone_number": "string",
+      "whatsapp_user_id": "string",
+      "status": "string (BatchCallRecipientStatus)",
+      "created_at_unix": 0,
+      "updated_at_unix": 0,
+      "conversation_id": "string",
+      "conversation_initiation_client_data": {}
+    }
+  ]
+}
+```
+
+#### Example
+
+```typescript
+await client.conversationalAi.batchCalls.get("batch_id");
+```
+
+```python
+client.conversational_ai.batch_calls.get(batch_id="batch_id")
+```
+
+---
+
+### Cancel Batch Calling Job
+
+Cancel a running batch call and set all recipients to cancelled status.
+
+```
+POST /v1/convai/batch-calling/{batch_id}/cancel
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `batch_id` | string | Yes | Batch call ID |
+
+#### Response `200`
+
+Returns `BatchCallResponse` with updated status (see [Submit Batch Calling Job](#submit-batch-calling-job) response schema).
+
+#### Example
+
+```typescript
+await client.conversationalAi.batchCalls.cancel("batch_id");
+```
+
+```python
+client.conversational_ai.batch_calls.cancel(batch_id="batch_id")
+```
+
+---
+
+### Retry Batch Calling Job
+
+Retry a batch call, calling failed and no-response recipients again.
+
+```
+POST /v1/convai/batch-calling/{batch_id}/retry
+```
+
+#### Path Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `batch_id` | string | Yes | Batch call ID |
+
+#### Response `200`
+
+Returns `BatchCallResponse` with updated status and incremented `retry_count`.
+
+#### Example
+
+```typescript
+await client.conversationalAi.batchCalls.retry("batch_id");
+```
+
+```python
+client.conversational_ai.batch_calls.retry(batch_id="batch_id")
+```
+
+---
+
+## SDK Support
+
+All endpoints are available in official SDKs:
+
+| Language | Package |
+|----------|---------|
+| TypeScript/JavaScript | `@elevenlabs/elevenlabs-js` |
+| Python | `elevenlabs` |
+| Go | HTTP client |
+| Ruby | HTTP client |
+| Java | HTTP client |
+| PHP | HTTP client |
+| C# | HTTP client |
+| Swift | HTTP client |
+
+---
+
+## Common Enums
+
+### BatchCallStatus
+`pending` | `in_progress` | `completed` | `failed` | `cancelled`
+
+### ConversationStatus
+`initiated` | `in-progress` | `processing` | `done` | `failed`
+
+### CallSuccessful
+`success` | `failure` | `unknown`
+
+### TelephonyProvider
+`twilio` | `sip_trunk`
+
+### ConversationDirection
+`inbound` | `outbound`
+
+### AgentAccessRole
+`admin` | `editor` | `commenter` | `viewer`
+
+### LLM Models
+`gpt-4o-mini` | `gpt-4o` | `claude-sonnet-4` | `gemini-2.5-flash` | and others