Custom SIP

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.

​

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",
      "sip_headers": {
        "X-Customer-ID": conv.state.customer_id,
        "X-Call-Type": "Support"
      }
    }
  }
}

​

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
      }
    }
  }
}

These code patterns are especially useful when dynamic call routing or SIP metadata injection is needed mid-conversation.