===============
LIBRARY RULES
===============
From library maintainers:
- API base URL is https://api.vogent.ai/api
- Authenticate with Authorization: Bearer <api_key> header
- Generate API keys at https://app.vogent.ai in Settings > API Keys
- Webhook signatures use X-Elto-Signature header for HMAC-SHA256 verification
- Voice agents require both a prompt and a voice configuration
- Use Flow Builder for structured conversation paths with explicit decision points
- IVR detection and navigation is available via ivrConfiguration
- Voicelab provides ultra-low-latency TTS with Sesame CSM-1B model
- Dial statuses: queued, ringing, in_progress, ended, failed, no_answer, busy
- Webhook events: dial.created, dial.updated, dial.transcript, function_call
- Voice cloning requires 10-30 seconds of clean audio
- Batch dial jobs support up to 10,000 concurrent dials

### Quick Start: Initiate Call and Monitor Transcripts

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

This example demonstrates how to create a dial, initialize the VogentCall instance, start the call, connect audio, and monitor transcripts in real-time. Ensure you use a public API key for browser calls.

```typescript
import { VogentCall } from '@vogent/vogent-web-client';
// Step 1: Create a dial via the Vogent API
const response = await fetch('https://api.vogent.ai/api/dials', {
 method: 'POST',
 headers: {
  'Authorization': 'Bearer pub_vogent_...', // Use your public API key
  'Content-Type': 'application/json'
 },
 body: JSON.stringify({
  callAgentId: 'your_call_agent_id',
  browserCall: true // Important: Enable browser call mode
 })
});
const { dialToken, sessionId, dialId } = await response.json();
// Step 2: Initialize the VogentCall instance
const call = new VogentCall({
 sessionId,
 dialId,
 token: dialToken
});
// Step 3: Start the call session
await call.start();
// Step 4: Connect audio
const audioConnection = await call.connectAudio();
// Step 5: Monitor transcripts in real-time
const unsubscribe = call.monitorTranscript((transcript) => {
 transcript.forEach(({ text, speaker }) => {
  console.log(`${speaker}: ${text}`);
 });
});
// Step 6: Listen for status changes
call.on('status', (status) => {
 console.log('Call status:', status);
});
// Cleanup when done
unsubscribe();
await call.hangup();

```

--------------------------------

### Start Batch Job

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/platform-overview_batch-dial-jobs.md

Starts a batch dial job that has been created. Jobs are created in the `INIT` state and must be explicitly started.

```APIDOC
## POST /api/batch_dial_jobs/{job-id}/paused

### Description
Starts a batch dial job.

### Method
POST

### Endpoint
https://api.vogent.ai/api/batch_dial_jobs/{job-id}/paused

### Parameters
#### Path Parameters
- **job-id** (string) - Required - The ID of the batch job to start.

#### Headers
- **Content-Type** (string) - Required - `application/json`
- **api_key** (string) - Required - Your Vogent API key

#### Request Body
- **paused** (boolean) - Required - Set to `false` to start the job.

### Request Example
```json
{
  "paused": false
}
```
```

--------------------------------

### start()

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Initiates the call session. This method should be called before other call-related operations.

```APIDOC
## start()

### Description
Initiates the call session.

### Method
`start()`

### Returns
`Promise<void>`

### Request Example
```javascript
await call.start();
```
```

--------------------------------

### Start a Batch Dial Job

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/platform-overview_batch-dial-jobs.md

After creating a batch job, it is in the 'INIT' state. You must explicitly start it by sending a POST request to the job's paused endpoint with `{"paused": false}`.

```bash
curl -X POST "https://api.vogent.ai/api/batch_dial_jobs/{job-id}/paused" \
 -H "Content-Type: application/json" \
 -H "api_key: YOUR_API_KEY" \
 -d '{"paused": false}'

```

--------------------------------

### start()

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Initiates the call session. This method must be called after initializing the VogentCall instance.

```APIDOC
## start()

Starts the call session.

### Method

```javascript
await call.start();
```

### Description

This method initiates the call session after the `VogentCall` instance has been created. It is an asynchronous operation.
```

--------------------------------

### Get Batch Job Response Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-batch-dial-job.md

This is a sample JSON response when successfully retrieving a batch dial job. It includes details such as job ID, name, status, and scheduling information.

```json
{
 "id": "<string>",
 "maxConcurrentDials": 123,
 "name": "<string>",
 "status": "INIT",
 "callAgentId": "<string>",
 "createdAt": "2023-11-07T05:31:56Z",
 "fromPhoneNumberIds": [
  "<string>"
 ],
 "schedule": {
  "days": [
   {
    "dayOfWeek": 123,
    "timeSlots": [
     {
      "startTime": "<string>",
      "endTime": "<string>"
     }
    ]
   }
  ],
  "timezone": "<string>"
 }
}
```

--------------------------------

### Start Call Session

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Initiates the call session. Ensure this is called before other call-related actions.

```javascript
await call.start();
```

--------------------------------

