Contact center integration

This section takes you through how to integrate Ada with your SIP infrastructure.

Setting up your Ada SIP domain

• If you are using your own Twilio account with Ada Voice, configure a Twilio SIP domain for your AI Agent to use. For more information, see Set up your Twilio account in Voice onboarding at Ada’s Help Docs.
• If your Voice subscription package includes Twilio your Ada team will set up your SIP domain for you. You will need to provide them with the following information:
  • The domain name for your SIP address: This will be used for the SIP domain that will be created for you, which will follow the format <your_domain_name>.sip.twilio.com. This needs to be a unique domain name that is not currently being used in Twilio.
  • IP Addresses for your SIP domain’s Access Control List (ACL): An ACL is a security mechanism that enhances network security by allowing only specified IP addresses to access your SIP domain. In the context of SIP communications, this means defining trusted IP addresses—such as those associated with your SIP infrastructure—to ensure that only authorized signaling and media traffic is permitted to interact with your SIP domain.

Integrating Ada in your SIP infrastructure

You must allow all of Twilio’s following IP address ranges and ports on your firewall for SIP signaling traffic. Please also note that these IP addresses are provided for firewall configuration purposes only and not all of these IP addresses will host active gateways at a given time. Customers should also avoid sending traffic directly to these IP addresses and instead use your SIP domain.

Global Media IP Gateway

The Public Connections Destination IP Ranges and Port Ranges are now identical across all locations:

Regional Signaling IP Gateways

Port

5061 (TLS)

North America Virginia Gateways

1
1    54.172.60.0/30 which translates to:
2
2    54.172.60.0
3
3    54.172.60.1
4
4    54.172.60.2
5
5    54.172.60.3
6
6 

North America Oregon Gateways

1
1    54.244.51.0/30 which translates to:
2
2    54.244.51.0
3
3    54.244.51.1
4
4    54.244.51.2
5
5    54.244.51.3
6
6

Europe Ireland Gateways

1
1    54.171.127.192/30 which translates to:
2
2    54.171.127.192
3
3    54.171.127.193
4
4    54.171.127.194
5
5    54.171.127.195
6
6

Europe Frankfurt Gateways

1
1    35.156.191.128/30 which translates to:
2
2    35.156.191.128
3
3    35.156.191.129
4
4    35.156.191.130
5
5    35.156.191.131
6
6

Asia-Pacific Tokyo Gateways

1
1    54.65.63.192/30 which translates to:
2
2    54.65.63.192
3
3    54.65.63.193
4
4    54.65.63.194
5
5    54.65.63.195

Asia-Pacific Singapore Gateways

1
1    54.169.127.128/30 which translates to:
2
2    54.169.127.128
3
3    54.169.127.129
4
4    54.169.127.130
5
5    54.169.127.131
6
6

Asia-Pacific Sydney Gateways

1
1    54.252.254.64/30 which translates to:
2
2    54.252.254.64
3
3    54.252.254.65
4
4    54.252.254.66
5
5    54.252.254.67
6
6

South America São Paulo Gateways

1
1    177.71.206.192/30 which translates to:
2
2    177.71.206.192
3
3    177.71.206.193
4
4    177.71.206.194
5
5    177.71.206.195
6
6

Send data to Ada using SIP User-to-User (UUI) header

When sending SIP to Ada, you must send the end user’s phone number in the SIP UUI header:

• The UUI header information must be sent in Ascii encoding format.
• It must also follow the format Ada Voice expects:

1
phone_number=+14035555555

You can send additional metadata to Ada Voice, such as name, language, account number — or any other information you choose — as key-value pairs using the SIP UUI header.

Any data sent will be available as a purple metavariable in Ada to help personalize the conversation.

Transferring calls from Ada to your SIP infrastructure

If an end user using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP REFER transfer to your SIP infrastructure.

1. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
2. In the SIP address field, enter the SIP address that you want to transfer the call to.
3. Select the checkbox beside Include a User-to-User header when transferring to the SIP address.
4. Click +Add another row.
5. For Key, enter the key name phone_number.
6. For Value, select the phone_number metavariable.
7. Click +Add another row.
8. Provide any additional key value pairs that you want sent via the UUI header.

This section takes you through how to transfer calls between Ada and Aircall.

Get calls into Ada

To have your AI Agent handle inbound calls originating in Aircall, configure an Aircall Smartflow that connects calls to your Ada Twilio Application:

1. If you have not done so already, configure a Twilio Application for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.
2. Set up the widget in an Aircall Smartflow to transfer the call to your Ada Twilio Application.
   • In Aircall, open the Smartflow Editor for the phone number(s) you want to route to Ada.
   • Drag and drop the Ada Voice smartflow widget into your flow where you want your AI Agent to engage with end users.
     • Your Aircall team will need to enable this widget for you.
3. Enter your Twilio Application details in Aircall.
   • In the Ada Voice Smartflow widget’s settings, paste the Twilio Application ID for your AI Agent. You can find this in Ada under Channels > Voice > Configuration after you create a Twilio Application for your AI Agent to use.
   • You will need an Application Key - you can obtain this from your Ada Team.
   • Publish your Smartflow.

When a call reaches the Ada Voice Smartflow widget in your Aircall Smartflow, it’s automatically routed to your AI Agent in Ada.

Escalate calls directly to agents using Aircall

If your AI Agent determines an end user needs human assistance, you can transfer the call back to an Aircall team.

1. In your Ada AI Agent Handoff use the Transfer Call block and select Aircall as the transfer option in the Transfer to dropdown.
2. For Destination type choose None, Number, Team, or User.
   • If you selected None as the Destination type, you do not need to provide any additional information. When this Transfer Call block runs, Ada drops from the call, the call continues in Aircall, and the Aircall Smartflow will continue from where the Ada Voice Smartflow widget was used.
   • If you selected Number as the Destination type, you will need to provide a line ID for a number in Aircall. You can find the line ID in the URL path of the Aircall number page, ex. dashboard.aircall.io/numbers/line_id/call-distribution. When this Transfer Call block runs, Ada drops from the call, the call continues in Aircall, and Aircall makes a ring to the number you specified in the Transfer Call block.
   • If you selected Team as the Destination type, you will need to provide a team ID for a team in Aircall. You can find the team ID in the URL path of the Aircall team page, ex. dashboard.aircall.io/teams/team_id. When this Transfer Call block runs, Ada drops from the call, the call continues in Aircall, and Aircall makes a ring to the team you specified in the Transfer Call block.
   • If you selected User as the Destination type, you will need to provide a user ID for a user in Aircall. You can find the user ID in the URL path of the Aircall user page, ex. dashboard.aircall.io/users/user_id/general. When this Transfer Call block runs, Ada drops from the call, the call continues in Aircall, and Aircall makes a ring to the user you specified in the Transfer Call block.

