SIPHON logo

Outbound Calls

Outbound Calls

Initiate phone calls from your code.

Overview

SIPHON provides a simple API to trigger outbound calls. This is useful for appointment reminders, automated surveys, or callbacks.

Provider-specific SIP examples (Twilio, Telnyx, Plivo, Wavix): Provider-specific quickstarts

Outbound calling has two pieces:

  • Your agent worker (Agent) must be running.
  • Your application places a call using Call(...).start().

This page shows the high-level API. For details, see:

Call(...) parameters

Call(...) configures one outbound call. The key parameters are:

  • agent_name
    • Must match the agent worker you are running.
  • number_to_call (required)
    • The destination phone number.
  • sip_trunk_id
    • Use an existing outbound trunk.
  • sip_trunk_setup
    • Provide SIP credentials so SIPHON can look up or create an outbound trunk.
  • number_to_call_from
    • The caller-id / from-number (optional). If omitted, SIPHON will try to infer it from the trunk.
  • wait_until_answered (default False)
    • If True, SIPHON will wait until the call is answered before returning.

Optional agent config (for per-call overrides):

  • llm, stt, tts
  • system_instructions, greeting_instructions

Place an outbound call (basic)

import os
from dotenv import load_dotenv
from siphon.telephony.outbound import Call

load_dotenv()

call = Call(
    agent_name="Receptionist",
    sip_trunk_id=os.getenv("SIP_TRUNK_ID"),
    number_to_call_from=os.getenv("FROM_NUMBER"),
    number_to_call=os.getenv("TO_NUMBER"),
)

result = call.start()
print(result)

Note: agent_name must match the agent worker name you run with Agent(...).dev() / Agent(...).start().

sip_trunk_setup

If you don’t have a trunk id, you can pass credentials and SIPHON will reuse or create an outbound trunk.

import os
from dotenv import load_dotenv
from siphon.telephony.outbound import Call

load_dotenv()

call = Call(
    agent_name="Receptionist",
    sip_trunk_setup={
        "name": "telnyx-primary",
        "sip_address": "sip.telnyx.com",
        "sip_number": os.getenv("FROM_NUMBER"),
        "sip_username": os.getenv("SIP_USERNAME"),
        "sip_password": os.getenv("SIP_PASSWORD"),
    },
    number_to_call="+15550200",
)

call.start()

The fields in sip_trunk_setup map to SIP provider settings:

  • name
  • sip_address
  • sip_number
  • sip_username
  • sip_password

Return value

Call.start() returns a dict with:

  • dispatch_id
  • sip_participant_id
  • sip_call_id
  • error

error is None on success. On failure, it may be:

  • dispatch_error: ... (agent dispatch creation failed)
  • sip_error: ... (dialing / SIP participant creation failed)

Next