### Dial Recording Complete Webhook Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_dial-recording.md

This JSON payload is an example of the message received when a dial recording is successfully created and attached to a dial. It includes the event type, the dial ID, and the URL where the recording can be accessed.

```json
{
  "event": "dial.recording_created",
  "payload": {
    "recording_url": "https://api.getelto.com/api/recordings/de3ee23e-ce58-4e05-9e7b-fcb96ba440a6",
    "dial_id": "5a6c6190-db20-4d8e-86a9-79a6af292dea"
  }
}
```

--------------------------------

### List Agents Response

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_list-agents.md

This is an example of a successful response when listing agents. It includes a 'data' array containing agent details and a 'cursor' for pagination.

```json
{
 "data": [
  {
   "id": "<string>",
   "name": "<string>",
   "language": "<string>",
   "transcriberParams": {
    "type": "deepgram",
    "keywords": [
     "<string>"
    ]
   },
   "metadata": {},
   "utteranceDetectorConfig": {
    "sensitivity": "ULTRA_FAST",
    "interruptionPlayTimeMs": 123
   },
   "endpointDetectorConfig": {
    "type": "SIMPLE",
    "mode": "CONSERVATIVE"
   },
   "ivrConfiguration": {
    "detectionType": "NONE",
    "versionedPromptId": "<string>",
    "aiVoiceId": "<string>",
    "taggingText": "<string>"
   },
   "idleMessageConfig": {
    "enabled": true,
    "messages": [
     "<string>"
    ],
    "idleDurationMilliseconds": 5001,
    "maxIdleMessages": 2
   },
   "maxDurationSeconds": 10800,
   "defaultVoiceId": "<string>",
   "defaultVersionedPromptId": "<string>",
   "defaultExtractorId": "<string>",
   "linkedFunctionDefinitions": [
    {
     "functionDefinitionId": "<string>",
     "lifecycleMessagesOverride": {
      "started": [
       "<string>"
      ]
     }
    }
   ],
   "fillEmptyStringVariables": true,
   "silenceHangupConfiguration": {
    "type": "DISABLED",
    "silenceDurationSeconds": 123
   },
   "voiceOptionValues": [
    {
     "optionId": "<string>",
     "value": "<string>"
    }
   ]
  }
 ],
 "cursor": "<string>"
}
```

--------------------------------

### connectAudio()

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Establishes the audio connection for the call session.

```APIDOC
## connectAudio()

Connects the audio stream for the call.

### Method

```javascript
const audioConnection = await call.connectAudio();
```

### Description

This method establishes the audio connection, allowing for real-time voice communication. It returns an object representing the audio connection.
```

--------------------------------

### Install Vogent Web Client

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Install the Vogent Web Client using your preferred package manager.

```bash
bun add @vogent/vogent-web-client
```

--------------------------------

### Get Phone Number by ID

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-phone-number.md

This snippet shows how to make a GET request to retrieve a specific phone number's details using its unique identifier.

```APIDOC
## GET /api/phone_numbers/{id}

### Description
Retrieves the details of a specific phone number.

### Method
GET

### Endpoint
/api/phone_numbers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the phone number.

### Request Example
```bash
curl --request GET \
 --url https://api.vogent.ai/api/phone_numbers/{id} \
 --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the phone number.
- **number** (string) - The phone number in E.164 format.
- **type** (string) - The type of the phone number (e.g., PSTN).
- **agentId** (string) - The identifier of the agent associated with the phone number.

#### Response Example
```json
{
 "id": "<string>",
 "number": "+18001234567",
 "type": "PSTN",
 "agentId": "<string>"
}
```
```

--------------------------------

### Web Application Text-to-Speech Integration

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/voicelab_voice-synthesis_advanced-features.md

Frontend JavaScript example for synthesizing text and playing audio directly in the browser. It handles the API call, receives the audio blob, creates a URL, and plays the audio.

```javascript
// Frontend JavaScript example
async function synthesizeText(text, voiceId) {
  try {
    const response = await fetch('/api/tts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ text, voiceId })
    });
    if (response.ok) {
      const audioBlob = await response.blob();
      const audioUrl = URL.createObjectURL(audioBlob);
      const audio = new Audio(audioUrl);
      audio.play();
    }
  } catch (error) {
    console.error('TTS Error:', error);
  }
}

```

--------------------------------

### Good Voice Pairing Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/voicelab_voice-synthesis_advanced-features.md

Illustrates effective voice pairing for a customer service scenario by contrasting a formal representative voice with a casual customer voice. Consistency is maintained for each character.

```python
# Good voice pairing example
customer_service_scenario = {
  "lines": [
    {"text": "Good morning, how may I help you?", "voiceId": "professional-female-1"}, # Formal representative
    {"text": "Hi, I need help with my account.", "voiceId": "conversational-male-1"},  # Casual customer
    {"text": "I'd be happy to assist you with that.", "voiceId": "professional-female-1"} # Consistent representative
  ]
}


