Event Flow

Understand the complete lifecycle of events and actions in AI Flow.

Complete Flow Diagram

Sequence Diagram

Event Lifecycle

1. Session Start

Event:

{
  "type": "session_start",
  "session": {
    "id": "session-123",
    "phone_number": "+1234567890",
    "from_phone_number": "+9876543210",
    "to_phone_number": "+1234567890"
  }
}

2. User Speak

Event:

{
  "type": "user_speak",
  "text": "Hello",
  "session": {
    "id": "session-123"
  }
}

3. Assistant Speak

Event:

{
  "type": "assistant_speak",
  "text": "Hello! How can I help?",
  "duration_ms": 2000,
  "speech_started_at": 1234567890,
  "session": {
    "id": "session-123"
  }
}

4. Assistant Speech Ended

Event:

{
  "type": "assistant_speech_ended",
  "session": {
    "id": "session-123"
  }
}

5. User Barge In

Event:

{
  "type": "user_speak with barged_in flag",
  "text": "Wait",
  "session": {
    "id": "session-123"
  }
}

6. Session End

Event:

{
  "type": "session_end",
  "session": {
    "id": "session-123"
  }
}

State Management

Response Timing

Best Practices

1. Respond Quickly - Keep response times under 1 second
2. Handle All Events - Even if you don't need to respond
3. Clean Up State - Use session_end for cleanup
4. Track Metrics - Use assistant_speak for analytics
5. Handle Errors - Always return valid responses or 204

Next Steps

• Event Types - Complete event reference
• Action Types - Complete action reference
• HTTP Webhooks - HTTP integration
• WebSocket - WebSocket integration