Skip to main content
API-based SIP transfers use REST API calls to create call transfers with rich context input and output. This approach provides unlimited complexity for context data but requires API integration in your system.
Run In Postman

​
How it works

At a high level, API-based SIP transfers work by:
  1. Request a SIP URI: Your system requests a destination SIP URI from ASAPP via API call. You can provide complex context to the call.
  2. GenerativeAgent handles the conversation: Transfer the call to GenerativeAgent via the SIP URI 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 specified return URI and your system will fetch the resulting context and handle the rest of the call flow.
SIP 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. Request a SIP URI: Your system requests a destination SIP URI from ASAPP via API call. You can provide complex context to the call.
  4. Transfer the call: Your system transfers the call to the destination SIP URI via SIP protocol.
  5. Detect call completion: When GenerativeAgent has completed the call, it will transfer the call back to your return URI.
  6. Fetch the call context: Your system will fetch the context, which includes the transfer type, from the call via API call.
  7. Handle the call: Using the context and transfer type, your system handles the agent escalation, call disposition, or any other steps in your call flow.

​
Before you Begin

Before implementing API-based SIP Transfers, you need:
  • Get your API Key Id and Secret
    • Ensure your API key has been configured to access GenerativeAgent APIs. Reach out to your ASAPP team if you need access enabled.
  • 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.
  • Get your SIP URI for transfers: Obtain the static SIP URI from ASAPP that you’ll use to route calls to GenerativeAgent
  • Configure transfer settings: Set up your default transfer type and authentication credentials (for INVITE transfers) with your ASAPP account team

​
Transfer Types

Your transfer type is configured as part of your static setup with ASAPP. Choose the appropriate transfer type based on your call flow needs:
Transfer TypeBehaviorUse Case
BYEGenerativeAgent disconnects when doneYour system handles the disconnect (lower cost)
REFERStandard blind transfer - sends REFER message to your return URITransfer to another system after ASAPP completes (higher cost)
INVITEKeeps ASAPP in call flow for continued transcriptionProvide end-to-end conversation understanding for GenerativeAgent (higher cost)
Cost Implications: REFER and INVITE transfer types have higher cost implications that need to be aligned with your sales team before implementation. Contact your ASAPP representative to discuss pricing for these transfer types.
For INVITE transfers, you can provide authentication credentials (username/password) as part of your static configuration with ASAPP.

​
Step 1: Create a call transfer

To transfer a call to GenerativeAgent, you need to create a call-transfer. A call transfer is the attempt to transfer a call to GenerativeAgent. This resource will include context and configuration for the transfer, but you’ll route the call to the static SIP URI provided by ASAPP. To create a call transfer, you need to specify:
ParameterDescription
idYour unique identifier for the call transfer. You will use this later to fetch the call transfer result.
externalConversationIdYour unique identifier for the conversation. This allows you to reconnect the customer to the same conversation and is used in reporting.
typeSpecify a type of SIP.
sip.returnURIOnly used for REFER and INVITE transfer types.

The SIP URI to transfer the call back to when the conversation ends. You can include any parameters in the URI (e.g., User-to-User headers, custom parameters) and ASAPP will send the URI back exactly as provided. Maximum length: 1024 characters.
inputContextOptionally specify the taskName and inputVariables to trigger GenerativeAgent with specific task information and variables.
curl --location 'https://api.sandbox.asapp.com/generativeagent/v1/call-transfers' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "id":"[Your Transfer Id]",
    "externalConversationId":"[Your Conversation Id]",
    "type": "SIP",
    "sip": {
        "returnURI": "sip:user@customer-sbc.example.com;User-to-User=UUI-12345"
    },
    "inputContext": {
        "taskName":"call_routing",
        "inputVariables":{
            "accountNumber":"3434",
            "name": "John Doe"
        }
    }
}'
A successful request returns 200 with the call transfer data: 
{
    "id": "[Your Transfer Id]",
    "externalConversationId": "[Your Conversation Id]",
    "status": "ACTIVE",
    "type": "SIP",
    "inputContext": {
        "taskName": "call_routing",
        "inputVariables": {
            "accountNumber": "3434",
            "name": "John Doe"
        }
    },
    "sip": {
        "returnURI": "sip:user@customer-sbc.example.com;User-to-User=UUI-12345"
    },
    "createdAt": "2025-01-15T13:06:00Z"
}
Save the id from the response; you will need it to pass as the X-ASAPP-CallTransferId header when transferring the call and to query the call transfer result in Step 3.

​
Step 2: Transfer the call and handle the response

Once you’ve created the call transfer, you need to route the call to GenerativeAgent and handle the return transfer when the conversation ends.
1

Send the call to ASAPP

Transfer the call to the static SIP URI provided by ASAPP during setup. Include the call transfer id as the X-ASAPP-CallTransferId header in your SIP transfer.
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.
Once you transfer the call, GenerativeAgent is given the input context, if provided, and talks to the customer.The specific implementation on how to perform a SIP transfer depends on your call center system.
With SIP transfers, the customer is calling into your phone number so your SBC/PBX is handling the inbound call. Your system maintains visibility and ultimate ownership of the call the entire time.
2

Handle the return transfer and detect call completion

Two scenarios are possible during the conversation that you must handle accordingly:
  1. GenerativeAgent completes the conversation with an agent escalation or a system transfer
    • GenerativeAgent has determined it needs to return the call to your system, either to an agent escalation or a system transfer.
    • GenerativeAgent handles the call return based on your transfer type:
      • BYE Transfer: GenerativeAgent disconnects the call. Your system needs to detect the disconnect and proceed to fetch the call context.
      • REFER Transfer: GenerativeAgent sends a SIP REFER message to your return URI. Your system should accept and handle the REFER, and then fetch the call context.
      • INVITE Transfer: GenerativeAgent sends a SIP INVITE to your return URI. Your system should accept the INVITE and then fetch the call context. ASAPP will continue to transcribe the call until the call is ended.
    • The output context of the conversation can be retrieved.
  2. Customer hangs up the phone call
    • When the customer hangs up, there are no output variables since GenerativeAgent didn’t close out the conversation.
    • No transfer is performed and no output context will be available for fetching.