```

--------------------------------

### Inbound Dial Webhook Example Message

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_dial-inbound.md

This is an example of the JSON payload received when the `dial.inbound` webhook is triggered. It contains details about the call session and involved numbers.

```json
{
  "event": "dial.inbound",
  "payload": {
    "dial_session_id": "de3ee23e-ce58-4e05-9e7b-fcb96ba440a6",
    "dial_id": "5a6c6190-db20-4d8e-86a9-79a6af292dea",
    "dest_number_id": "2310e824-a2cb-4b0c-88cf-8f8b745bf6ae",
    "call_agent_id": "32e4be84-0803-4c41-af70-5a87a2dc0a4e",
    "source_number": "+18001234567"
  }
}

```

--------------------------------

### Function Call Webhook Example Message

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_function-call.md

This is an example of the payload received when the Function Call webhook is triggered. It includes the dial ID, dial object details, and the parameters passed to the function.

```json
{
  "dial_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "dial": {
    ...
  },
  "params": {
    "name": "John Doe"
   }
}
```

--------------------------------

### Dial Transcript Finalized Webhook Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_dial-transcript.md

This JSON object represents an example payload for the `dial.transcript` webhook. It includes the event type and the payload containing the dial ID and the finalized transcript.

```json
{
  "event": "dial.transcript",
  "payload": {
    "dial_id": "5a6c6190-db20-4d8e-86a9-79a6af292dea",
    "transcript": [{
      "text": "Hello?",
      "speaker": "HUMAN"
    }]
  }
}
```

--------------------------------

### connectAudio()

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/sdk_web-sdk.md

Establishes the audio connection for the call. This is necessary to enable voice communication.

```APIDOC
## connectAudio()

### Description
Establishes the audio connection for the call.

### Method
`connectAudio()`

### Returns
`Promise<AudioConnection>`

### Request Example
```javascript
const audioConnection = await call.connectAudio();
```
```

--------------------------------

### Dial Status Updated Webhook Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_dial-status-updated.md

This is an example of the JSON payload received when a dial's status is updated. It includes the dial session ID, dial ID, and the new status.

```json
{
  "event": "dial.updated",
  "payload": {
    "dial_session_id": "de3ee23e-ce58-4e05-9e7b-fcb96ba440a6",
    "dial_id": "5a6c6190-db20-4d8e-86a9-79a6af292dea",
    "status": "completed"
  }
}
```

--------------------------------

### Dial Extractor Complete Webhook Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/developers_webhooks_dial-extractor.md

This is an example of the JSON payload received when the dial extractor completes its process. It includes the event type, dial ID, and the AI result summary.

```json
{
  "event": "dial.extractor",
  "payload": {
    "ai_result": {
      "summary": "This call was successful in getting the information."
    },
    "dial_id": "5a6c6190-db20-4d8e-86a9-79a6af292dea"
  }
}
```

--------------------------------

### Create Agent

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_create-agent.md

Creates a new agent with specified configurations.

```APIDOC
## POST /agents

### Description
Creates a new agent.

### Method
POST

### Endpoint
/agents

### Request Body
- **name** (string) - Required - The name of the agent.
- **defaultVoiceId** (string) - Optional - The default voice ID for the agent.
- **defaultVersionedPrompt** (object) - Required - The default versioned prompt for the agent.
  - **aiModelId** (string) - Required - The ID of the AI model.
  - **agentType** (string) - Required - The type of agent (e.g., "STANDARD").
  - **name** (string) - Required - The name of the prompt.
  - **prompt** (string) - Required - The prompt content.
  - **flowDefinition** (object) - Optional - The flow definition for the prompt.
    - **nodes** (array) - Required - An array of nodes in the flow.
      - **id** (string) - Required - The ID of the node.
      - **name** (string) - Required - The name of the node.
      - **type** (string) - Required - The type of the node.
      - **transitionRules** (array) - Optional - Rules for transitioning between nodes.
        - **conditionType** (string) - Required - The type of condition (e.g., "always").
        - **transitionNodeId** (string) - Required - The ID of the node to transition to.
        - **arrayConditionType** (string) - Optional - The type of array condition.
        - **field** (string) - Optional - The field to check.
        - **value** (string) - Optional - The value to compare.
        - **values** (array) - Optional - An array of values to compare.
          - (string) - Optional - A value in the array.
      - **nodeData** (object) - Optional - Additional data for the node.
    - **globalContext** (string) - Optional - Global context for the flow.
    - **aiOpen** (boolean) - Optional - Whether AI is enabled for the flow.
    - **openingLineType** (string) - Optional - The type of opening line (e.g., "INBOUND_ONLY").
  - **modelOptionValues** (array) - Optional - Values for model options.
    - **optionId** (string) - Required - The ID of the option.
    - **value** (string) - Required - The value of the option.
- **defaultExtractor** (object) - Optional - The default extractor for the agent.
  - **name** (string) - Required - The name of the extractor.
  - **extractorFieldsJsonSchema** (string) - Required - The JSON schema for extractor fields.
