Skip to main content
Custom SIP (Session Initiation Protocol) integration in PolyAI allows you to leverage SIP headers for tailoring agent behaviors based on call-specific metadata. By accessing SIP headers, builders can extract details like caller ID, dialed number, or other metadata transmitted through the SIP protocol.

​
What is Custom SIP?

SIP headers provide a structured format for transmitting metadata during VoIP calls. This metadata can include details about the caller, the recipient, and other contextual information, enabling more personalized and context-aware interactions.

​
Key attributes

The conv object provides access to SIP-related attributes that you can use in your agent logic:

​
sip_headers

  • Description: A dictionary containing SIP headers and their corresponding values.
  • Use case: Extract caller-specific metadata or route calls dynamically.
  • Example:
caller_id = conv.sip_headers.get("From", "Unknown Caller")
print(f"Caller ID: {caller_id}")

​
caller_number

  • Description: The phone number of the caller.
  • Use case: Personalize responses based on the caller’s number.
  • Example:
if conv.caller_number == "+15551234567":
    conv.goto_flow("vip_support_flow")
else:
    conv.goto_flow("general_support_flow")

​
callee_number

  • Description: The phone number the caller dialed.
  • Use case: Determine routing based on the number dialed.
  • Example:
dialed_number = conv.callee_number
if dialed_number == "+15557654321":
    conv.state.branch = "North Branch"
else:
    conv.state.branch = "South Branch"

​
How to Use Custom SIP

  1. Access SIP headers:
    • Use conv.sip_headers to retrieve metadata from the SIP protocol.
    • This is particularly useful for identifying caller attributes or custom routing.
  2. Dynamic routing:
    • Utilize caller_number and callee_number to configure routing flows based on incoming and dialed numbers.
  3. Store data for contextual responses:
    • Save SIP-related information into conv.state to persist data across the conversation.
    • Example:
conv.state.metadata = {
    "caller_id": conv.sip_headers.get("From", "Unknown"),
    "dialed_number": conv.callee_number,
}

​
Use cases

  • VIP routing: Automatically direct high-priority callers to specific support flows.
  • Branch-specific handling: Route calls to the appropriate branch or location based on the number dialed.
  • Dynamic personalization: Use SIP headers to provide tailored greetings or responses.
For more details on the Conversation object, visit the conv object page.

​
Initiating SIP transfers programmatically

In addition to configuring call handoffs in the UI, you can initiate SIP transfers directly from a function using return values. This is especially useful when routing logic depends on in-conversation data or SIP header values. You can use two methods: INVITE and REFER. These are mutually exclusive with UI-based Call Handoffs and require manual setup.

​
When to use INVITE vs REFER

Use SIP INVITE when:
  • You want PolyAI to remain in the call as a bridge between the caller and the target
  • You need to monitor or record the transferred call
  • You want to inject custom SIP headers for the outbound leg
  • You’re transferring to a PSTN number or external SIP URI
Use SIP REFER when:
  • You want the Session Border Controller (SBC) to handle the transfer directly
  • You want to remove PolyAI from the call path after transfer (reduces latency and infrastructure load)
  • Your SBC supports REFER and has “Take Back and Transfer” enabled
  • You’re performing an attended or blind transfer within the same SIP domain

​
SIP INVITE

This creates a new call and bridges the user with the target. Use this when you want PolyAI to act as a bridge. 
return {
  "handoff": {
    "invite": {
      "phone_number": "2222222",  // SIP URI or PSTN number
      "outbound_caller_id": conv.caller_number,
      "outbound_endpoint": "YOUR_OUTBOUND_ENDPOINT_NAME",  // Provided by PolyAI during setup
      "sip_headers": {
        "X-Customer-ID": conv.state.customer_id,
        "X-Call-Type": "Support"
      }
    }
  }
}
The outbound_endpoint value is provided by PolyAI during your SIP integration setup. Contact your PolyAI account manager or support@poly.ai if you need this value.

​
SIP REFER

This instructs the Session Border Controller to take over and transfer the call. 
return {
  "handoff": {
    "refer": {
      "phone_number": conv.caller_number,  // Number PolyAI used
      "refer_to": "sip:support@example.com",  // SIP URI or number
      "sip_headers": {
        "X-Caller-ID": conv.caller_number
      }
    }
  }
}
To avoid 405 errors, make sure the “Take Back and Transfer” setting is enabled when using SIP REFER on any platform with that setting.
These code patterns are especially useful when dynamic call routing or SIP metadata injection is needed mid-conversation.