This section takes you through how to transfer calls between Ada and Amazon Connect.

Get calls into Ada

You will continue to receive phone calls using an Amazon Connect provisioned phone number, and you will transfer phone calls from Amazon Connect to your Ada AI Agent’s phone number using the Amazon Connect Transfer to phone number module.

1. If you have not done so already, configure a Twilio phone number for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.
2. Log into your Amazon Connect account.
3. Create a new flow in Amazon Connect for inbound phone calls that you want to transfer to Ada.
4. In order to track the end user across Amazon Connect and your Ada AI Agent, you will need to create an AWS Lambda function in the AWS Instance associated with your Amazon Connect account. This function will retrieve an Ada Call UUID for the call from Ada prior to the call being transferred to Ada.

   1. Navigate to the Console Home of the AWS instance that is associated with your Amazon Connect account. It should look like this:

      

   2. Navigate to Lambda. (Note: You might need to use Search to find it if it isn’t listed under your Recently visited.)

   3. Click Create Function on your Lambda homepage.

   4. Enter the following property values under your Lambda’s Basic information:

      • Function name: Ada-Get-Call-ID
      • Runtime: Python 3.12
      • Architecture: x86_64

      

   5. Click Create function.

   6. Once created, you will see an editor where you are able to create a new function. Enter the following — replace bot-handle with your AI Agent’s handle:

      1
      import json
      2
      import urllib.request
      3
      from urllib.error import HTTPError
      4
      5
      def lambda_handler(event, context):
      6
          url = f"https://bot-handle.ada.support/voice/transfers/"
      7
      8
          for attempt in range(3):
      9
              try:
      10
                  response = urllib.request.urlopen(url)
      11
                  uuid = response.read().decode('utf-8')
      12
                  return {
      13
                      'uuid': uuid,
      14
                  }
      15
              except Exception as e:
      16
                  # Retry on any other exception
      17
                  if attempt == 2:  # After 3rd attempt, raise the exception
      18
                      raise e

   7. Click the Deploy button.

5. After creating, allow your Amazon Connect instance to access the Lambda.
   1. Go to Amazon Connect on AWS dashboard
   2. Click on the instance
   3. Click “Flows” on the left sidebar
   4. Scroll down to “AWS Lambda” section
   5. Add function created above
6. Use the Invoke an AWS Lambda function block to call your newly created AWS Lambda function and to retrieve the uuid from Ada for your call. Enter the following property values:
   • Function ARN: Use the function created above
   • Timeout: 8
   • Response validation: Set to JSON
7. Use the Transfer to phone number block to transfer the call to Ada. Enter the following property values:
   • Transfer via: Select Phone number, select Set manually, and provide your AI Agent’s phone number.
   • Set timeout: Select Set manually 30.
   • Set Resume flow after disconnect section to Yes.
     • With this enabled, once the call is transferred to Ada, if Ada is unable to resolve a conversation and it needs to be escalated then Ada will disconnect from the call and the Amazon Connect flow will resume where it left off.
   • Select Send DTMF:
     • Select Set Dynamically
       • Namespace: External
       • Key: uuid

Escalate calls directly to agents using Amazon Connect

If an end user using your AI Agent needs to escalate to a human agent, Ada will disconnect from the call and your Amazon Connect flow will resume where you left off.

1. In your Ada AI Agent Handoff use the Transfer Call block and select Amazon Connect from the Transfer to drop down menu.
2. In the Amazon Connect destination queue field enter the queue ID of the queue in Amazon Connect that you want to transfer the phone call to.

