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.

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

await assistant.call({
  aiFlowId: "e3670012-96a3-4ae5-ac42-87abe22015c3",
  billingDevice: "e2",             // provided by sipgate support during onboarding
  toPhoneNumber: "+4915790000687", // E.164 format
});

Parameter	Type	Description
aiFlowId	string	ID of the AI flow to use for the call
billingDevice	string	Billing device suffix, provided during onboarding
toPhoneNumber	string	Target phone number in E.164 format

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:

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

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

• API Reference — call() method and all options
• Outbound Calls (API) — raw HTTP reference
• Event Types — complete event reference