- **inboundWebhookResponse** (boolean) - Optional - Whether to enable inbound webhook responses.
- **inboundWebhookUrl** (string) - Optional - The URL for inbound webhooks.
- **maxDurationSeconds** (integer) - Optional - The maximum duration of the agent in seconds.
- **openingLine** (object) - Optional - The opening line for the agent.
  - **lineType** (string) - Required - The type of line (e.g., "INBOUND_ONLY").
  - **content** (string) - Required - The content of the opening line.
- **voiceVolumeLevel** (number) - Optional - The volume level of the agent's voice.
- **backgroundNoiseType** (string) - Optional - The type of background noise.
- **linkedFunctionDefinitionIds** (array) - Optional - IDs of linked function definitions.
  - (string) - Optional - A function definition ID.
- **linkedFunctionDefinitionInputs** (array) - Optional - Inputs for linked function definitions.
  - **functionDefinitionId** (string) - Required - The ID of the function definition.
  - **lifecycleMessagesOverride** (object) - Optional - Override lifecycle messages.
    - **started** (array) - Optional - Messages to send when started.
      - (string) - Optional - A message.
- **metadata** (object) - Optional - Metadata for the agent.
- **transcriberParams** (object) - Optional - Parameters for the transcriber.
  - **type** (string) - Required - The type of transcriber (e.g., "deepgram").
  - **keywords** (array) - Optional - Keywords for the transcriber.
    - (string) - Optional - A keyword.
- **idleMessageConfig** (object) - Optional - Configuration for idle messages.
  - **enabled** (boolean) - Optional - Whether idle messages are enabled.
  - **messages** (array) - Optional - The idle messages.
    - (string) - Optional - An idle message.
  - **idleDurationMilliseconds** (integer) - Optional - The duration of idle time in milliseconds.
  - **maxIdleMessages** (integer) - Optional - The maximum number of idle messages.
- **utteranceDetectorConfig** (object) - Optional - Configuration for utterance detection.
  - **sensitivity** (string) - Optional - The sensitivity of the detector (e.g., "ULTRA_FAST").
  - **interruptionPlayTimeMs** (integer) - Optional - Playback time in milliseconds for interruptions.
- **endpointDetectorConfig** (object) - Optional - Configuration for endpoint detection.
  - **type** (string) - Optional - The type of detector (e.g., "SIMPLE").
  - **mode** (string) - Optional - The mode of the detector (e.g., "CONSERVATIVE").
- **ivrConfiguration** (object) - Optional - IVR configuration.
  - **detectionType** (string) - Optional - The type of IVR detection.
  - **versionedPromptId** (string) - Optional - The ID of the versioned prompt.
  - **aiVoiceId** (string) - Optional - The ID of the AI voice.
  - **taggingText** (string) - Optional - Text for tagging.
- **language** (string) - Optional - The language of the agent.
- **fillEmptyStringVariables** (boolean) - Optional - Whether to fill empty string variables.
- **silenceHangupConfiguration** (object) - Optional - Configuration for silence hangup.
  - **type** (string) - Optional - The type of silence hangup (e.g., "DISABLED").
  - **silenceDurationSeconds** (integer) - Optional - The duration of silence in seconds.
- **voiceOptionValues** (array) - Optional - Values for voice options.
  - **optionId** (string) - Required - The ID of the option.
  - **value** (string) - Required - The value of the option.

### Request Example
```json
{
 "name": "<string>",
 "defaultVoiceId": "<string>",
 "defaultVersionedPrompt": {
  "aiModelId": "<string>",
  "agentType": "STANDARD",
  "name": "<string>",
  "prompt": "<string>",
  "flowDefinition": {
   "nodes": [
    {
     "id": "<string>",
     "name": "<string>",
     "type": "<string>",
     "transitionRules": [
      {
       "conditionType": "always",
       "transitionNodeId": "<string>",
       "arrayConditionType": "any",
       "field": "<string>",
       "value": "<string>",
       "values": [
        "<string>"
       ]
      }
     ],
     "nodeData": {}
    }
   ],
   "globalContext": "<string>",
   "aiOpen": true,
   "openingLineType": "INBOUND_ONLY"
  },
  "modelOptionValues": [
   {
    "optionId": "<string>",
    "value": "<string>"
   }
  ]
 },
 "defaultExtractor": {
  "name": "<string>",
  "extractorFieldsJsonSchema": "<string>"
 },
 "inboundWebhookResponse": true,
 "inboundWebhookUrl": "<string>",
 "maxDurationSeconds": 10800,
 "openingLine": {
  "lineType": "INBOUND_ONLY",
  "content": "<string>"
 },
 "voiceVolumeLevel": -100,
 "backgroundNoiseType": "office",
 "linkedFunctionDefinitionIds": [
  "<string>"
 ],
 "linkedFunctionDefinitionInputs": [
  {
   "functionDefinitionId": "<string>",
   "lifecycleMessagesOverride": {
    "started": [
     "<string>"
    ]
   }
  }
 ],
 "metadata": {},
 "transcriberParams": {
  "type": "deepgram",
  "keywords": [
   "<string>"
  ]
 },
 "idleMessageConfig": {
  "enabled": true,
  "messages": [
   "<string>"
  ],
  "idleDurationMilliseconds": 5001,
  "maxIdleMessages": 2
 },
 "utteranceDetectorConfig": {
  "sensitivity": "ULTRA_FAST",
  "interruptionPlayTimeMs": 123
 },
 "endpointDetectorConfig": {
  "type": "SIMPLE",
  "mode": "CONSERVATIVE"
 },
 "ivrConfiguration": {
  "detectionType": "NONE",
  "versionedPromptId": "<string>",
  "aiVoiceId": "<string>",
  "taggingText": "<string>"
 },
 "language": "en",
 "fillEmptyStringVariables": true,
 "silenceHangupConfiguration": {
  "type": "DISABLED",
  "silenceDurationSeconds": 123
 },
 "voiceOptionValues": [
  {
   "optionId": "<string>",
   "value": "<string>"
  }
 ]
}
```

