> ## Documentation Index
> Fetch the complete documentation index at: https://docs.millis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Millis AI Webhooks Documentation

Millis AI provides flexible webhooks to enhance integration capabilities. This documentation explains the purpose, format, and fields for the **Prefetch Data Webhook** and **End-of-Call Webhook**.

***

## **1. Prefetch Data Webhook**

**Configuration Key in Agent Config**: `extra_prompt_webhook`

The Prefetch Data Webhook is called before the conversation begins. It enables real-time customization and event notifications.

### Configuration

The configuration can be provided in one of the following formats:

* **String**: The URL of the webhook endpoint.
* **Object**:

```json theme={null}
{
  "url": "endpoint",
  "headers": {
    "key": "value"
  }
}
```

### **Use Cases**

1. **Call Notification**: Notify your system about an incoming call by receiving a webhook event.
2. **Metadata Override**: Dynamically override or add session metadata based on external systems.
3. **Extra Prompt**: Provide additional context to the agent's system prompt.

### **Request**

* **Method**: `GET`
* **Query Parameters**:
  * `session_id` (string): Unique session identifier.
  * `agent_id` (string): ID of the agent handling the session.
  * `from` (string): Caller’s phone number (if applicable).
  * `to` (string): Receiver’s phone number (if applicable).
  * Additional session metadata as key-value pairs (if available).

### **Expected Response**

* **Content-Type**: `application/json`.
* **Response Fields**:
  * **`metadata` (object)**: Overrides or extends the current session metadata. Existing keys are updated, and new keys are added.
  * **`extra_prompt` (string)**: Additional text appended to the agent’s system prompt.

### **Response Example**

```json theme={null}
{
  "metadata": {
    "customer_tier": "premium",
    "location": "California"
  },
  "extra_prompt": "The caller is a premium customer from California."
}
```

***

## **2. End-of-Call Webhook**

**Configuration Key in Agent Config**: `session_data_webhook`

The End-of-Call Webhook is triggered after a session concludes. It provides detailed information about the session for logging, analytics, or post-call processing.

### Configuration

The configuration can be provided in one of the following formats:

* **String**: The URL of the webhook endpoint.
* **Object**:

```json theme={null}
{
  "url": "endpoint",
  "headers": {
    "key": "value"
  }
}
```

### **Request**

* **Method**: `POST`
* **Payload** (JSON):
  * **`chat` (string)**: JSON string representing the chat history (user and agent messages).
  * **`function_calls` (array)**: List of external functions invoked during the session.
  * **`ts` (timestamp)**: Session start time.
  * **`duration` (integer)**: Session duration in seconds.
  * **`agent_config` (object)**: Serialized agent configuration.
  * **`agent_id` (string)**: ID of the agent managing the session.
  * **`call_id` (string)**: Unique identifier for the call session.
  * **`chars_used` (integer)**: Number of characters processed during the session.
  * **`session_id` (string)**: Unique session identifier.
  * **`cost_breakdown` (array)**: List of cost components for different services.
    ```json theme={null}
    [
      {
        "type": "stt",
        "provider": "millis",
        "credit": 0.0043
      },
      {
        "type": "tts",
        "provider": "elevenlabs",
        "credit": 0.03
      }
    ]
    ```
  * **`voip` (object)**: Telephony details.
    ```json theme={null}
    {
      "provider": "twilio",
      "from": "+1234567890",
      "to": "+0987654321"
    }
    ```
  * **`recording` (object)**: Call recording details.
    ```json theme={null}
    {
      "recording_url": "https://your-recording-url.com/recording123"
    }
    ```
  * **`metadata` (object)**: Final metadata for the session.
  * **`call_status` (string)**: Status of the call. Possible values:
    * `user-ended`
    * `api-ended`
    * `voicemail-message`
    * `voicemail-hangup`
    * `agent-ended`
    * `timeout`
    * `error`
    * `chat_completion`
  * **`error_message` (string)**: Description of any errors encountered during the session.

### **Example**

**Request URL**:

```http theme={null}
POST https://your-webhook-url.com/session-data
```

**Payload**:

```json theme={null}
{
  "chat": "[{\"role\": \"user\", \"content\": \"Hi, I'd like to book a flight.\"}, {\"role\": \"assistant\", \"content\": \"Sure! Can you provide the destination and date?\"}]",
  "function_calls": [{'name': 'check_status', 'params': {'check': 'true', 'order_id': 6689, 'session_id': '-OA1XVnwRGpaameIakJb'}}],
  "ts": 1729840680.886249,
  "duration": 300,
  "agent_config": {...},
  "agent_id": "agent001",
  "call_id": "call123",
  "chars_used": 1024,
  "session_id": "session123",
  "cost_breakdown": [
    {
      "type": "stt",
      "provider": "millis",
      "credit": 0.05
    }
  ],
  "voip": {
    "provider": "twilio",
    "from": "+1234567890",
    "to": "+0987654321"
  },
  "recording": {
    "recording_url": "https://your-recording-url.com/recording123"
  },
  "metadata": {
    "customer_tier": "gold"
  },
  "call_status": "user-ended",
  "error_message": null
}
```

***

## **Notes**

1. **Prefetch Webhook**:
   * Use this webhook to notify your system about calls, adjust metadata dynamically, or provide extra prompts to enhance conversational context.
2. **End-of-Call Webhook**:
   * Designed for detailed post-call analytics and tracking.
   * Ensure secure storage of sensitive information like call recordings and metadata.
3. **Security**:
   * Use HTTPS for all webhooks.
   * Authenticate requests with headers or API keys as needed.

These webhooks provide a robust way to integrate Millis AI into your existing systems, offering flexibility and advanced customization for voice agent interactions.