The call completion detection is crucial for maintaining proper call flow control and ensuring you can fetch the conversation context before handling the next steps.

​
Step 3: Fetch the call context

After handling the return transfer in Step 2, retrieve the call transfer result and outputContext to understand what happened during the conversation.
Only fetch call context when GenerativeAgent handed back the call: You can only retrieve meaningful output context when GenerativeAgent completed the conversation and transferred the call back to your system. If the customer hung up during the conversation, there will be no output context available for fetching.
To retrieve the call transfer result, you need to fetch the call-transfers with the id of the original call transfer: 
curl --location 'https://api.sandbox.asapp.com/generativeagent/v1/call-transfers/[Your Transfer Id]' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>'
A successful request returns 200 with call transfer data: 
{
    "id": "[Your Transfer Id]",
    "externalConversationId": "[Your Conversation Id]",
    "status": "COMPLETED",
    "createdAt": "2025-01-15T13:06:00Z",
    "callReceivedAt": "2025-01-15T13:06:30Z",
    "completedAt": "2025-01-15T13:09:45Z",
    "inputContext": {
        "taskName": "call_routing",
        "inputVariables": {
            "accountNumber": "3434",
            "name": "John Doe"
        }
    },
    "type": "SIP",
    "outputContext": {
        "transferType": "SYSTEM",
        "currentTaskName": "AccountInquiry",
        "referenceVariables": {
            "account_balance": "1250.00",
            "last_payment_date": "2025-01-10"
        },
        "transferVariables": {
            "next_action": "schedule_callback",
            "priority": "high"
        }
    },
    "sip": {
        "returnURI": "sip:user@customer-sbc.example.com;User-to-User=UUI-12345"
    }
}
Extract the key information:
  • Status: Indicates if the call was completed successfully.
    StatusDescription
    ACTIVEThe call transfer is active and the destination SIP URI is waiting to be connected.
    ONGOINGThe call was connected and GenerativeAgent is talking to the customer.
    COMPLETEDThe call transfer has completed.
    EXPIREDThe call transfer has expired and the destination SIP URI is no longer valid for that conversation.
  • outputContext: Contains the conversation results and any transfer variables
    • transferType: Indicates the type of transfer that occurred. This can be either AGENT or SYSTEM.
    • referenceVariables: Context information about the customer and conversation
    • transferVariables: Data that should be passed to the next system or agent
With this information, handle the call according to your own business logic, such as routing the call to an agent or handling call disposition.

​
Handling customer reconnections

There may be scenarios where you want to reconnect a customer directly to where they left off with GenerativeAgent. For example, if the customer hangs up the phone, or after transferring back to your system, you want to transfer them back again to GenerativeAgent. To do this, ensure you use the same externalConversationId to reconnect the customer to the same conversation. GenerativeAgent will resume the conversation where it left off. 
curl --location 'https://api.sandbox.asapp.com/generativeagent/v1/call-transfers' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "id":"[Your New Transfer Id for this transfer attempt]",
    "externalConversationId":"[Your Original Conversation Id from the first conversation leg]",
    "type": "SIP",
    "sip": {
        "returnURI": "sip:user@customer-sbc.example.com;User-to-User=UUI-12345",
        "returnTransferType": "REFER"
    }
}'

​
Dynamic Transfer Configuration

By default, your transfer type is configured as part of your static setup with ASAPP. However, you can optionally override the transfer type for specific calls by including the sip.returnTransferType parameter in your call transfer request.

​
Override Transfer Type

To use a different transfer type for a specific call, include the sip.returnTransferType parameter:
ParameterDescription
sip.returnTransferTypeOverride the default transfer type for this specific call (BYE, REFER, or INVITE).
sip.returnInviteAuthentication.usernameUsername for authentication (optional for INVITE transfers).
sip.returnInviteAuthentication.passwordPassword for authentication (optional for INVITE transfers).
curl --location 'https://api.sandbox.asapp.com/generativeagent/v1/call-transfers' \
--header 'asapp-api-id: <API KEY ID>' \
--header 'asapp-api-secret: <API TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "id":"[Your Transfer Id]",
    "externalConversationId":"[Your Conversation Id]",
    "type": "SIP",
    "sip": {
        "returnURI": "sip:user@customer-sbc.example.com;User-to-User=UUI-12345",
        "returnTransferType": "INVITE",
        "returnInviteAuthentication": {
            "username": "your_username",
            "password": "your_password"
        }
    },
    "inputContext": {
        "taskName":"call_routing",
        "inputVariables":{
            "accountNumber":"3434",
            "name": "John Doe"
        }
    }
}'
When using dynamic transfer configuration:
  • The sip.returnURI is required for REFER and INVITE transfer types, but not for BYE transfers
  • For INVITE transfers, you may provide sip.returnInviteAuthentication.username and sip.returnInviteAuthentication.password for authentication

​
Next Steps

Now that you have successfully implemented API-based SIP Transfers with GenerativeAgent, here are some important next steps to consider:

Configuration Overview

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

Connect your APIs

Configure your APIs to allow GenerativeAgent to access necessary data and perform actions

Review Knowledge Base

Connect and optimize your knowledge base to improve GenerativeAgent’s responses

Go Live

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