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:

{
  "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": "[phone]",
      "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": "[phone]",
    "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.