### Response
#### Success Response (200)
- **id** (string) - Description of the agent ID.
- **name** (string) - Description of the agent name.
- **language** (string) - Description of the agent language.
- **transcriberParams** (object) - Transcriber parameters.
  - **type** (string) - The type of transcriber.
  - **keywords** (array) - Keywords for the transcriber.
    - (string) - A keyword.
- **metadata** (object) - Metadata for the agent.
- **utteranceDetectorConfig** (object) - Utterance detector configuration.
  - **sensitivity** (string) - The sensitivity of the detector.
  - **interruptionPlayTimeMs** (integer) - Playback time in milliseconds for interruptions.
- **endpointDetectorConfig** (object) - Endpoint detector configuration.
  - **type** (string) - The type of detector.
  - **mode** (string) - The mode of the detector.
- **ivrConfiguration** (object) - IVR configuration.
  - **detectionType** (string) - The type of IVR detection.
  - **versionedPromptId** (string) - The ID of the versioned prompt.
  - **aiVoiceId** (string) - The ID of the AI voice.
  - **taggingText** (string) - Text for tagging.
- **idleMessageConfig** (object) - Idle message configuration.
  - **enabled** (boolean) - Whether idle messages are enabled.
  - **messages** (array) - The idle messages.
    - (string) - An idle message.
  - **idleDurationMilliseconds** (integer) - The duration of idle time in milliseconds.
  - **maxIdleMessages** (integer) - The maximum number of idle messages.
- **maxDurationSeconds** (integer) - The maximum duration of the agent in seconds.
- **defaultVoiceId** (string) - The default voice ID for the agent.
- **defaultVersionedPromptId** (string) - The ID of the default versioned prompt.
- **defaultExtractorId** (string) - The ID of the default extractor.
- **linkedFunctionDefinitions** (array) - Linked function definitions.
  - **functionDefinitionId** (string) - The ID of the function definition.
  - **lifecycleMessagesOverride** (object) - Override lifecycle messages.
    - **started** (array) - Messages to send when started.
      - (string) - A message.
- **fillEmptyStringVariables** (boolean) - Whether to fill empty string variables.
- **silenceHangupConfiguration** (object) - Silence hangup configuration.
  - **type** (string) - The type of silence hangup.
  - **silenceDurationSeconds** (integer) - The duration of silence in seconds.
- **voiceOptionValues** (array) - Values for voice options.
  - **optionId** (string) - The ID of the option.
  - **value** (string) - The value of the option.

#### Response Example
```json
{
 "id": "<string>",
 "name": "<string>",
 "language": "<string>",
 "transcriberParams": {
  "type": "deepgram",
  "keywords": [
   "<string>"
  ]
 },
 "metadata": {},
 "utteranceDetectorConfig": {
  "sensitivity": "ULTRA_FAST",
  "interruptionPlayTimeMs": 123
 },
 "endpointDetectorConfig": {
  "type": "SIMPLE",
  "mode": "CONSERVATIVE"
 },
 "ivrConfiguration": {
  "detectionType": "NONE",
  "versionedPromptId": "<string>",
  "aiVoiceId": "<string>",
  "taggingText": "<string>"
 },
 "idleMessageConfig": {
  "enabled": true,
  "messages": [
   "<string>"
  ],
  "idleDurationMilliseconds": 5001,
  "maxIdleMessages": 2
 },
 "maxDurationSeconds": 10800,
 "defaultVoiceId": "<string>",
 "defaultVersionedPromptId": "<string>",
 "defaultExtractorId": "<string>",
 "linkedFunctionDefinitions": [
  {
   "functionDefinitionId": "<string>",
   "lifecycleMessagesOverride": {
    "started": [
     "<string>"
    ]
   }
  }
 ],
 "fillEmptyStringVariables": true,
 "silenceHangupConfiguration": {
  "type": "DISABLED",
  "silenceDurationSeconds": 123
 },
 "voiceOptionValues": [
  {
   "optionId": "<string>",
   "value": "<string>"
  }
 ]
}
```