3. In Amazon Connect, after the Transfer to phone number block that you set-up in Step 9 of Get calls into Ada above, you will need to invoke another AWS Lambda function. This function will retrieve transfer data for the call — you can use this to determine which queue in Amazon Connect to route the call to, along with other call metadata.

   Choose Which Lambda Version to Use

   There are two versions of the lambda function available. Select the one that best meets your requirements:

   Version 1: Ada-Get-Destination-Queue (Legacy)

   Returns: Only the destinationQueue value for basic routing.

   Use this if: You only need to route calls to specific queues and don’t require additional metadata.

   1. Navigate to the Console Home of the AWS instance that is associated with your Amazon Connect account. It should look like this:

      

   2. Navigate to Lambda. (Note: You might need to use Search to find it if it isn’t listed under your Recently visited.)

   3. Click Create Function on your Lambda homepage.

   4. Enter the following property values under your Lambda’s Basic information:

      • Function name: Ada-Get-Destination-Queue
      • Runtime: Python 3.12
      • Architecture: x86_64

      

   5. Click Create function.

   6. Once created, you will see an editor where you are able to create a new function. Enter the following — replace bot-handle with your AI Agent’s handle:

      1
      import json
      2
      import urllib.request
      3
      from urllib.error import HTTPError
      4
      5
      def lambda_handler(event, context):
      6
          uuid = event['Details']['Parameters']['uuid']
      7
          url = f"https://bot-handle.ada.support/voice/transfers/{uuid}/"
      8
      9
          for attempt in range(3):
      10
              try:
      11
                  response = urllib.request.urlopen(url)
      12
                  destinationQueue = response.read().decode('utf-8')
      13
                  return {
      14
                      'destinationQueue': destinationQueue,
      15
                  }
      16
              except HTTPError as e:
      17
                  if e.code == 404:
      18
                      # Handle 404 error: no destinationQueue available
      19
                      return {
      20
                          'destinationQueue': None,
      21
                          'error': 'Destination queue not found (404)'
      22
                      }
      23
                  # Retry on other errors except 404
      24
                  if attempt == 2:  # After 3rd attempt, raise the exception
      25
                      raise e
      26
              except Exception as e:
      27
                  # Retry on any other exception
      28
                  if attempt == 2:  # After 3rd attempt, raise the exception
      29
                      raise e

   7. Click the Deploy button.

   Version 2: Ada-Get-Transfer-Data (Recommended)

   Returns: Enhanced transfer data including:

   • destinationQueue - Queue routing information
   • twilioCallId - Twilio call identifier
   • conversationId - Ada conversation identifier
   • endUserId - End user identifier

   Use this if: You need additional call metadata for enhanced tracking, analytics, or advanced routing logic.

   1. Navigate to the Console Home of the AWS instance that is associated with your Amazon Connect account.

      

   2. Navigate to Lambda. (Note: You might need to use Search to find it if it isn’t listed under your Recently visited.)

   3. Click Create Function on your Lambda homepage.

   4. Enter the following property values under your Lambda’s Basic information:

      • Function name: Ada-Get-Transfer-Data
      • Runtime: Python 3.12
      • Architecture: x86_64

   5. Click Create function.

   6. Once created, you will see an editor where you are able to create a new function. Enter the following — replace bot-handle with your bot’s handle:

      1
      import json
      2
      import urllib.request
      3
      from urllib.error import HTTPError
      4
      5
      def lambda_handler(event, context):
      6
          uuid = event['Details']['Parameters']['uuid']
      7
          url = f"https://bot-handle.ada.support/voice/v2/transfers/{uuid}/" # Replace bot-handle with your own
      8
      9
          for attempt in range(3):
      10
              try:
      11
                  response = urllib.request.urlopen(url)
      12
                  response_data = response.read().decode('utf-8')
      13
                  transfer_data = json.loads(response_data)
      14
      15
                  return {
      16
                      'destinationQueue': transfer_data.get('destinationQueue'),
      17
                      'twilioCallId': transfer_data.get('twilio_call_id'),
      18
                      'endUserId': transfer_data.get('end_user_id'),
      19
                      'conversationId': transfer_data.get('conversation_id'),
      20
                  }
      21
              except HTTPError as e:
      22
                  if e.code == 404:
      23
                      # Handle 404 error: no transfer data available
      24
                      return {
      25
                          'destinationQueue': None,
      26
                          'twilioCallId': None,
      27
                          'endUserId': None,
      28
                          'conversationId': None,
      29
                          'error': 'Transfer data not found (404)'
      30
                      }
      31
                  # Retry on other errors except 404
      32
                  if attempt == 2:  # After 3rd attempt, raise the exception
      33
                      raise e
      34
              except Exception as e:
      35
                  # Retry on any other exception
      36
                  if attempt == 2:  # After 3rd attempt, raise the exception
      37
                      raise e

   7. Click the Deploy button.

4. After creating, allow your Amazon Connect instance to access the Lambda:

   1. Go to Amazon Connect on AWS dashboard
   2. Click on the instance
   3. Click “Flows” on the left sidebar
   4. Scroll down to “AWS Lambda” section
   5. Add function created above

5. Use the Invoke an AWS lambda function block to call your newly created AWS Lambda function and to retrieve the destinationQueue from Ada for your call. Enter the following property values:

   • Destination Key: uuid
   • Value: Set dynamically
     • Namespace: External
     • Key: uuid
   • Timeout: 3
   • Response validation: JSON

   

6. Use the destinationQueue value that is returned in this Lambda function to determine what queue to send the end user to.

This section takes you through how to integrate Ada Voice with a Cisco CUBE.

Setting up your Ada SIP domain

• If you are using your own Twilio account with Ada Voice, configure a Twilio SIP domain for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.
• If your Voice subscription package includes Twilio your Ada team will set up your SIP domain for you. You will need to provide them with the following information:
  • The domain name for your SIP address: This will be used for the SIP domain that will be created for you, which will follow the format <your_domain_name>.sip.twilio.com. This needs to be a unique domain name that is not currently being used in Twilio.
  • IP Addresses for your SIP domain’s Access Control List (ACL): An ACL is a security mechanism that enhances network security by allowing only specified IP addresses to access your SIP domain. In the context of SIP communications, this means defining trusted IP addresses—such as those associated with your SIP infrastructure—to ensure that only authorized signaling and media traffic is permitted to interact with your SIP domain.

Integrating Ada in your SIP infrastructure

You must allow all of Twilio’s following IP address ranges and ports on your firewall for SIP signaling traffic. Please also note that these IP addresses are provided for firewall configuration purposes only and not all of these IP addresses will host active gateways at a given time. Customers should also avoid sending traffic directly to these IP addresses and instead use your SIP domain.

Global Media IP Gateway

The Public Connections Destination IP Ranges and Port Ranges are now identical across all locations:

Regional Signaling IP Gateways

Port

5061 (TLS)

North America Virginia Gateways

1
1    54.172.60.0/30 which translates to:
2
2    54.172.60.0
3
3    54.172.60.1
4
4    54.172.60.2
5
5    54.172.60.3
6
6 

North America Oregon Gateways

1
1    54.244.51.0/30 which translates to:
2
2    54.244.51.0
3
3    54.244.51.1
4
4    54.244.51.2
5
5    54.244.51.3
6
6

Europe Ireland Gateways

1
1    54.171.127.192/30 which translates to:
2
2    54.171.127.192
3
3    54.171.127.193
4
4    54.171.127.194
5
5    54.171.127.195
6
6

Europe Frankfurt Gateways

1
1    35.156.191.128/30 which translates to:
2
2    35.156.191.128
3
3    35.156.191.129
4
4    35.156.191.130
5
5    35.156.191.131
6
6

Asia-Pacific Tokyo Gateways

1
1    54.65.63.192/30 which translates to:
2
2    54.65.63.192
3
3    54.65.63.193
4
4    54.65.63.194
5
5    54.65.63.195

Asia-Pacific Singapore Gateways

1
1    54.169.127.128/30 which translates to:
2
2    54.169.127.128
3
3    54.169.127.129
4
4    54.169.127.130
5
5    54.169.127.131
6
6

