Event Types

Complete reference for all events sent by the AI Flow service.

Overview

Events are JSON objects sent from the AI Flow service to your application. All events include a type field and session information.

Base Event Structure

All events include session information:

{
  "session": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "account_id": "account-123",
    "phone_number": "+1234567890",
    "direction": "inbound",
    "from_phone_number": "+9876543210",
    "to_phone_number": "+1234567890"
  }
}

Event Types

Event Type	Description	When Triggered
session_start	Call session begins	When a new call is initiated
user_speak	User speech detected	After speech-to-text completes (includes barged_in flag if user interrupted)
assistant_speak	Assistant finished speaking	After TTS playback completes
assistant_speech_ended	Assistant finished speaking	After speech playback ends
user_input_timeout	User input timeout reached	When no speech detected after timeout
session_end	Call session ends	When the call terminates

Quick Reference

• Session Start - Call begins
• User Speak - User speaks (includes barge-in detection)
• Assistant Speak - Assistant speaks
• Assistant Speech Ended - Assistant finished speaking
• User Input Timeout - Timeout reached waiting for user
• Session End - Call ends

Event Flow

Handling Events

HTTP Webhook

@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json
    event_type = event['type']

    if event_type == 'session_start':
        # Handle session start
        pass
    elif event_type == 'user_speak':
        # Handle user speech
        pass
    # ... handle other events

WebSocket

ws.on('message', (data) => {
  const event = JSON.parse(data.toString());

  switch (event.type) {
    case 'session_start':
      // Handle session start
      break;
    case 'user_speak':
      // Handle user speech
      break;
    // ... handle other events
  }
});

Response Requirements

• session_start: Can return any action or 204 No Content
• user_speak: Can return any action or 204 No Content (check barged_in flag for interruptions)
• assistant_speak: Can return any action or 204 No Content
• assistant_speech_ended: Can return any action or 204 No Content
• user_input_timeout: Can return any action or 204 No Content
• session_end: No action allowed, cleanup only

Next Steps

• Session Start Event - Detailed reference
• User Speak Event - Detailed reference
• Action Types - How to respond to events