We want to emphasize a few important things about building a contact center with Vonage APIs that could improve performance and user experience.
NCCO (A Call Control Object) is used to control the flow of a Voice API call. When you use NCCO to route incoming calls to your contact center, be mindful of the response time of your Vonage Application's Answer URL endpoint, as it is critical in providing the best customer experience. If your webhook endpoint takes a long time to return an NCCO, for example, 4 seconds, your customer calling in won't be able to hear anything except for silence during those 4 seconds.
At the Answer URL endpoint, if your app server needs time to do some time-consuming queries, you may consider first returning a 'talk or stream' action to let the caller know the call is connected, then use the Modify an in-progress call API to update the call after you have done the necessaries queries, such as finding an available agent or putting a call into a queue.
The same should apply to all the Event URLs of NCCO actions that are expected to return an NCCO, such as input, connect (when the eventType is set to synchronous), and notify. These actions are synchronous, which means their next actions have to wait for them to complete. Hence, at their Event URLs, you want to respond with an NCCO (or empty response) as fast as possible to avoid keeping your customer in the dark waiting.
When setting up your Application, you will notice the Fallback URL, which is the fallback URL where Vonage APIs attempt to retrieve NCCO when your Answer or Event URL is unreachable or return certain HTTP error codes. It's good to set up some default handling (such as logging and returning a default NCCO), as calls will be dropped if no NCCO is returned.
The default timeout setting for the Answer and Event URL is 5 seconds; you can change it in the Vonage Developer Dashboard if needed.
Do you want to learn more about Voice API and NCCO? please check Voice API and NCCO.
Queue, Transfer, and Record are essential features of a contact center that help to manage customer calls efficiently. The Queue feature allows customers to wait in line until a representative becomes available, while Transfer allows agents to transfer calls to other agents. Record, on the other hand, enables call recording.
With the NCCO action conversation, Voice API, and Conversation API, you can easily implement Queue and Transfer to manage and transfer calls in waiting. We have easy-to-use ways to implement Call Recording and also have Conversation API for when you need complex features like Split Recording.
When you implement them with Vonage API, it is crucial to differentiate the uuid and conversation_uuid in event webhooks and associate them correctly in your app server with transfer and recording event, especially when calls are transferred from conversation to conversation, and you want to record everything.
When a call (also referred to as a leg or call leg in the Conversation API, see more) is created using the Voice API, that is when an incoming call arrives at the Vonage platform, or Vonage has received your request to make an outbound call, it is assigned with a unique identifier - uuid - and added to a conversation(identified with conversation_uuid). The uuid stays the same till the call is completed, but conversation_uuid changes when a transfer happens to the call while the recording is tied to a conversation.
When a transfer happens, that is, when the action "conversation" is executed or a transfer request is completed, you will receive a transfer webhook (see more):
{
"conversation_uuid_from": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"type": "transfer",
"uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid_to": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2023-04-12T07:26:42.775720Z"
}It is suggested to store both conversation_uuid_from and conversation_uuid_to if you have the recording enabled for each conversation, as you would receive a recording event for each conversation.
For example, the following NCCO:
[
{
"action": "record"
},
{
"action": "talk",
"text": "You are joining a conference that was created using Vonage's Voice API."
},
{
"action": "conversation",
"record": true,
"name": "vonage-conference-abc",
}
]There is a record action and a conversation action with the record option set to true, so you will receive one transfer event webhook and two recording event webhooks:
One recording event for the conversation from which the call was transferred away (conversation_uuid_from).
Another recording event for the conversation to which the call was just added (conversation_uuid_to).
So it is vital to associate them with the correct IDs to keep track of each recording and each transfer. You don't want to wonder later which call the recordings are about if you don't save all the conversation_uuid.
Split Recording will result in the recording being a stereo file with one channel having the audio sent from the caller and another channel being the audio heard by the caller.
To add Split Recording in your application, depending on whether it is a conversation created with NCCO action connect or NCCO action conversation, you may choose:
When using the action of connect, set the NCCO action record:
{
"action": "record",
"split": "conversation",
"channels": 3,//the number of channels to record (maximum 32)
"format": "wav",
},
{
"action": "connect", ... }When using the action of conversation, use the API recordConversation (part of Conversation API):
when the conversation starts, send a request to recordConversation with the request body:
{
"action": "start",
"split": "conversation",
"format": "wav",
"channels": 3
}
If your conversations are created with the NCCO action connect, it is strongly suggested you make sure to store every voice event webhook as Voice API won't store them, especially for recording events(which has recording url) that you need later to down recording.
Though when you create conferences with the action conversation, there is a way to retrieve missing recording events with this Conversation API v0.2 events].
Apart from regularly updating the Client SDK to the latest version, your application would benefit from implementing error-catching and logging.
For example, if the "answer" button on your contact center is unable to connect the call, it would help to throw out an error and send it to your error logging platform with as much information as possible about the user's browser, OS, call_uuid, converstion_uuid, etc. This provides more context around the problem's impact and the possible cause when debugging.
try {
app.on("member:call", (member, call) => {
// Answer the call.
$( "#answer" ).click((e) => {
call.answer().then().catch(error => {
// Send the error to your error logging platform with additional information
logError({
message: 'Failed to answer the call',
data: [
member.id,
member.conversation.id,
call.id,
],
extra: [
`Browser: ${navigator.userAgent}`,
`OS: ${navigator.platform}`
]
});
});
});
} catch (error) {
logError({
message: `Error: ${error.message}`,
extra: [
`Browser: ${navigator.userAgent}`,
`OS: ${navigator.platform}`
]
});
}
To build an efficient contact center with Vonage APIs, it's strongly suggested to monitor the response time of webhooks for NCCO (you should enable server logging to monitor the response time of HTTP requests) and ensure that Fallback URL is set up to return a fallback NCCO(set it up in Vonage Customer Dashboard). It's also important to correctly associate call uuid and conversation_uuid (learn more about concepts used in Conversation API) in event webhooks to implement features like Queue, Transfer, and Record. Finally, implementing your error-catching and logging would help you debug the application built with Vonage Client SDK.
If you have questions or feedback, join us on the Vonage Developer Slack.
){kind=small}
