Call Flow
Overview
Any voice interaction starts with a call. This guide describes how the calls are being processed in different scenarios.
Inbound calls are made to the Vonage platform by one of the following methods:
- to a Vonage number from a regular phone,
- to a SIP domain assigned to the application from PBX or any SIP capable software/hardware,
- from a client application using the Client SDK.
Outbound calls are calls made from the Vonage platform to
- a regular phone number,
- a SIP endpoint,
- client application, or
- WebSocket server.
Outbound calls are usually initiated in response to a request made via the REST API to create a new call. Outbound calls may also be made from within the call flow of an existing call (either inbound or outbound) using the connect
action within the NCCO. This scenario is generally used for forwarding calls.
There are two different types of call in terms of call flow:
- "Scripted" Call: when the flow is determined by a sequence of question-answer steps (actions);
- Live Conversation: which connects two or more participants in a conversation.
See both concepts described below, including switching seamlessly between on and another.
Scripted Call
Both inbound and outbound calls initially follow the same call flow once answered. This call flow is controlled by an NCCO. An NCCO is a script of actions to be run within the context of the call. Actions are executed in the order they appear in the script, with the next action starting when the previous action has finished executing. For more information about NCCOs, see the NCCO Reference.
When the Vonage API platform receives a call on your Vonage number, it makes an HTTP request to the answer_url
provided. For inbound calls, the answer_url
is configured in your Voice Application. For outbound calls, you provide an answer_url
in the API request that creates the call.
Inbound call
You may choose to provide your NCCO as part of the request you send to create a call instead of supplying an answer_url
. This is done by providing a ncco
attribute in the NCCO object of your request.
Outbound call with embedded NCCO
During the call, Vonage is making callback requests to the application at the event_url
, set in the application configuration or in the NCCO action, if one is provided in the NCCO. There are two types of callbacks:
- notifications, for example, a call status change;
- instructions request, for example, on an
input
ornotify
callback - for these events Vonage expects the application to provide a new NCCO for processing, which allows implementing different logical call flows.
Successfully established calls pass through the following states:
started
ringing
answered
completed
The Vonage platform sends corresponding event callbacks per each status. You can find more detail in the Webhooks Reference.
NCCO and webhooks allow scripting the call as a series of messages and questions to the user, which is applicable to voice notifications, IVR, voice assistants and other scenarios with a predefined list of possible events. With an NCCO, the application may instruct the Vonage platform to play the audio message (text-to-speech or prerecorded) and then expect user input either with DTMF or speech. When the user has made a menu selection, your application is notified and is able to direct the call appropriately by supplying new call instructions in the form of an NCCO.
...
input V->>U: NCCO action 1: talk V->>U: NCCO action N: input U->>V: input V->>A: event URL A->>A: analyse input A->>V: NCCO V->>U: NCCO action deactivate U deactivate V deactivate A
Typical IVR flow
Live Conversation
In some scenarios, for example, a private voice communication use case, you want to connect two or more participants to establish a live conversation. Each call, inbound or outbound, is automatically added to the new conversation behind the scenes. To connect it to another call with an NCCO, the application can either
Create a new outbound call with the
connect
action - it will be automatically joined to the same conversation;Move the call to an existing (or new) named conversation with the
conversation
action.
During the conversation, the call is no longer following a sequence of actions, it is now a live interaction between two or more members. To control the call during the conversation, for example, to mute/unmute a member, the application should use the REST API.
Live conversation flow
Using a sequence of connect
actions, the application may add other members to the conversation (up to 50 total conversation participants).
Since any type of voice endpoint might be used in the connect
action, the second member is not necessarily a human: it might be a voice bot talking to the user using the media passed through the WebSocket connection.
Switching between Scripted Call and Live Conversation
IVR usually has one or more options to speak to a live agent, sales, or support person. Also, in some cases a live conversation may end up with some scripted parts. For example, a customer satisfaction survey. The Voice API allows switching from one form of interaction to another so that the call flow may consist of three (or more in complex cases) parts:
Initial IVR, controlled with NCCO and webhooks; ends with
connect
orconversation
action →Live conversation with a person (or multiparty conference), controlled with REST API; ends with
PUT /calls/{id}
REST API call withtransfer
action →The survey, controlled with NCCO
input V->>U: question U->>V: answer V->>App: input callback App->>V: NCCO note left of App: conversation App->>V: POST /calls note left of App: conversation V->>A:outbound call activate A note over U,A: Conversation A->>V: hang up deactivate A V->>App: completed App->>V: PUT /calls/id note left of App: transfer: NCCO
talk
input V->>U: question U->>V: answer V->>App: input callback App->>App: save result App->>V: NCCO note left of App: talk deactivate App V->>U: message V->>U: end call deactivate V deactivate U
Switching from scripted call to live conversation and back
The scenario described above is a typical example; however, the application may have any combination of scripted and live parts depending on a certain use-case. See the Contact Center Augmentation tutorial to learn how to implement the described scenario step by step.