Appearance

Outbound Calls ​

Initiate outbound calls directly from your assistant using assistant.call().

Access Required

Outbound calls are only available upon request and after a positive review by sipgate support. Please contact support to request access before using this feature.

Setup ​

Pass token when creating the assistant. baseUrl is optional and defaults to https://api.sipgate.com.

typescript
import { AiFlowAssistant } from "@sipgate/ai-flow-sdk";

const assistant = AiFlowAssistant.create({
  token: process.env.SIPGATE_TOKEN,

  onSessionStart: async (event) => {
    if (event.session.direction === "outbound") {
      return "Hello! This is an automated call. Do you have a moment?";
    }
    return "Hello! How can I help you today?";
  },

  onUserSpeak: async (event) => {
    return processWithLLM(event.text);
  },
});

Initiating a Call ​

typescript
await assistant.call({
  aiFlowId: "e3670012-96a3-4ae5-ac42-87abe22015c3",
  billingDevice: "e2",             // provided by sipgate support during onboarding
  toPhoneNumber: "+4915790000687", // full E.164 format
});
ParameterTypeDescription
aiFlowIdstringID of the Flow to use for the call
billingDevicestringBilling device suffix, provided during onboarding
toPhoneNumberstringTarget phone number in full E.164 format, e.g. +4915790000687. The leading + is optional — it is added automatically when missing.

call() resolves when the call has been successfully initiated (201 Created). It throws if the request fails.

Handling the Session ​

Once the recipient answers, the normal event flow begins. Your existing handlers (onSessionStart, onUserSpeak, etc.) are called exactly as for inbound calls.

Check event.session.direction to distinguish outbound from inbound sessions:

typescript
onSessionStart: async (event) => {
  if (event.session.direction === "outbound") {
    // Your assistant placed this call
    return "Hi, I'm calling from Example Corp regarding your appointment.";
  }
  // Inbound call
  return "Hello! How can I help you?";
},

The direction field is available on the session object of every event.

Complete Example ​

typescript
import { AiFlowAssistant } from "@sipgate/ai-flow-sdk";
import express from "express";

const assistant = AiFlowAssistant.create({
  token: process.env.SIPGATE_TOKEN,

  onSessionStart: async (event) => {
    if (event.session.direction === "outbound") {
      return "Hello! This is an automated reminder from Example Corp. Your appointment is tomorrow at 10am. Press 1 to confirm or say 'cancel' to cancel.";
    }
    return "Hello! How can I help you?";
  },

  onUserSpeak: async (event) => {
    const text = event.text.toLowerCase();
    if (text.includes("confirm") || text.includes("1")) {
      return [
        { type: "speak", session_id: event.session.id, text: "Great, your appointment is confirmed. Goodbye!" },
        { type: "hangup", session_id: event.session.id },
      ];
    }
    if (text.includes("cancel")) {
      await cancelAppointment(event.session.id);
      return [
        { type: "speak", session_id: event.session.id, text: "Your appointment has been cancelled. Goodbye!" },
        { type: "hangup", session_id: event.session.id },
      ];
    }
    return "I didn't catch that. Say 'confirm' to confirm or 'cancel' to cancel your appointment.";
  },
});

// Webhook server (receives events when calls connect)
const app = express();
app.use(express.json());
app.post("/webhook", assistant.express());
app.listen(3000);

// Initiate the call
await assistant.call({
  aiFlowId: process.env.AI_FLOW_ID!,
  billingDevice: "e2",
  toPhoneNumber: "+4915790000687",
});

Next Steps ​