Response Types

Learn about the different ways to respond to events.

Overview

Event handlers can return three types of responses:

1. Simple string - Automatically converted to a speak action
2. Action object - For advanced control
3. null/undefined - No response needed

Simple String Response

The simplest way to respond is to return a string:

onUserSpeak: async (event) => {
  return "Hello, how can I help?";
}

This is automatically converted to:

{
  type: "speak",
  session_id: event.session.id,
  text: "Hello, how can I help?",
}

Action Object Response

For advanced control, return an action object directly:

onUserSpeak: async (event) => {
  return {
    type: "speak",
    session_id: event.session.id,
    text: "Hello!",
    barge_in: {
      strategy: "minimum_characters",
      minimum_characters: 3,
    },
  };
}

Available Action Types

• Speak Action - Text-to-speech response
• Audio Action - Play pre-recorded audio
• Hangup Action - End the call
• Transfer Action - Transfer to another number
• Barge-In Action - Manually interrupt playback

No Response

Return null or undefined when no response is needed:

onAssistantSpeak: async (event) => {
  // Track metrics, no response needed
  trackMetrics(event);
  return null;
}

Type Safety

The SDK provides TypeScript types for all responses:

import type {
  InvocationResponseType,
  AiFlowAction
} from "@sipgate/ai-flow-sdk";

// InvocationResponseType is a union of:
// string | AiFlowAction | null | undefined

onUserSpeak: async (event): Promise<InvocationResponseType> => {
  // You can return any of these types
  return "Hello";                    // string
  // or
  return { type: "speak", ... };    // AiFlowAction
  // or
  return null;                       // null/undefined
}

Examples

Conditional Response

onUserSpeak: async (event) => {
  if (event.text.toLowerCase().includes("goodbye")) {
    return {
      type: "hangup",
      session_id: event.session.id,
    };
  }

  return "How can I help you?";
}

Multiple Actions

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

const sessionState = new Map();

onUserSpeak: async (event) => {
  // Store what we want to do next
  sessionState.set(event.session.id, "play_audio");

  return "Please listen to this message.";
},

onAssistantSpeak: async (event) => {
  const nextAction = sessionState.get(event.session.id);

  if (nextAction === "play_audio") {
    sessionState.delete(event.session.id);
    return {
      type: "audio",
      session_id: event.session.id,
      audio: base64AudioData,
    };
  }

  return null;
}

Next Steps

• Action Types - Complete reference for all actions
• API Reference - Full API documentation