Session Start Event

Triggered when a new call session begins.

Event Structure

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

Fields

Field	Type	Required	Description
type	string	Yes	Always "session_start"
session.id	string (UUID)	Yes	Unique session identifier
session.account_id	string	Yes	Account identifier
session.phone_number	string	Yes	Phone number for this flow session
session.direction	string	No	"inbound" or "outbound"
session.from_phone_number	string	Yes	Phone number of the caller
session.to_phone_number	string	Yes	Phone number of the callee

Response

You can return any action or 204 No Content. Common responses:

Greet the User

{
  "type": "speak",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "text": "Welcome! How can I help you today?"
}

Play Welcome Audio

{
  "type": "audio",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "audio": "base64-encoded-wav-data"
}

No Response

HTTP/1.1 204 No Content

Examples

Python (Flask)

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

    if event['type'] == 'session_start':
        session_id = event['session']['id']
        return jsonify({
            'type': 'speak',
            'session_id': session_id,
            'text': 'Welcome! How can I help you?'
        })

    return '', 204

Node.js (Express)

app.post('/webhook', (req, res) => {
  const event = req.body;

  if (event.type === 'session_start') {
    return res.json({
      type: 'speak',
      session_id: event.session.id,
      text: 'Welcome! How can I help you?'
    });
  }

  res.status(204).send();
});

Go

func webhook(w http.ResponseWriter, r *http.Request) {
    var event map[string]interface{}
    json.NewDecoder(r.Body).Decode(&event)

    if event["type"] == "session_start" {
        session := event["session"].(map[string]interface{})
        action := map[string]interface{}{
            "type":       "speak",
            "session_id": session["id"],
            "text":       "Welcome! How can I help you?",
        }
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(action)
        return
    }

    w.WriteHeader(http.StatusNoContent)
}

Use Cases

• Initialize session state - Set up conversation context
• Greet the user - Welcome message
• Log call information - Track incoming calls
• Route based on number - Different greetings for different numbers

Best Practices

1. Respond quickly - Keep greeting under 2 seconds
2. Initialize state - Set up any session tracking
3. Log session info - Record call metadata
4. Handle errors - Always return a valid response

Next Steps

• User Speak Event - Handle user input
• Action Types - All available actions
• Event Flow - Understand the complete flow