Asia-Pacific Sydney Gateways

1
1    54.252.254.64/30 which translates to:
2
2    54.252.254.64
3
3    54.252.254.65
4
4    54.252.254.66
5
5    54.252.254.67
6
6

South America São Paulo Gateways

1
1    177.71.206.192/30 which translates to:
2
2    177.71.206.192
3
3    177.71.206.193
4
4    177.71.206.194
5
5    177.71.206.195
6
6

Routing Calls to Ada

In order to route calls to Ada, you must make a SIP INVITE to Ada.

• The SIP INVITE TO SIP address should be <DID>@<YOUR_ADA_SIP_DOMAIN>, where:
  • <DID>: The phone number that you used to receive the call.
  • <YOUR_ADA_SIP_DOMAIN>: The Ada SIP domain for your Ada AI Agent.
• The FROM SIP address should be <ANI>@<YOUR_IP_ADDRESS> where:
  • <ANI>: The end user’s phone number.
  • <YOUR_IP_ADDRESS>: The IP addresses of your SIP infrastructure.

Transferring Calls from Ada to your Cisco CUBE

If a caller using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP REFER transfer to your SIP infrastructure.

1. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
2. In the SIP address field, enter the SIP address that you want to transfer the call to. This will generally be <DID>@<YOUR_IP_ADDRESS>, where:
   • <DID>: The line or extension that you want to transfer the call to.
   • <YOUR_ADA_SIP_DOMAIN>: The IP addresses of your SIP infrastructure.
3. Select the checkbox beside Include a User-to-User header when transferring to the SIP address.
4. Click +Add another row.
5. For Key, enter the key name phone_number.
6. For Value, select the phone_number metavariable.
7. Click +Add another row.
8. Provide any additional key value pairs that you want sent via the UUI header.

This section takes you through how to transfer calls between Ada and Dixa.

Get calls into Ada

• You will continue to receive phone calls using a Dixa provisioned phone number, and you will transfer phone calls from Dixa to your Ada AI Agent’s phone number. For more information, see the Forward call section in Create a Phone Flow at Dixa’s documentation. You will also need to configure a Twilio phone number for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.

Escalate calls directly to agents using Dixa

If an end user using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP INVITE transfer to Dixa.

1. Get the Ada IP address allowlist from your Ada team.
2. Ask your Dixa Team to allowlist the Ada IPs, and ask them for your Dixa SIP domain.
3. In your Dixa instance, go to Settings > Phone, and configure a DID number.
4. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
5. In the SIP address field, enter <DID>@<DIXA_SIP_DOMAIN>, where:
   • <DID>: The destination number in Dixa that is being reached, in E164 format with a leading +.
   • <DIXA_SIP_DOMAIN>: Dixa’s SIP domain, which you got from the Dixa team.
6. Select the checkbox beside Include a User-to-User header when transferring to the SIP address.
7. Click +Add another row.
8. For Key, enter the key name phone_number.
9. For Value, select the phone_number metavariable.

If required, you can assign different phone numbers to different departments. For example, you can configure one number for handoffs related to billing issues, and another one related to sales inquiries. To learn how to do this, see Buy a Phone Number at Dixa’s documentation.

This guide explains how to connect your Ada AI Agent to the Five9 contact center platform so that:

• Incoming calls received by Five9 can be routed to your Ada AI Agent.
• Ada can seamlessly escalate calls to live Five9 human agents when required.
• Optional metadata (language, ticket ID, queue, etc.) can flow in both directions using SIP X-headers.

Route calls from Five9 to Ada

Five9 delivers calls to Ada over a secure SIP trunk that terminates on a Twilio SIP domain.

1. Your Ada team will set up a Twilio SIP domain for your AI Agent to receive phone calls.
   1. Create a Twilio SIP Domain (e.g. acme.ada.sip.twilio.com).
   2. Enable TLS transport and SRTP media encryption.
   3. Add the Five9 signalling IPs to the domain’s Access-Control List (ACL).
   4. Provision a dedicated Twilio phone number (E.164) that will act as a pseudo number inside Five9.
      • This phone number will also be used by your AI Agent to send and receive SMS messages during phone calls and can be used for internal testing.
2. You open a Five9 Connectivity Project.
   Ask your Five9 Account Manager to build an outbound Twilio SIP trunk.
   Provide Five9 with:
   1. The Twilio SIP Domain (a.k.a. FQDN) created in step 1.
   2. The Twilio phone number to use as the pseudo number.
   3. Twilio’s signalling & media IPs (see the Twilio doc for the current list).
3. Five9 builds the trunk (3–6 weeks).
4. Inter-operability testing
   1. When Five9 signals completion, schedule a test call with Ada & Five9 to verify:
      • SIP OPTIONS are successful.
      • Calls to the pseudo number reach Ada and audio flows correctly.
5. Go live.
   1. In the Five9 IVR builder use the 3rd Party Transfer Module and dial the pseudo number. Calls are now routed to Ada via the secure trunk.

What is a pseudo number?
A pseudo number is an E.164 phone number that Five9 uses to route calls to a designated SIP trunk without ever going over the public phone network.

Escalate calls from Ada to Five9 agents

If the Ada conversation needs a human handoff, configure the Transfer Call block inside your Ada AI Agent Handoff to send a SIP INVITE directly to Five9.

1. Obtain an inbound pseudo number from the Five9 Connectivity Team.
2. In Ada, open AI Agent Profile from your navigation ▸ Handoff and select the Voice tab in your Handoff.
3. Drag the Transfer Call block into your Voice Handoff. Under Transfer to select SIP address.
4. Enter the address in the following format on a single line: <INBOUND_PSEUDO_NUMBER>@<FIVE9_IP_ADDRESS>:5061;secure=true, where:
   • <INBOUND_PSEUDO_NUMBER>: The inbound pseudo number provided by Five9 in step 1 above.
   • <FIVE9_IP_ADDRESS>: Five9 signalling IPs.
   • :5061;secure=true: Specifies the port the call is being sent to and that SRTP is being used.

Pass call metadata with SIP X-Headers (optional)

Using SIP X-headers you can exchange contextual data such as ticket IDs, language codes, or queue names.

