Skip to main content
SIP Headers Transfer enables you to integrate GenerativeAgent with your existing SIP telephony infrastructure by passing context directly in SIP headers. This approach eliminates the need for API calls during the transfer process, making it simpler to implement but with limited context complexity due to SIP header size constraints.

​
How it works

At a high level, SIP Headers Transfer works by:
  1. Transfer to ASAPP: You transfer the call to ASAPP using SIP with context passed in headers
  2. GenerativeAgent handles the conversation: Transfer the call to GenerativeAgent via SIP so it can talk directly to the customer
  3. Return control: When GenerativeAgent has completed the call, it will transfer the call back to your system over SIP with return and transfer variables
SIP Headers Transfer Flow
  1. Incoming Call: A customer calls your existing phone number
  2. IVR Processing: Your existing IVR system processes the call and determines when to transfer to GenerativeAgent
  3. Transfer the call: Your system transfers the call to ASAPP’s static SIP domain with context passed in SIP headers
  4. Receive the returned SIP transfer: When GenerativeAgent has completed the call, it will transfer the call back to your return URI
  5. Process the return data: Your system extracts the context from the Refer-To URI parameters and handles the call flow

​
Prerequisites

Before implementing SIP Headers Transfer, you need:
  • Configure Tasks and Functions
  • Contact your ASAPP account team to enable SIP transfers
    • This includes determining how many concurrent calls you need to support, SIP infrastructure requirements, etc.
  • Configure SIP server authentication: ASAPP requires authentication for all incoming SIP requests to ensure security. You must provide one or both of the following authentication methods:
    • IP whitelist: The IP address(es) of your SIP server(s) that ASAPP will allow to make SIP requests
    • Username and password: SIP authentication credentials that ASAPP will use to validate your SIP requests
    Security requirement: ASAPP cannot accept unauthenticated SIP requests. You must provide at least one authentication method (IP whitelist and/or username/password) during setup.
  • ASAPP will provide a static SIP domain for you to transfer to
  • Provide your SIP return URI: You must provide ASAPP with your SIP URI for return transfers
Unlike API-based transfers, SIP Headers Transfer does not require API credentials as context is passed directly in the SIP headers.

​
SIP Return URI Configuration

You need to provide ASAPP with your SIP return URI configuration to enable return transfers. This includes:

​
Return Transfer Methods

Choose the appropriate return transfer method based on your call flow needs:
Transfer MethodBehaviorUse Case
REFERStandard blind transfer - sends REFER message to your return URITransfer back to you after ASAPP completes
INVITEKeeps ASAPP in call flow for continued transcriptionProvide end-to-end conversation understanding for GenerativeAgent
Cost Implications: INVITE transfer method has higher cost implications that need to be aligned with your sales team before implementation. Contact your ASAPP representative to discuss pricing for this transfer method.

​
Required Configuration

When setting up SIP Headers Transfer, provide ASAPP with:
  • SIP Return URI: The complete SIP URI where ASAPP should transfer calls back to
  • Transfer Method: Whether to use REFER or INVITE for return transfers
  • Authentication (INVITE only): If using INVITE method, specify whether to use username/password authentication

​
Step 2: Transfer the call to ASAPP

Transfer the call to ASAPP using SIP. ASAPP will provide a static SIP domain for you to transfer to.
Authentication required: ASAPP will authenticate your SIP request using the IP whitelist and/or username/password credentials you provided during setup. Your SIP request must pass authentication or it will be rejected.
You have several headers you can use to pass context to ASAPP:
HeaderDescription
X-GA-taskNameThe entry task for GenerativeAgent to handle the call
X-GA-extConversationIdThe external conversation ID for the call
X-GA-customerIdThe customer ID for the call
X-GA-iv-*Add any number of input variables with this prefix. These can be referenced in the task instructions
For input variables, use the prefix X-GA-iv- followed by your variable name. For example, an input variable named userName would be passed as X-GA-iv-userName.
Example SIP Transfer
INVITE sip:asapp-endpoint.com SIP/2.0
Via: SIP/2.0/UDP your-sbc.example.com:5060
From: <sip:customer@your-sbc.example.com>
To: <sip:asapp-endpoint.com>
Call-ID: call-12345@your-sbc.example.com
CSeq: 1 INVITE
X-GA-taskName: call_routing
X-GA-extConversationId: conv-12345
X-GA-customerId: cust-67890
X-GA-iv-accountNumber: 3434
X-GA-iv-name: John Doe
X-GA-iv-priority: high
After connecting, GenerativeAgent will handle the conversation using the provided context.

​
Step 3: Handle the return transfer

To transfer back a call to your system, GenerativeAgent will perform a SIP transfer back to you using the method you configured (REFER or INVITE). The transfer method determines how the call is returned: REFER Transfer: GenerativeAgent sends a SIP REFER message to your return URI. The transfer will send back the list of referenceVariables and transferVariables as query params in the Refer target (Refer-To). INVITE Transfer: GenerativeAgent sends a SIP INVITE to your return URI. ASAPP will continue to transcribe the call to provide end-to-end conversation understanding for GenerativeAgent. For REFER transfers, the following parameters are sent as query params in the Refer-To header:
ParameterDescription
X-GA-extConIdThe conversation ID you provided
X-GA-transferTransfer type: AGENT (unable to help) or SYSTEM (called system transfer function)
X-GA-rv-*Each reference variable with this prefix
X-GA-tv-*Each transfer variable with this prefix
These are defined as part of the System Transfer function within the GenerativeAgent configuration.
Example REFER Return Transfer
Refer-To: sip:your-sbc.example.com?X-GA-extConId=conv-12345&X-GA-transfer=SYSTEM&X-GA-tv-next_action=schedule_callback&X-GA-tv-priority=high&X-GA-rv-account_balance=1250.00&X-GA-rv-last_payment_date=2025-01-10

​
Header Size Limit

There is a 1024 character limit for all context data. Headers are added in this order:
  1. Transfer variables (X-GA-tv-*) - added first
  2. Reference variables (X-GA-rv-*) - added second
The system stops adding variables when it reaches the limit. Any remaining variables are dropped, so use shorter variable names and values to maximize the data you can transfer. The System Transfer function determines which variables are included, so make sure the total size of the variables you pass does not exceed this limit.

​
Step 4: Process the return data

The processing depends on the transfer method you configured: For REFER transfers: When you receive the REFER message, extract the context from the Refer-To URI parameters:
  1. Parse the Refer-To URI to extract all parameters
  2. Identify the transfer type from X-GA-transfer:
    • AGENT: GenerativeAgent was unable to help and needs human agent escalation
    • SYSTEM: GenerativeAgent called a system transfer function to hand control back to your system
  3. Extract variables:
    • Reference variables (X-GA-rv-*): Context information about the customer and conversation
    • Transfer variables (X-GA-tv-*): Data that should be passed to the next system or agent
Use this information to handle the call according to your business logic, such as routing to an agent or handling call disposition.

​
Next Steps

Now that you understand how SIP Headers Transfer works, here are some important next steps to consider:

Configuration Overview

Learn how to configure GenerativeAgent’s behaviors, tasks, and communication style

System Transfer Functions

Configure system transfer functions to control what data is returned in transfer variables

Input Variables

Learn how to structure input variables for optimal context passing

Go Live

Follow the deployment checklist to launch GenerativeAgent in your production environment
⌘I