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

Outbound Call Flow

For outbound calls initiated via the REST API, the flow is identical to inbound — except that session.direction is "outbound" and the AI flow dials the recipient first.

TIP

Check event.session.direction === "outbound" in your session_start handler to customize the opening message for calls your assistant initiated.

Access Required

Outbound calls require explicit access granted by sipgate support. See the Outbound Calls guide for details.

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