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:
{
  "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

{
  "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:
{
  "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.
      [
        {
          "type": "stt",
          "provider": "millis",
          "credit": 0.0043
        },
        {
          "type": "tts",
          "provider": "elevenlabs",
          "credit": 0.03
        }
      ]
      
    • voip (object): Telephony details.
      {
        "provider": "twilio",
        "from": "+1234567890",
        "to": "+0987654321"
      }
      
    • recording (object): Call recording details.
      {
        "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:

POST https://your-webhook-url.com/session-data

Payload:

{
  "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.