Event Flow

To understand the relationships between the different components in the system and between the Vonage APIs, consider the system flow of event dispatching.

To illustrate, consider the use case of a making a call from a phone to an app user.

This flow is summarized here:

  1. A phone call is initiated.
  2. Vonage receives the call and calls back on the answer_url webhook.
  3. An NCCO is executed.
  4. A call is created and users connected into it.
  5. Events are dispatched.

Note: in the mentioned use case the entry point is a phone call to a Vonage number. However, the diagram below and the way events are dispatched in the system, works in a similar manner for all other event type.

This is illustrated in the following diagram:

sequenceDiagram participant Client participant Application participant Conversation API participant Voice API participant Backend Note over Client, Backend: Establish Conversation Client-->>Application: 1. Calls Vonage number Application-->>Backend: 2. Establishes `answer_url `and `event_url` webhooks Backend-->>Voice API: 3. `answer_url` returns NCCO Voice API-->>Conversation API: 4. Call is created and Users added Note over Client, Backend: Handle events rect rgba(197, 207, 209, .2) Voice API-->> Backend: 5a. Voice API events trigger`event_url` Conversation API-->>Backend: 5b. RTC events trigger `event_url` Conversation API-->>Client: 5c. Events sent to your app via Client SDK end

The sequence is as follows:

  1. A call is placed to a Vonage number, which was assigned to a Vonage Application.

  2. Vonage receives the call and triggers your Vonage Application’s answer_url webhook, which your backend exposes.

  3. That answer_url determines how to handle a call, and who to connect the call to. It does that by executing an NCCO, that utilizes numerous capabilities of the Voice API.

  4. A call is created, and the requested users are connected into it. A call, as with Vonage communication events, occurs within a Conversation object.

As a result of answer_url execution, a new Conversation is created, or an existing one is fetched, and the requested users are added to it to connect to the call. Note, all of the events are passing through the Conversation API and are accessible to you through it. For that reason, Conversations are very powerful, as they hold all the communication events of all channels per user, allowing you to retain the communication context, and provide better and smarter communication experiences for your users.

  1. All the respective events are dispatched to your application. These events can be inbound to the backend or to the client app:

    a. and b. To your backend via event_url webhooks, that you could assign to your Vonage application. There are both Voice events and RTC events. Events to your Vonage application's voice event_url webhook are dispatched by Voice API. Events to your Vonage application's RTC capability event_url webhook are dispatched by Conversation API.

    c. To your client-side application, which is integrated with the Client SDK. These events can be received via callbacks that the Client SDKs trigger if a user is logged in to the SDK. They can also be received via push notifications, if they have been enabled, and the app is in the background.

Note: Only selected events are dispatched to the Client SDKs. In order to receive all events, make sure you set event_url webhooks for your Vonage Application. Setting of event webhooks is not mandatory but is highly recommended.


For further information see the following documentation:


API References