1. Enable header support in your Five9 tenant.
   1. At the same time you request the outbound Twilio SIP trunk, ask Five9 professional services to enable X-headers on that trunk.
   2. Provide a list of headers you plan to send and/or receive.
   3. Implementation typically takes Five9 3–6 weeks.
2. Receive headers sent by Five9.
   1. Ada automatically converts each incoming X-<key>: <value> header into a metavariable your AI Agent can reference.
3. Send headers from Ada to Five9.
   1. Append query parameters to the SIP address in the Transfer Call block:
      • E.g. <INBOUND_PSEUDO_NUMBER>@<FIVE9_IP_ADDRESS>:5061;secure=true?x-ticket-id=12345&x-language=fr

Get calls into Ada

You will continue to receive phone calls using a Genesys Cloud provisioned phone number, and you will transfer phone calls from Genesys Cloud to your Ada AI Agent using a SIP INVITE made to your AI Agent’s SIP domain.

1. If you have not done so already, configure a Twilio SIP domain for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.

2. Log into your Genesys Cloud account, then go to the Admin tab.

3. Under Telephony, click Trunks.

4. On the External Trunks tab, click Create New. The Create External Trunk page opens.

5. On the Create External Trunk page, fill in the following fields:

   1. Under External Trunk Name, enter a name (e.g., Ada Voice trunk).
   2. Under Type, select BYOC Carrier and Generic BYOC Carrier.
   3. Under Protocol, select TLS.

6. In the Inbound section, fill in the following fields:

   1. Under Number Plan Site, select your main Genesys site. For more information, see About sites at the Genesys Cloud Resource Center.
   2. Under Inbound SIP Termination Identifier, enter a name (e.g., ada-voice).
   3. You can leave the Inbound SIP Termination Header field blank.

7. In the Outbound section, fill in the following fields:

   1. Under Outbound SIP Termination FQDN, enter the Twilio SIP domain that you created for your AI Agent in Step 1.
   2. Under Outbound SIP DNIS, enter admin.
   3. Under SIP Servers or Proxies, in the Hostname or IP Address field, enter your SIP domain, and in the Port field, enter 5061. Then, click the + icon to add it.

8. Under SIP Access Control, in the Add an IP or CIDR address field, enter each of the following CIDR addresses, one at a time, and click the + icon to add it.

   These are all of Twilio’s SIP IP addresses. For more information, see IP Addresses for Elastic SIP Trunking Services at Twilio Docs.

   168.86.128.0/18
   54.172.60.0/30
   54.172.60.0/23
   34.203.250.0/23
   54.244.51.0/30
   54.244.51.0/24
   54.171.127.192/30
   54.171.127.192/26
   52.215.127.0/24
   35.156.191.128/30
   35.156.191.128/25
   3.122.181.0/24
   54.65.63.192/30
   54.65.63.192/26
   3.112.80.0/24
   54.169.127.128/30
   54.169.127.128/26
   3.1.77.0/24
   54.252.254.64/30
   54.252.254.64/26
   3.104.90.0/24
   177.71.206.192/30
   177.71.206.192/26
   18.228.249.0/24

9. Click the Protocol section of the page to expand it. Then, under User to User Information (UUI), do the following:

   1. Click the UUI Passthrough toggle so it’s Enabled.
   2. Under Type, select User-to-User PD Attribute.
   3. Under Encoding Format, select Ascii.

10. Under Transfer, click the Take Back and Transfer and Release Link Transfer (RLT) toggles so they’re both Enabled.

11. Click Save External Trunk.

Connect your SIP trunk to a number plan

1. In Genesys Cloud, go to Telephony > Sites and select your main site. For more information, see About sites at the Genesys Cloud Resource Center.

2. On the Number Plans tab, click New Number Plan.

3. On the page that opens, fill in the following fields:

   1. Under Number Plan Name, enter a name.
   2. Under Match Type, select E.164 Number List.
   3. Under Numbers, enter the range of numbers that, when dialed from your system, will transfer to Ada Voice. These can be placeholders, and they can be the same number to indicate that the range only contains one phone number.
   4. Under Classification, choose a classification.

4. Click Save Number Plans.

5. On the Outbound Routes tab, click New Outbound Route.

6. On the page that opens, fill in the following fields:

   1. Under Outbound Route Name, enter a name.
   2. Under Classifications, choose one or more classifications.
   3. Under External Trunks, click Select External Trunks and select the SIP trunk you created.
   4. Under Classifications, add a classification for your Outbound Route. This must match the Classification that you used for your Number Plan.

7. Click Save Outbound Routes.

Create a call flow that transfers to Ada Voice

1. In Genesys Cloud, on the Admin tab, click Architect.

2. Select the call flow you want to transfer to Ada Voice. The Inbound Call Flow page opens.

3. On the Inbound Call Flow page, under Toolbox, click Task to expand it, then drag the Task action into your Starting Menu. This creates the task we use to transfer end users to Ada Voice. The New Task pane opens.

4. Under Toolbox, click Data to expand it, then drag the Set UUI Data action into the New Task pane, into the Drag action here box. The Set UUI Data pane opens.

5. In the Set UUI Data pane, under Outgoing UUI Data, beside the Enter value field, click the menu that has an icon of a document on it, and select String Builder.

6. Click the same menu again and click Expression. The String Builder window opens. In the String Builder window, under Expression, enter this string:

   Append("phone_number=", Replace(Call.Ani, "tel:", ""))

   This is a Genesys expression that extracts the end user’s number and adds it to the UUI header in the format Ada Voice expects (e.g., phone_number=+14035555555).

7. Click Save to save the string and close the String Builder window.

8. Under Toolbox, click Transfer to expand it, then drag the Transfer to Number action into the New Task pane, under the Set UUI Data action you just added. The Transfer to Number pane opens.

9. In the Transfer to Number pane, do the following:

   1. Under Number, enter the number you added in your number plan earlier.
   2. Under Perform release link transfer, select True.

10. Under Toolbox, click Disconnect to expand it, then drag the Disconnect action into the New Task pane, under the Transfer to Number action you just added.

11. Click Publish.

