Webhooks

Millis AI Webhooks Documentation

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.