Integrate your voice bot with your contact center technology
Integrating Ada with your contact center technology is as simple as transferring a phone call:
- You can transfer a call from your contact center platform to Ada
- You can transfer a call from Ada to your contact center platform when human support is required
There are two different types of call transfers. Your bot can receive or transfer phone calls using either option:
- Public Switched Telephone Network (PSTN) transfers made over the phone network
- Session Initiation Protocol (SIP) transfers made over the public internet
The one you'll choose depends on the capabilities of your contact center platform.
Understand the types of call transfers
Public Switched Telephone Network (PSTN) transfers
PSTN transfers are made using the phone network. To transfer a phone call, you just need to provide the phone number you want to transfer to, and don't need to configure anything else.
| Benefits | Drawbacks |
|---|---|
Easy to configure - to make a call or transfer, you just need to dial a phone number Supported by all contact center platforms | More expensive Not possible to include metadata with calls |
Session Initiation Protocol (SIP) transfers
If your contact center platform supports SIP transfers, you can take advantage of the cost savings and additional features that are possible when transferring calls over the internet.
| Benefits | Drawbacks |
|---|---|
More cost efficient Can sometimes include metadata with call transfers, depending on what your contact center platform supports | Not supported by all contact center platforms Configuration can be more complicated in contact center platforms |
Integrate your bot with your contact center platform
This section takes you through how to integrate your contact center platform with Ada Voice. If you don’t see your contact center platform listed here, you can contact your Ada team to determine the best way to integrate. Ada Voice can integrate with any contact center platform.
Integrate Voice with Twilio Flex
This section takes you through how to transfer calls between Ada and Twilio Flex.
Get calls into Ada
- If you want your bot to answer all calls that are made to a phone number, the best option is to configure your bot to use that phone number. For more information, see Set up your Twilio account
- If you don't want your bot to answer all calls that are made to a phone number, then you can choose to just forward certain calls from Twilio Flex to Ada using Twilio Studio and a SIP transfer:
- Request the following from Ada:
- Ada Voice SIP Proxy address
- Voice SIP Proxy secret key
- Sender name
- In Twilio Studio, in the UUI header, add a
phone_numberfield, and set the value to the end user’s phone number. - Go to Twilio > Services, and use the secret key and sender name you got from Ada to generate an authentication signature by defining a function:
const crypto = require('crypto');
// Helper function to get rounded time
function getRoundedTime() {
const now = new Date();
now.setUTCMinutes(Math.floor(now.getUTCMinutes() / 10) * 10);
now.setUTCSeconds(0, 0);
return Math.floor(now.getTime() / 1000);
}
// Function to generate authentication signature
function generateAuthenticationSignature(twilioCallId, secret) {
const roundedTime = getRoundedTime();
const message = `${twilioCallId}|${roundedTime}`;
console.log("Rounded Time: ", roundedTime);
if (!secret) {
throw new Error('VOICE_SIP_PROXY_SECRET not found.');
}
const hmac = crypto.createHmac('sha3-256', secret);
hmac.update(message);
const hmacSignature = hmac.digest('hex');
sender = "TEST_TFLEX"
return `${twilioCallId}|${hmacSignature}|${sender}`;
}
// Twilio Function
exports.handler = function (context, event, callback) {
let authSignature = ""
try {
const twilioCallId = event.CallSid;
const secret = context.VOICE_SIP_PROXY_SECRET
authSignature = generateAuthenticationSignature(twilioCallId, secret);
} catch (error) {
console.error('Error generating authentication signature:', error.message);
}
const response = new Twilio.Response();
console.log('Authentication Signature:', authSignature);
response
.setStatusCode(200)
.appendHeader('Content-Type', 'application/json')
.setBody({
everything: encodeURIComponent(authSignature),
});
return callback(null, response);
}; - Use a Run Function widget to pass the output from the above to a linked Connect Call To widget.
- In the Connect Call To widget, set the SIP endpoint.
- Request the following from Ada:
Escalate calls directly to agents using Twilio Flex
If a caller using your bot needs to escalate to a human agent, you can hand them off using a SIP transfer to Twilio Flex. You can modify Twilio Studio to process inbound calls from Ada Voice.
These transfers can contain user-to-user information (UUI) headers, which can contain information about the caller and their inquiry.
To do this, make sure you have the following:
- A SIP domain on Twilio, which is where Voice will transfer the call to, and which will forward the call to a Twilio Studio Flow
- An instance of Twilio Flex
- Set up a basic trigger in Twilio Studio
-
Go to Studio > Flows > Create new flow, and give your flow a name, e.g.,
voice-twilio-flex-flow. -
Create a simple branch off of incoming calls, and add a Say or Play block to it. Here's an example, where incoming calls get the message "Transfer from Ada complete":
Make sure you save and publish your flow.
-
Configure your SIP domain to forward incoming calls to this flow.
-
On your Ada dashboard, create a Transfer Call block to your SIP domain so you can try transferring calls to your new flow.
If the transfer is successful, you should hear the message you added; in our example, "Transfer from Ada complete."
-
- Extract UUI headers
- In the flow you created, add a function to the Say/Play block, with the following attributes:
- Widget name: Add a name
- Service:
HEX-to-ASCII - Environment:
ui - Function:
/getUUIHeaders - Function URL:
https://hex-to-ascii-3794.twil.io/getUUIHeaders - Function Parameters: set
UUI_Headersto{{trigger.call.SipHeader_User-to-User}}
- Go to Develop > Function sand Assets > Services.
- Define the service and implementation of the function. Here's an example of a function that extracts the UUI headers, and decodes them from HEX if needed:
exports.handler = function(context, event, callback) {
let twiml = new Twilio.twiml.VoiceResponse();
// Check if UUI_Headers exists and contains "encoding=hex"
if (event.UUI_Headers && event.UUI_Headers.includes("encoding=hex")) {
// Step 2: Remove everything from the first ";" onwards
let uui = event.UUI_Headers.split(';')[0];
// Step 3: Check if the hex encoded string starts with "XX" and remove it
if (uui.startsWith("XX")) {
uui = uui.substring(2);
}
// Step 4: Decode the hex string to ASCII
let asciiString = hexToAscii(uui);
console.log('Decoded UUI:', asciiString);
// You can use the decoded string as needed; here we just return it in the response for demonstration
twiml.say(`Decoded UUI Header: ${asciiString}`);
} else {
// If "encoding=hex" is not found, or UUI_Headers does not exist, return the UUI_Headers field as is
console.log('UUI_Headers:', event.UUI_Headers);
twiml.say('UUI Headers do not require decoding.');
twiml.say(`UUI Header: ${asciiString}`);
}
return callback(null, twiml);
};
// Helper function to convert hex to ASCII
function hexToAscii(hexStr) {
var hex = hexStr.toString(); //force conversion
var str = '';
for (var i = 0; i < hex.length; i += 2)
str += String.fromCharCode(parseInt(hex.substr(i, 2), 16));
return str;
} - Click Deploy All to deploy your changes, and turn on the Live logs on toggle.
- Try transferring a call again like you did earlier, but this time, include some UUI variables. You should see those extracted variables in your live logs.
- In the flow you created, add a function to the Say/Play block, with the following attributes:
Integrate Voice with Dixa
This section takes you through how to transfer calls between Ada and Dixa.
Get calls into Ada
- If you want your bot to answer all calls that are made to a phone number, the best option is to port your existing phone number to the Twilio account that you will use with Ada. For more information, see Porting a Phone Number to Twilio at Twilio's Help Center.
- If you do not want your bot to answer all calls that are made to a phone number OR if you do not want to port your phone number to Twilio, then you can forward calls to an external number from Dixa to send inbound calls to your bot. For more information, see the Forward call section in Create a Phone Flow at Dixa's documentation.
Escalate calls directly to agents using Dixa
If a caller using your bot needs to escalate to a human agent, you can hand them off using a SIP transfer to Dixa.
- Get the Ada IP address allowlist from your Ada team.
- Ask your Dixa Team to allowlist the Ada IPs, and ask them for your Dixa SIP domain.
- In your Dixa instance, go to Settings > Phone, and configure a DID number.
- On the Ada dashboard, in your handoff, use the Transfer Call block to make a SIP transfer to Dixa.
- In the Phone number or 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.
- Select the checkbox beside Include a User-to-User header when transferring to the SIP address.
- Click +Add another row.
- For Key, enter the key name
phone_number. - For Value, select the
phone_numbermetavariable.
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.