Conversation

A Conversation is a shared core component that Vonage APIs rely on. Conversations happen over multiple Media (text, voice, video) and can have associated Users through Member objects.

The Conversation object is key to understanding the Conversation API. In order for Users to communicate, they must connect to a Conversation, at which point an associated Member object is created in that Conversation.

A Conversation is capable of supporting text messaging, audio calls, or video calls. For text messaging a Conversation can be thought of as like a chat room. Users can be invited to join a Conversation and they can leave a Conversation. A single User can also join multiple Conversations through multiple Member objects.

Over the course of a Conversation, Vonage emits various Events. These events can be communication events such as messages, voice and video streams or other events such as added or removed users, typing indicators and so on. The intention is that these events should be handled as they occur, although a log of events is recorded by Vonage which can later be searched.

There can be no communication outside of the context of a Conversation.

A Conversation can be used for a single temporary communication interaction with a beginning and end, such as a call. Alternatively, it can be utilized as a permanent container for the complete history of all related interactions.

An example Conversation

Consider the following example. A User calls a Vonage Number associated with a Vonage Application. The application forwards the call to a second phone. This is illustrated in the following diagram:

Conversation details

The Call consists of two legs: inbound and outbound, and two Members, all contained in a Conversation object. If you used the Conversation API call Get Conversation to obtain details of this Conversation you would obtain a response similar to the following:

{
    "uuid": "CON-bc643220-2542-499a-892e-c982c4150c06",
    "name": "NAM-1b2c4274-e3f2-494e-89c4-46856ee84a8b",
    "timestamp": {
        "created": "2018-10-25T09:26:18.999Z"
    },
    "sequence_number": 8,
    "numbers": {},
    "properties": {
        "ttl": 172800,
        "video": false
    },
    "members": [
        {
            "member_id": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
            "user_id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
            "name": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
            "state": "JOINED",
            "timestamp": {
                "joined": "2018-10-25T09:26:30.334Z"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "initiator": {
                "joined": {
                    "isSystem": true
                }
            }
        },
        {
            "member_id": "MEM-25ccda92-839d-4ac6-a7b2-de310224878b",
            "user_id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
            "name": "vapi-user-f59c1ff26c0543fdb6c02fd30617a1c0",
            "state": "JOINED",
            "timestamp": {
                "invited": "2018-10-25T09:26:19.385Z",
                "joined": "2018-10-25T09:26:30.270Z"
            },
            "invited_by": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000001",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "initiator": {
                "invited": {
                    "isSystem": true
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06"
        }
    }
}

In the above response the phone numbers are as follows:

Number	Description
447700000001	Phone making inbound call (Alice)
447700000002	Vonage Number linked to the Vonage Application
447700000003	The destination phone (Bob)

If you look carefully at the response you can see the following:

There is one Conversation identified by the ID of the form CON-<uuid>.
This Conversation has two Members - one for each User.
Both Members are JOINED into the Conversation.
Each Member has a Channel which has the type phone.
Each Channel has an ID.
Each Channel has a different Leg associated with it.
Each Leg has a unique ID.

This is illustrated in the following diagram:

To summarize, in this example there is one call and one Conversation consisting of two Legs (inbound and outbound). Each User involved in the call is joined into the Conversation by becoming a Member of that Conversation.

Events

If, while the call is in session, you get Events for the Conversation using the List Events API call you would see Events that have taken place so far during the call:

[
    {
        "id": 1,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "timestamp": {
                "joined": "2018-10-25T09:26:19.204Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:19.207Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/1"
    },
    {
        "id": 2,
        "type": "sip:ringing",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:24.384Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/2"
    },
    {
        "id": 3,
        "type": "sip:answered",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "direction": "outbound"
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.277Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/3"
    },
    {
        "id": 4,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b"
            },
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "timestamp": {
                "invited": "2018-10-25T09:26:19.385Z",
                "joined": "2018-10-25T09:26:30.270Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.273Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/4"
    },
    {
        "id": 5,
        "type": "member:media",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "audio": true,
            "media": {
                "audio": true,
                "audio_settings": {
                    "enabled": true,
                    "earmuffed": false,
                    "muted": false
                }
            },
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.274Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/5"
    },
    {
        "id": 6,
        "type": "sip:answered",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "direction": "inbound"
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.340Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/6"
    },
    {
        "id": 7,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "timestamp": {
                "joined": "2018-10-25T09:26:30.334Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.337Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/7"
    },
    {
        "id": 8,
        "type": "member:media",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "audio": true,
            "media": {
                "audio": true,
                "audio_settings": {
                    "enabled": true,
                    "earmuffed": false,
                    "muted": false
                }
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.337Z",
        "href": "https://api.nexmo.com/beta/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/8"
    }
]

You can see the Events that occurred during this transient Conversation are as follows:

Event ID	Member ID	Event type	Description
1	MEM-f44c872e-cba9-444f-88ae-0bfa630865a6	`member:joined`	Alice to Vonage Number
2	MEM-25ccda92-839d-4ac6-a7b2-de310224878b	`sip:ringing`	Vonage to Bob
3	MEM-25ccda92-839d-4ac6-a7b2-de310224878b	`sip:answered`	Bob answered
4	MEM-25ccda92-839d-4ac6-a7b2-de310224878b	`member:joined`	Bob joined the Conversation
5	MEM-25ccda92-839d-4ac6-a7b2-de310224878b	`member:media`	Bob audio setup
6	MEM-f44c872e-cba9-444f-88ae-0bfa630865a6	`member:answered`	Alice answers
7	MEM-f44c872e-cba9-444f-88ae-0bfa630865a6	`member:joined`	Alice joins the Conversation
8	MEM-f44c872e-cba9-444f-88ae-0bfa630865a6	`member:media`	Alice audio set up

NOTE: Each event has an Event ID.

As this is a transient Conversation (call) once the call ends the Conversation will no longer be available unless otherwise specified, so you can only see events that take place while the Conversation is live, and not the terminating event. A Conversation could be made persistent, for example, by specifying the conversation action in an NCCO controlling the call. You could see the terminating event if you looked at the activity on the Event webhook for your application, for example on https://www.example.com:9000/webhooks/event you would see a series of events such as the following:

Timestamp	Direction (Leg)	From	To	Event Type (status)	Notes
2018-10-25T09:26:18.991Z	Inbound	447700000001	447700000002	`started`	Calls Vonage number
2018-10-25T09:26:18.991Z	Inbound	447700000001	447700000002	`ringing`	Now ringing
2018-10-25T09:26:19.827Z	N/A	447700000001	447700000002	N/A	At this point the call is answered
2018-10-25T09:26:24.384Z	Outbound	Unknown	447700000003	`started`	Vonage calls out
2018-10-25T09:26:24.384Z	Outbound	Unknown	447700000003	`ringing`	Bob is ringing
2018-10-25T09:26:30.277Z	Outbound	Unknown	447700000003	`answered`	Bob answers
2018-10-25T09:26:30.340Z	Inbound	447700000001	447700000002	`answered`	Alice and Bob connected
2018-10-25T09:31:30.179Z	Inbound	447700000001	447700000002	`completed`	Inbound leg completes
2018-10-25T09:31:30.179Z	Outbound	Unknown	447700000003	`completed`	Outbound leg completes

This shows that Bob completed the call, and the Conversation was subsequently deleted.

This description so far has dealt with a Voice (Media) call over Phone (Channel) with two Legs. However, the same basic concepts would apply for different Media (Text, Voice or Video) and different Channels (Phone, SIP, Websocket, or App). The details for different call types would be a little different, for example Video calls would include different Event types.

Improve this page