At this point, you should be able to call your Genesys Cloud IVR and be successfully transferred to Ada Voice.

Escalate calls directly to agents using Genesys Cloud

If an end user using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP REFER transfer to Genesys Cloud.

1. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
2. In the SIP address field, enter <DID>@admin.byoc.usw2.pure.cloud, where <DID> is the destination number in Genesys Cloud that is being reached, in E164 format with a leading +.
3. Select the checkbox beside Include a User-to-User header when transferring to the SIP address.
4. Click +Add another row.
5. For Key, enter the key name phone_number.
6. For Value, select the phone_number metavariable.
7. Click +Add another row.
8. Provide any additional key value pairs that you want sent to Genesys Cloud.

This section takes you through how to transfer calls between Ada and Gladly.

Get calls into Ada

• You will continue to receive phone calls using a Gladly provisioned phone number, and you will transfer phone calls from Gladly to your Ada AI Agent’s phone number.
  • For more information, see Configuration Options: Outbound calls, forwards via IVR, and transfers/conferences at Gladly’s documentation.
  • You will also need to configure a Twilio phone number for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.

Escalate calls directly to agents using Gladly

If an end user using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP INVITE transfer to Gladly.

1. Get the Ada IP address allowlist from your Ada team.
2. Work with your Gladly team to set-up SIP forwarding. For more information, see Forward calls via SIP at Gladly’s documentation.
   • You will use IP address allow list for authentication and will provide your Gladly team with the Ada IP addresses obtained in step 1 above.
   • Ada uses G.711 mediacodec.
   • You will need to provide Gladly with the list of phone numbers in Gladly that you will transfer calls from Ada to, and which will use SIP to receive the incoming call.
   • For each phone number, Gladly will set up a corresponding SIP address following the format <DID>@<GLADLY_SIP_DOMAIN>, where:
     • <DID>: The destination number in Gladly that is being reached, in E164 format with a leading +.
     • <GLADLY_SIP_DOMAIN>: A unique SIP domain created by Gladly.
3. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
4. In the SIP address field, enter your SIP address obtained from Gladly in step 2 following the format <DID>@<GLADLY_SIP_DOMAIN>;transport=tls.
5. Append X-Gladly-Caller-Id=<ANI> to your SIP address as a query parameter, where:
   • <ANI>: The end user’s phone number in E164 format with a leading +. You should use the phone_number metavariable in Ada for this.
   • ex. <DID>@<GLADLY_SIP_DOMAIN>;transport=tls?X-Gladly-Caller-Id=<ANI>
6. Optional: If you want to route an end user to a specific queue, you can also pass a queue identifier when transferring a call.
   • Append X-Gladly-Routing-Selector=<topic> to your SIP address as a query parameter, where:
     • <topic>: The specific queue that you want to send a call to. This is a free-form, alphanumeric string identifying the specific queue to send a call to.
     • ex. <DID>@<GLADLY_SIP_DOMAIN>;transport=tls?X-Gladly-Caller-Id=<ANI>&X-Gladly-Routing-Selector=<topic>

This guide explains how to connect your Ada Voice AI Agent to NICE CXone so that:

• Incoming calls received by CXone can be routed to your Ada AI Agent.
• Ada can cleanly hand off calls back to CXone agents using a back-channel signal flow.

Set-up a SIP trunk between Nice CXone and Ada

Nice CXone delivers calls to Ada over a secure SIP trunk that terminates on a Twilio SIP domain.

1. Your Ada team will set up a Twilio SIP domain for your AI Agent to receive phone calls.
   1. Create a Twilio SIP Domain (e.g. acme.ada.sip.twilio.com).
   2. Enable TLS transport and SRTP media encryption.
   3. Add the Nice CXone signalling IPs to the domain’s Access-Control List (ACL).
   4. Provision a dedicated Twilio phone number (E.164) for your Voice AI Agent.
      • This phone number will be used by your AI Agent to send and receive SMS messages during phone calls and can be used for internal testing.
2. You open a Nice CXone Connectivity Project.
   1. Ask your Nice CXone Account Manager to create a custom route in Ada’s shared Twilio SIP trunk with Nice CXone. They will need the following:
      1. The Twilio SIP Domain (a.k.a. FQDN) created in step 1.
      2. Twilio’s signalling & media IPs (see the Twilio doc for the current list).
3. Nice Cxone creates the custom route in Ada’s shared Twilio SIP trunk with Nice CXone (~6 weeks).
   1. CXone will add a route on the shared Nice CXone ↔ Ada Twilio SIP trunk:
      • They assign pseudo number or a range of pseudo numbers that points to your Ada SIP domain. When you dial these numbers from your instance of Nice CXone, they will route the call to your Ada AI Agent via your Twilio SIP domain.
      • You’ll use this pseudo number in your Studio scripts when sending calls to Ada.

What is a pseudo number?
A pseudo number is an E.164 phone number that Nice CXone uses to route calls to a designated SIP trunk without ever going over the public phone network.

4. Inter-operability testing
   1. When Nice CXone signals completion, schedule a test call with Ada & Nice CXone to verify:
      • SIP OPTIONS are successful.
      • Calls to the pseudo number reach Ada and audio flows correctly.

Route calls from CXone to Ada using SIP Backchannel

With SIP Backchannel, a Nice Studio script retains control of the parent contact while a child script places a dedicated call leg to the AI Agent. Ada will signal back to the parent when to end or escalate.

1. Create the Parent script (Inbound) in Nice CXone.
   1. Import the SIP Parent sample script — you can ask your Ada Team for the SIP Parent sample script JSON to import into Nice Studio.
   2. Assign the Parent script to your inbound POC/Skill so that it can handle the incoming call.
   3. The SIP Parent spawns the SIP Child on call arrival by using the SPAWN action.
