Action Types

Complete reference for all actions you can send to the AI Flow service.

Overview

Actions are JSON objects you send back to the AI Flow service in response to events. All actions require a session_id and type field.

Base Action Structure

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "speak"
}

Action Summary

Action Type	Description	Primary Use Case
speak	Speak text or SSML	Respond to user with synthesized speech
audio	Play pre-recorded audio	Play hold music, pre-recorded messages
hangup	End the call	Terminate conversation
transfer	Transfer to another number	Route to human agent or department
barge_in	Manually interrupt playback	Stop current audio immediately

Quick Reference

• Speak Action - Text-to-speech
• Audio Action - Play audio file
• Hangup Action - End call
• Transfer Action - Transfer call

Response Format

HTTP Webhook

Return actions as JSON with 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "type": "speak",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Hello!"
}

Or return 204 No Content if no action is needed:

HTTP/1.1 204 No Content

WebSocket

Send actions as JSON strings:

{
  "type": "speak",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Hello!"
}

Action Flow

Common Patterns

Simple Response

{
  "type": "speak",
  "session_id": "session-123",
  "text": "Hello! How can I help you?"
}

Conditional Response

if "goodbye" in event['text'].lower():
    return {
        "type": "hangup",
        "session_id": event['session']['id']
    }
else:
    return {
        "type": "speak",
        "session_id": event['session']['id'],
        "text": "I understand."
    }

Chaining Actions

You can only return one action per event. To chain actions, use the assistant_speak event:

# First response
if event['type'] == 'user_speak':
    return {
        "type": "speak",
        "session_id": event['session']['id'],
        "text": "Please listen to this message."
    }

# Follow-up after assistant speaks
if event['type'] == 'assistant_speak':
    return {
        "type": "audio",
        "session_id": event['session']['id'],
        "audio": "base64-audio-data"
    }

Next Steps

• Speak Action - Detailed reference
• Event Types - What triggers actions
• Event Flow - Understand the complete flow