SIP Headers Transfer

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:

Transfer to ASAPP: You transfer the call to ASAPP using SIP with context passed in headers
GenerativeAgent handles the conversation: Transfer the call to GenerativeAgent via SIP so it can talk directly to the customer
Return control: When GenerativeAgent has completed the call, it will transfer the call back to your system over SIP with return and transfer variables

Detailed Flow

Incoming Call: A customer calls your existing phone number
IVR Processing: Your existing IVR system processes the call and determines when to transfer to GenerativeAgent
Transfer the call: Your system transfers the call to ASAPP’s static SIP domain with context passed in SIP headers
Receive the returned SIP transfer: When GenerativeAgent has completed the call, it will transfer the call back to your return URI
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 Method	Behavior	Use Case
REFER	Standard blind transfer - sends REFER message to your return URI	Transfer back to you after ASAPP completes
INVITE	Keeps ASAPP in call flow for continued transcription	Provide 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:

Header	Description
`X-GA-taskName`	The entry task for GenerativeAgent to handle the call
`X-GA-extConversationId`	The external conversation ID for the call
`X-GA-customerId`	The 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:

Parameter	Description
`X-GA-extConId`	The conversation ID you provided
`X-GA-transfer`	Transfer 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:

Transfer variables (X-GA-tv-*) - added first
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:

Parse the Refer-To URI to extract all parameters
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
These are the only two values sent on X-GA-transfer, because a return transfer is only ever generated when GenerativeAgent hands the call back deliberately. If the customer hangs up, or GenerativeAgent or ASAPP hits an internal error, no REFER or INVITE is sent at all. See Handling errors and disconnects for how to detect and recover from that case.
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.

Handling errors and disconnects

Unlike the API-based SIP Transfers integration, SIP Headers Transfer has no GET /call-transfers endpoint to check status or output context after the fact. All context is delivered inline on the return transfer itself, so your error handling has to be based on what your SIP session observes, not on a follow-up query. If the return transfer arrives normally GenerativeAgent completed the conversation, either through a system transfer or by giving up and handing back to your IVR, and sent a REFER or INVITE back to your return URI as configured. Extract X-GA-transfer, the X-GA-rv-* reference variables, and the X-GA-tv-* transfer variables directly from the headers or URI parameters as described in Step 4. There is nothing further to fetch. If the SIP connection errors or is dropped before a return transfer arrives This covers both a customer hangup and an internal error on GenerativeAgent’s or ASAPP’s side. In a header-based integration neither produces a REFER or INVITE back to you, so from your system’s perspective they look the same: the call simply ends without a return transfer.

Do not expect a DISCONNECT or INTERNAL_ERROR value on X-GA-transfer. No return transfer means no headers are sent at all.
To resume the conversation where it left off, initiate a new transfer to ASAPP reusing the same X-GA-extConversationId header. GenerativeAgent picks the conversation back up using that identifier.
If you do not want to resume, for example the customer already hung up and is not coming back, no further action is needed. There is no context to fetch.

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

Getting Started

Build

Tasks & Functions

Agents

Test

Observe

Integrate

Reporting & Security

SIP Headers Transfer

How it works

Prerequisites

SIP Return URI Configuration

Return Transfer Methods

Required Configuration

Step 2: Transfer the call to ASAPP

Step 3: Handle the return transfer

Header Size Limit

Step 4: Process the return data

Handling errors and disconnects

Next Steps

Configuration Overview

System Transfer Functions

Input Variables

Go Live

​How it works

​Prerequisites

​SIP Return URI Configuration

​Return Transfer Methods

​Required Configuration

​Step 2: Transfer the call to ASAPP

​Step 3: Handle the return transfer

​Header Size Limit

​Step 4: Process the return data

​Handling errors and disconnects

​Next Steps

Configuration Overview

System Transfer Functions

Input Variables

Go Live

How it works

Prerequisites

SIP Return URI Configuration

Return Transfer Methods

Required Configuration

Step 2: Transfer the call to ASAPP

Step 3: Handle the return transfer

Header Size Limit

Step 4: Process the return data

Handling errors and disconnects

Next Steps