2. Create the Child script (talks to Ada) in Nice CXone
   1. Import the SIP Child sample script — you can ask your Ada Team for the SIP Child sample script JSON to import into Nice Studio.
   2. Use SIPPUTHEADER action in the SIP Child script to set:
      • X-ContactId = {ContactId} so that the CXone contact ID is passed to Ada as a metavariable.
      • Include the caller’s number in the user to user header using the following format so that this is passed to Ada as a metavariable:
        • phone_number=+14155550123 (E.164).
      • You can add more user-to-user header key value pairs (name, language, account number, brand) as needed — including these will create metavariables in Ada.
   3. Use the PLACECALL to dial your Ada AI Agent’s pseudo number.
      • Use the pseudo phone number that Nice CXone provided you under Step 3 in :Set-up a SIP trunk between Nice CXone and Ada” above.
      • Set LinkContactId = {MasterId} and SourceLegPersistent = True so CXone correlates the legs.

Handoff from Ada back to CXone agents

If the Ada conversation needs a human handoff, configure the HTTP Request block inside your Ada AI Agent Handoff to make an API call to the CXone Admin API “Signal a Contact” endpoint to indicate the call should be escalated. Then configure the End Call block so that Ada drops from the call and the call continues in Nice CXone.

1. In Ada, open AI Agent Profile from your navigation ▸ Handoff and select the Voice tab in your Handoff.
2. Drag the HTTP Request block into your Handoff.
3. Using the HTTP Request block, call the CXone Admin API “Signal a Contact” endpoint for the active Contact ID — which was passed to Ada as a metavariable at the start of the conversation (see Step 2b under Route calls from CXone to Ada using SIP Backchannel section above).
   1. Pass a unique parameter as the value for the p1 key which indicates which skill or queue a call should be transferred to (for example, p1=QueueName).

   • Example:

     POST https://api-<region>.niceincontact.com/inContactAPI/services/v23.0/interactions/{ContactId}/signal?p1=billing