#### Authorizations
- **Authorization** (string) - Required - header - In the form `Bearer <api_key_here>`. You can find your api key in your dashboard.
```

--------------------------------

### Basic Text-to-Speech Request

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/voicelab_quickstart.md

Use this cURL command to perform a basic text-to-speech generation. Replace YOUR_API_KEY with your actual API key. The output is saved to my-first-voice.wav.

```bash
curl -X POST "https://api.vogent.ai/api/tts" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
  "text": "So I tried this new thing called Voicelab that I found online, and the voices that it generated were super realistic.",
  "voiceId": "23b2186b-ed56-4185-998c-8d19e1bb227a"
 }' \
 --output my-first-voice.wav
```

--------------------------------

### Get Extractor

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-extractor.md

Fetches a specific extractor for a given agent.

```APIDOC
## GET /agents/{agentId}/extractors/{extractorId}

### Description
Retrieves the details of a specific extractor for a given agent.

### Method
GET

### Endpoint
/agents/{agentId}/extractors/{extractorId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - ID of the agent.
- **extractorId** (string) - Required - ID of the extractor.

#### Request Body
None

### Response
#### Success Response (200)
- **id** (string) - Required - The unique identifier of the extractor.
- **name** (string) - Required - The name of the extractor.
- **extractorFieldsJsonSchema** (string) - Required - The JSON schema defining the fields for the extractor.

#### Response Example
```json
{
 "id": "<string>",
 "name": "<string>",
 "extractorFieldsJsonSchema": "<string>"
}
```

#### Authorizations
- **Authorization** (string) - Required - In the form `Bearer <api_key_here>`.
```

--------------------------------

### Create a voice agent

Source: https://github.com/crowe452/vogent-docs/blob/main/README.md

Configure new voice agents for your AI system.

```APIDOC
## POST /agents

### Description
Create a voice agent.

### Method
POST

### Endpoint
/agents
```

--------------------------------

### Get Function

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-function.md

Retrieves the details of a specific function by its unique identifier.

```APIDOC
## GET /api/functions/{id}

### Description
Retrieves the details of a specific function by its unique identifier.

### Method
GET

### Endpoint
/api/functions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the function to retrieve.

### Request Example
```bash
curl --request GET \
 --url https://api.vogent.ai/api/functions/{id} \
 --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the function.
- **name** (string) - The name of the function.
- **description** (string) - A description of the function.
- **type** (string) - The type of the function (e.g., "transfer").
- **allowedNumbers** (array) - A list of allowed phone numbers for the function.
  - **number** (string) - A phone number.
- **allowAnyNumber** (boolean) - Indicates if any phone number is allowed.
- **lifecycleMessages** (object) - Messages related to the function's lifecycle.
  - **started** (array) - A list of messages when the function starts.
    - (string) - A message string.

#### Response Example
```json
{
 "id": "<string>",
 "name": "<string>",
 "description": "<string>",
 "type": "transfer",
 "allowedNumbers": [
  {
   "number": "<string>"
  }
 ],
 "allowAnyNumber": true,
 "lifecycleMessages": {
  "started": [
   "<string>"
  ]
 }
}
```
```

--------------------------------

### Real-time Streaming with WebSockets

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/voicelab_quickstart.md

Implement real-time text-to-speech streaming using WebSockets for applications requiring immediate audio feedback. This example connects to the WebSocket API, sends text chunks, and saves received audio data.

```python
import asyncio
import websockets
import json
import base64
import uuid
import wave
SAMPLE_RATE = 24000
API_KEY = ""
async def stream_tts():
  # Connect to the WebSocket endpoint
  uri = f"wss://api.vogent.ai/api/tts/websocket?apiKey={API_KEY}"
  generation_id = f"gen_{uuid.uuid4()}"
  async with websockets.connect(uri) as websocket:
    print("🔗 Connected to Voicelab WebSocket")
    # Send initial text chunk
    await websocket.send(json.dumps({
      "generationId": generation_id,
      "voiceId": "36b87413-6d7b-421d-8745-bc0897770d1e", # Mabel voice
      "text": "Hello! This is a real-time streaming example.",
      "finalText": False,
      "sampleRate": 24000,
      "cancel": False
    }))
    # Send final text chunk
    await websocket.send(json.dumps({
      "generationId": generation_id,
      "voiceId": "36b87413-6d7b-421d-8745-bc0897770d1e",
      "text": " This demonstrates real-time text-to-speech streaming!",
      "finalText": True,
      "cancel": False
    }))
    audio_chunks = []
    print("Listening for audio")
    # Listen for audio chunks
    async for message in websocket:
      data = json.loads(message)
      if data["type"] == "chunk":
        # Decode and store audio chunk
        audio_data = base64.b64decode(data["audio"])
        audio_chunks.append(audio_data)
        print("🎵 Received audio chunk")
      elif data["type"] == "error":
        print(f"❌ Error: {data['error']}")
        break
      elif data["type"] == "finished":
        print("✅ Streaming complete!")
        with wave.open("streaming_audio.wav", "wb") as wf:
          wf.setnchannels(1)
          wf.setsampwidth(2)
          wf.setframerate(SAMPLE_RATE)
          print("Chunks", len(audio_chunks))
          for chunk in audio_chunks:
            wf.writeframes(chunk)
        print("💾 Audio saved as 'streaming_audio.wav'")
        break
# Run the streaming example
asyncio.run(stream_tts())
```

--------------------------------

### Get Dial Details

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-dial.md

Fetches the details of a specific dial by its ID.

```APIDOC
## GET /dials/{id}

### Description
Retrieves the details of a specific dial, including its associated agent, recordings, and transcript.

### Method
GET

### Endpoint
/dials/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dial.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication. Format: `Bearer <api_key_here>`.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the dial.
- **toNumber** (string) - The phone number the dial was made to.
- **agent** (object) - Details about the agent handling the dial.
- **recordings** (array) - A list of recording URLs for the dial.
- **transcript** (array) - The conversation transcript, including speaker information and timestamps.
- **durationSeconds** (integer) - The total duration of the dial in seconds.
- **status** (string) - The current status of the dial.
- **startedAt** (string) - The timestamp when the dial started.
- **endedAt** (string) - The timestamp when the dial ended.
- **createdAt** (string) - The timestamp when the dial record was created.
- **updatedAt** (string) - The timestamp when the dial record was last updated.

### Response Example
```json
{
 "id": "<string>",
 "toNumber": "<string>",
 "agent": {
  "id": "<string>",
  "name": "<string>",
  "language": "<string>",
  "transcriberParams": {
   "type": "deepgram",
   "keywords": [
    "<string>"
   ]
  },
  "metadata": {},
  "utteranceDetectorConfig": {
   "sensitivity": "ULTRA_FAST",
   "interruptionPlayTimeMs": 123
  },
  "endpointDetectorConfig": {
   "type": "SIMPLE",
   "mode": "CONSERVATIVE"
  },
  "ivrConfiguration": {
   "detectionType": "NONE",
   "versionedPromptId": "<string>",
   "aiVoiceId": "<string>",
   "taggingText": "<string>"
  },
  "idleMessageConfig": {
   "enabled": true,
   "messages": [
    "<string>"
   ],
   "idleDurationMilliseconds": 5001,
   "maxIdleMessages": 2
  },
  "maxDurationSeconds": 10800,
  "defaultVoiceId": "<string>",
  "defaultVersionedPromptId": "<string>",
  "defaultExtractorId": "<string>",
  "linkedFunctionDefinitions": [
   {
    "functionDefinitionId": "<string>",
    "lifecycleMessagesOverride": {
     "started": [
      "<string>"
     ]
    }
   }
  ],
  "fillEmptyStringVariables": true,
  "silenceHangupConfiguration": {
   "type": "DISABLED",
   "silenceDurationSeconds": 123
  },
  "voiceOptionValues": [
   {
    "optionId": "<string>",
    "value": "<string>"
   }
  ]
 },
 "recordings": [
  {
   "url": "<string>"
  }
 ],
 "transcript": [
  {
   "text": "<string>",
   "speaker": "<string>",
   "detailType": "<string>",
   "functionCallId": "<string>",
   "startTimeMs": 123,
   "endTimeMs": 123,
   "functionCalls": [
    {
     "name": "<string>",
     "args": "<string>",
     "functionCallId": "<string>"
    }
   ],
   "nodeTransition": {
    "toNodeId": "<string>",
    "transitionData": {}
   }
  }
 ],
 "durationSeconds": 123,
 "aiResult": {},
 "inputs": {},
 "status": "<string>",
 "dialTaskId": "<string>",
 "fromNumberId": "<string>",
 "startedAt": "2023-11-07T05:31:56Z",
 "endedAt": "2023-11-07T05:31:56Z",
 "createdAt": "2023-11-07T05:31:56Z",
 "updatedAt": "2023-11-07T05:31:56Z",
 "systemResultType": "BUSY",
 "voiceId": "<string>",
 "versionedPromptId": "<string>"
}
```
```

--------------------------------

### Weekly Schedule Format Example

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/platform-overview_batch-dial-jobs.md

Define a weekly schedule for batch dial jobs, specifying days of the week, time slots within those days, and the overall timezone for the schedule.

```json
{
 "schedule": {
  "days": [
   {
    "dayOfWeek": 1, // Monday (0=Sunday, 1=Monday, etc.)
    "timeSlots": [
     {
      "startTime": "09:00",
      "endTime": "12:00"
     },
     {
      "startTime": "13:00",
      "endTime": "17:00"
     }
    ]
   }
  ],
  "timezone": "America/New_York"
 }
}

```

--------------------------------

### Get Extractor

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-extractor.md

Retrieves a specific extractor by its ID and the agent ID.

```APIDOC
## GET /api/agents/{agentId}/extractors/{extractorId}

### Description
Retrieves a specific extractor by its ID and the agent ID.

### Method
GET

### Endpoint
/api/agents/{agentId}/extractors/{extractorId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
- **extractorId** (string) - Required - The ID of the extractor.

### Request Example
```bash
curl --request GET \
 --url https://api.vogent.ai/api/agents/{agentId}/extractors/{extractorId} \
 --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the extractor.
- **name** (string) - The name of the extractor.
- **extractorFieldsJsonSchema** (string) - The JSON schema defining the fields for the extractor.

#### Response Example
```json
{
 "id": "<string>",
 "name": "<string>",
 "extractorFieldsJsonSchema": "<string>"
}
```
```

--------------------------------

### Create Versioned Prompt Request

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_create-versioned-prompt.md

Use this cURL command to send a POST request to create a new versioned prompt. Ensure you replace placeholders like <token> and <agentId> with your actual values. The request body includes details about the AI model, agent type, prompt name, and flow definition.

```bash
curl --request POST \
 --url https://api.vogent.ai/api/agents/{agentId}/versioned_prompts \
 --header 'Authorization: Bearer <token>' \
 --header 'Content-Type: application/json' \
 --data '
{
 "aiModelId": "<string>",
 "agentType": "STANDARD",
 "name": "<string>",
 "prompt": "<string>",
 "flowDefinition": {
  "nodes": [
   {
    "id": "<string>",
    "name": "<string>",
    "type": "<string>",
    "transitionRules": [
     {
      "conditionType": "always",
      "transitionNodeId": "<string>",
      "arrayConditionType": "any",
      "field": "<string>",
      "value": "<string>",
      "values": [
       "<string>"
      ]
     }
    ],
    "nodeData": {}
   }
  ],
  "globalContext": "<string>",
  "aiOpen": true,
  "openingLineType": "INBOUND_ONLY"
 },
 "modelOptionValues": [
  {
   "optionId": "<string>",
   "value": "<string>"
  }
 ]
}
'
```

--------------------------------

### Get Dial Response

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/api-reference_get-dial.md

Details of the response object when retrieving dial information.

```APIDOC
## Get Dial Response

### Description
This section details the structure of the response object returned by the get-dial API, providing information about a specific dial operation.

### Response
#### Success Response (200)
- **id** (string) - Required - Unique identifier for the dial.
- **toNumber** (string) - The phone number the dial was made to.
- **agent** (object) - Information about the agent involved in the dial.
- **recordings** (object[]) - An array of recording objects associated with the dial.
- **transcript** (object[]) - An array of transcript objects from the dial.
- **durationSeconds** (integer) - The duration of the dial in seconds.
- **aiResult** (object) - The results of any AI analysis performed on the dial.
- **inputs** (object) - The input parameters used for the dial operation.
- **status** (string) - The current status of the dial.
- **dialTaskId** (string) - The identifier for the associated dial task.
- **fromNumberId** (string) - The identifier for the originating phone number.
- **startedAt** (string<date-time>) - The timestamp when the dial started.
- **endedAt** (string<date-time>) - The timestamp when the dial ended.
- **createdAt** (string<date-time>) - The timestamp when the dial record was created.
- **updatedAt** (string<date-time>) - The timestamp when the dial record was last updated.
- **systemResultType** (enum<string> | null) - The type of system result for this dial, if applicable. Available options: `BUSY`, `FAILED`, `NO_ANSWER`, `CANCELLED`, `USER_HANGUP`, `COUNTERPARTY_HANGUP`, `TIMEOUT`, `RATE_LIMITED`, `TRANSFERRED`, `AGENT_HANGUP`, `VOICEMAIL_DETECTED_HANGUP`, `LONG_SILENCE_HANGUP`.
- **voiceId** (string) - The identifier for the voice used in the dial.
- **versionedPromptId** (string) - The identifier for the versioned prompt used.
```

--------------------------------

### Customer Service Training Dialogue Generation

Source: https://github.com/crowe452/vogent-docs/blob/main/docs/voicelab_voice-synthesis_advanced-features.md

Create a customer service training dialogue by defining lines with specific voice IDs for different roles. This example demonstrates a common customer support interaction.

```python
training_dialogue = {
  "lines": [
    {"text": "Thank you for calling customer support. How can I assist you today?", "voiceId": "professional-female-1"},
    {"text": "I'm having trouble with my recent order. It hasn't arrived yet.", "voiceId": "conversational-male-1"},
    {"text": "I understand your concern. Let me look up your order details. Can you provide your order number?", "voiceId": "professional-female-1"},
    {"text": "Sure, it's order number 12345.", "voiceId": "conversational-male-1"},
    {"text": "Thank you. I can see your order was shipped yesterday and should arrive by tomorrow.", "voiceId": "professional-female-1"}
  ]
}
response = requests.post("https://api.vogent.ai/tts/multispeaker", headers=headers, json=training_dialogue)

```