4. Drag the End Call block into your Handoff after the HTTP Request block. This will cause Ada to drop from the conversation.
   1. When Ada drops from the call, the Parent script decides what to do next by listening to ONSIGNAL, checking P1, and uses the [REQAGENT] action (https://help.nicecxone.com/content/studio/actions/reqagent/reqagent.htm) on the chosen skill.

NICE Studio actions you’ll use

• SIPPUTHEADER — add SIP headers before PLACECALL.
• PLACECALL — start a dedicated leg to Ada. (Nice inContact Help)
• SIGNAL / ONSIGNAL — coordinate completion/escalation between Child and Parent scripts.

Test the integration

1. Smoke test: Dial a CXone test entry point that hits your Parent (or simple transfer) script; verify you can hear the Ada greeting.
2. Header test: In Ada, confirm the phone_number metavariable is populated; confirm X-Contact-Id metavariable is populated
3. Back-channel test: Trigger your Ada flow to return Signal; verify ONSIGNAL runs in Child, then SIGNALs the Parent, which REQAGENTs.

Use this integration when you want to keep your existing Twilio call routing (Studio, Functions, Flex, or your own webhook) while connecting callers to the AI Agent on Ada’s Twilio account, then returning control back to your Twilio flow when Ada escalates to a human.

This is done using Twilio Application Connect (<Dial><Application>):

• Your Twilio project controls the inbound call and “dials” Ada’s Twilio Application (on Ada’s account).
• The caller speaks with Ada.
• When Ada needs to hand off, Ada uses the Transfer Call block with Transfer to = Twilio, which ends Ada’s leg and returns control back to your Twilio flow along with any key/value parameters you configured.

How the call flow works

1. A caller dials a phone number in your Twilio project.
2. Your Twilio flow returns TwiML that connects the call to Ada’s Twilio Application SID using <Dial><Application>.
3. The AI Agent handles the conversation.
4. If escalation is required, Ada runs a Transfer Call block (Transfer to = Twilio).
5. Twilio resumes your original flow at the <Dial action="..."> URL, where you route the caller to a human agent.

Before you start

You’ll need:

• A Twilio phone number in your Twilio project that receives inbound calls.
• A way to return TwiML for that number (one of: Twilio Studio + TwiML Redirect, Twilio Functions, TwiML Bin, or your own webhook).
• The Ada Twilio Application SID for your AI Agent (provided by Ada / available in your AI Agent’s Voice settings when enabled).
• A destination for escalations in your Twilio environment (Flex queue, agent phone number, SIP, etc.).

You do not need to give Ada access to your Twilio account for this integration. Your Twilio account simply connects calls to Ada’s Twilio Application.

Step 1: Create a TwiML endpoint that connects calls to Ada

Twilio Studio’s “Connect Call To” widget doesn’t directly connect to a TwiML Application SID. The most reliable pattern is:

• Use TwiML Redirect in Studio (or a direct number webhook) to call a TwiML endpoint
• That endpoint returns <Dial><Application> to connect to Ada

Create a TwiML endpoint using one of:

• Twilio Functions (recommended)
• TwiML Bin
• Your own TwiML webhook

Use this TwiML, replacing:

• APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX with the Ada Twilio Application SID
• https://YOUR_DOMAIN.example.com/twilio/after-ada with your handler URL for when Ada returns control

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Dial action="https://YOUR_DOMAIN.example.com/twilio/after-ada" method="POST">
4
    <Application>
5
      <ApplicationSid>APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</ApplicationSid>
6
      <Parameter name="applicationKey" value="YOUR_APPLICATION_KEY" />
7
      <!-- Optional: pass additional metadata into Ada -->
8
      <Parameter name="language" value="en" />
9
      <Parameter name="customer_id" value="12345" />
10
      <Parameter name="caller_phone" value="+14165551234" />
11
    </Application>
12
  </Dial>
13
</Response>

1
<Parameter name="applicationKey" value="YOUR_APPLICATION_KEY" />

What this does:

• <Dial><Application> connects the live call to Ada’s Twilio Application.
• The <Dial action="..."> URL is where Twilio will send control after Ada disconnects (for example, after escalation).
• Any <Parameter> values are passed into Ada at connect time.

Step 2: Point your inbound Twilio number at the TwiML endpoint

Choose one option below.

Option A: Twilio Studio Flow (common)

1. In Twilio Console, open Studio and create/open your inbound Flow.
2. Add a TwiML Redirect widget.
3. Set the widget URL to your TwiML endpoint from Step 1.
4. Publish the Flow.
5. In Phone Numbers, select your inbound number and set A CALL COMES IN to trigger your Studio Flow.

Option B: Direct voice webhook (no Studio)

1. In Phone Numbers, select your inbound number.
2. Set A CALL COMES IN to Webhook.
3. Enter your TwiML endpoint URL from Step 1.

Step 3: Configure escalation back to Twilio in Ada

In Ada, configure an escalation path that uses the Transfer Call block:

1. In your AI Agent handoff flow, add a Transfer Call block.
2. Set Transfer to = Twilio.
3. Enable Pass additional data to Twilio when transferring the call (optional but recommended).
4. Add any key/value rows you want returned to Twilio (examples below).

Examples of useful return parameters:

• handoff_reason = billing_issue
• handoff_intent = cancel_subscription
• customer_id = 12345
• summary = Caller wants to change plan and asked about proration

When this block runs:

• Ada disconnects from the call, and
• Twilio resumes execution at your <Dial action="..."> URL (from Step 1), including any returned parameters.

The action URL in your <Dial> is required if you want Twilio to reliably resume your flow after Ada returns control.

Step 4: Route the caller to an agent after Ada returns control

Your <Dial action="..."> URL should respond with TwiML that routes the caller to the right agent destination.

Below is a minimal example that routes to a phone number:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Say>One moment while I connect you to an agent.</Say>
4
  <Dial>+14165559876</Dial>
5
</Response>

Common routing patterns:

• Route to Flex (enqueue/queue workflow)
• Route to a PSTN agent number
• Route to a SIP endpoint
• Use returned parameters (e.g., handoff_reason) to decide which queue/agent group to send to

Step 5: Test end-to-end

1. Call your Twilio inbound number.
2. Confirm the call connects to Ada (you hear your AI Agent greeting).
3. Trigger an escalation path in Ada (where the Transfer Call block runs).
4. Confirm:
   • Ada disconnects cleanly
   • Twilio resumes at your <Dial action="..."> handler
   • The caller is routed to your agent destination
5. If you enabled “Pass additional data…”, confirm your handler receives the returned parameters and can route accordingly.

Troubleshooting

The call never reaches Ada

• Confirm your inbound number is pointing to the correct Studio Flow or webhook.
• Confirm the TwiML endpoint from Step 1 returns valid TwiML (not HTML, not JSON).
• Confirm the Ada Application SID is correct (AP...).

The call connects but drops immediately

• Confirm your TwiML endpoint is reachable over HTTPS.
• Confirm your <Dial> is well-formed and includes a valid <ApplicationSid>.
• Confirm your Twilio project has sufficient permissions/limits for dialing to an Application Connect destination.

Escalation doesn’t return to my Twilio flow

• Ensure your <Dial> includes an action="..." URL.
• Confirm the action URL responds quickly and returns valid TwiML.
• Confirm your Ada escalation path actually reaches the Transfer Call block (and isn’t ending the call earlier).

I don’t see the parameters from Ada

• In Ada, confirm Pass additional data to Twilio… is enabled and key/value rows are configured.
• Confirm your <Dial action="..."> handler is reading request parameters sent by Twilio.
• Confirm you are not redirecting the call flow before using the data.

Notes and limitations

• This integration keeps your Twilio account in control of inbound routing and post-Ada escalation routing.
• Treat the Ada portion and agent portion as distinct legs:
  • Ada handles the AI portion
  • Your Twilio flow handles the agent transfer and queueing logic
• For advanced behavior (queue selection, localization, CRM lookups), implement that logic in your Twilio Functions/webhook using:
  • parameters passed into Ada at connect time (<Parameter>)
  • parameters returned from Ada at escalation time (Transfer Call block key/value pairs)

This section takes you through how to transfer calls between Ada and Zendesk Talk. For more information about how to integrate an AI Agent to Zendesk Talk, you can also reference the Connecting an external AI agent using a SIP-IN line article at Zendesk’s documentation.

Get calls into Ada

• You will continue to receive phone calls using a Zendesk Talk provisioned phone number, and you will transfer phone calls from Zendesk Talk to your Ada AI Agent’s phone number.
  • For more information, see the How can I forward calls to an external number from Zendesk Talk? article or the Routing incoming calls with IVR article at Zendesk’s documentation.
  • You will also need to configure a Twilio phone number for your AI Agent to use. For more information, see Set up your Twilio account in Get started with Voice at Ada’s Help Docs.

Escalate calls directly to agents using Zendesk Talk

If an end user using your AI Agent needs to escalate to a human agent, you can hand them off using a SIP INVITE transfer to Zendesk Talk.

1. Add a SIP-IN line in Zendesk Talk. For more information about how to do this, see the Adding a Talk SIP-IN line at Zendesk’s documentation.
   • When you are creating your SIP-IN line in Zendesk, you will need to provide Ada’s source IP addresses for INVITE requests (”CIDR network addresses”). Please reach out to your Ada team to obtain these.
   • You can create multiple SIP-IN lines for different skills or departments, and can route end users to the most appropriate department depending on the context of the conversation.
2. In your Ada AI Agent Handoff use the Transfer Call block and select SIP address from the Transfer to drop down menu.
3. In the SIP address field, enter <USERNAME>@<YOUR-UNIQUE-NAME-zendesk.sip.twilio.com>, where:
   • <USERNAME>: A friendly username of your choice. We recommend using a unique username for Ada.
   • <YOUR-UNIQUE-NAME-zendesk.sip.twilio.com>: The URI for your SIP-IN line.
4. Optional: Pass a Zendesk Support ticket ID when making the transfer.
   • Before transferring the call to the Zendesk SIP-IN line, your Ada AI Agent can create a Zendesk Support ticket to log information about the conversation. Human agents will be shown the linked call tickets containing end user and SIP details when handling SIP-IN calls.
   • When creating the ticket, use the via_id 34 (details here). This will help identify it as a voice incoming call ticket in Zendesk.
   • Append the following to your SIP address as a query parameter: X-Zendesk-Ticket-Id=<TICKET_NUMBER> where:
     • <TICKET_NUMBER> - Is the number of the ticket you created.
   • ex. <USERNAME>@<YOUR-UNIQUE-NAME-zendesk.sip.twilio.com>?X-Zendesk-Ticket-Id=<TICKET_NUMBER>