Conversation
Une Conversation est un composant central partagé sur lequel s'appuient les API de Vonage. Les conversations se déroulent sur plusieurs supports (texte, voix) et peuvent être associées à des Utilisateurs à travers Membre objets.
L'objet Conversation est essentiel pour comprendre l'API Conversation. Pour que les utilisateurs puissent communiquer, ils doivent se connecter à une conversation, à partir de laquelle un objet Membre associé est créé dans cette conversation.
Une conversation peut prendre en charge la messagerie texte ou les appels audio. Pour la messagerie textuelle, une conversation peut être considérée comme un salon de discussion. Les utilisateurs peuvent être invités à rejoindre une conversation et ils peuvent la quitter. Un même utilisateur peut également se joindre à plusieurs conversations par l'intermédiaire de plusieurs objets membres.
Au cours d'une conversation, Vonage émet divers messages d'information. Evénements. Ces événements peuvent être des événements de communication tels que des messages et des flux vocaux ou d'autres événements tels que l'ajout ou la suppression d'utilisateurs, des indicateurs de frappe, etc. L'objectif est de traiter ces événements au fur et à mesure qu'ils se produisent, bien que Vonage enregistre un journal des événements qui peut être consulté ultérieurement.
Il ne peut y avoir de communication en dehors du contexte d'une conversation.
Une conversation peut être utilisée pour une seule interaction de communication temporaire avec un début et une fin, comme un appel. Elle peut également servir de conteneur permanent pour l'historique complet de toutes les interactions connexes.
Un exemple Conversation
Product deprecation notice
Effective April 30th, 2026, the messaging functionality of the Vonage Conversation API will be discontinued. Access for new users will be closed, and messaging capabilities will no longer be available to existing users after this date.
The voice functionality of the Conversation API will remain available and is not impacted by this change. If you have any questions regarding this partial discontinuation, please contact your account manager or our support team.
Prenons l'exemple suivant. Un utilisateur appelle un numéro Vonage associé à une Application Vonage. L'application transfère l'appel vers un deuxième téléphone. Ceci est illustré dans le diagramme suivant :
Détails de la conversation
L'appel se compose de deux segments : entrant et sortant, et de deux membres, tous contenus dans un objet Conversation. Si vous avez utilisé l'appel de l'API Conversation Obtenir une conversation pour obtenir les détails de cette conversation, vous obtiendrez une réponse similaire à la suivante :
{
"id": "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/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06"
}
}
}
Dans la réponse ci-dessus, les numéros de téléphone sont les suivants :
| Numbers | Description |
|---|---|
| 447700000001 | Téléphone : appels entrants (Alice) |
| 447700000002 | Numéro Vonage lié à l'Applications Vonage |
| 447700000003 | Le téléphone de destination (Bob) |
Si vous examinez attentivement la réponse, vous constaterez ce qui suit :
- Il existe une Conversation identifiée par l'ID du formulaire
CON-<uuid>. - Cette conversation compte deux membres - un pour chaque utilisateur.
- Les deux députés sont
JOINEDdans la conversation. - Chaque membre dispose d'un canal de type
phone. - Chaque canal possède un identifiant.
- Chaque canal est associé à une jambe différente.
- Chaque jambe a un identifiant unique.
Ceci est illustré dans le diagramme suivant :
En résumé, dans cet exemple, il y a un appel et une conversation composée de deux segments (entrant et sortant). Chaque utilisateur impliqué dans l'appel est associé à la conversation en devenant membre de cette conversation.
Evénements
Si, alors que l'appel est en cours de session, vous obtenez des événements pour la conversation à l'aide de la fonction Liste des événements API, vous verrez les événements qui ont eu lieu jusqu'à présent au cours de l'appel :
[
{
"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/v0.3/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/v0.3/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/v0.3/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/v0.3/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/v0.3/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/v0.3/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/v0.3/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/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/8"
}
]
Les événements survenus au cours de cette conversation transitoire sont les suivants :
| ID de l'événement | ID du membre | Type d'événement | Description |
|---|---|---|---|
| 1 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | Alice vers Numbers Vonage |
| 2 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:ringing | Vonage à Bob |
| 3 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:answered | Bob a répondu |
| 4 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:joined | Bob s'est joint à la conversation |
| 5 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:media | Configuration audio de Bob |
| 6 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:answered | Alice répond |
| 7 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | Alice participe à la conversation |
| 8 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:media | Installation audio Alice |
NOTE : Chaque événement possède un ID d'événement.
Comme il s'agit d'une conversation transitoire (appel), une fois l'appel terminé, la conversation ne sera plus disponible, sauf indication contraire. Vous ne pouvez donc voir que les événements qui ont lieu pendant que la conversation est en cours, et non l'événement de fin. Une conversation peut être rendue persistante, par exemple, en spécifiant l'attribut conversation dans un NCCO contrôlant l'appel. Vous pourriez voir l'événement de fin si vous regardiez l'activité sur le webhook d'événement pour votre application, par exemple sur https://www.example.com:9000/webhooks/event vous verrez une série d'événements tels que les suivants :
| Horodatage | Direction (jambe) | De | Pour | Type d'événement (statut) | Notes |
|---|---|---|---|---|---|
| 2018-10-25T09:26:18.991Z | Inbound | 447700000001 | 447700000002 | started | Appelle le numéro de Vonage |
| 2018-10-25T09:26:18.991Z | Inbound | 447700000001 | 447700000002 | ringing | Sonnerie de téléphone |
| 2018-10-25T09:26:19.827Z | N/A | 447700000001 | 447700000002 | N/A | À ce stade, l'appel est pris |
| 2018-10-25T09:26:24.384Z | Sortie | Inconnu | 447700000003 | started | Vonage lance un appel |
| 2018-10-25T09:26:24.384Z | Sortie | Inconnu | 447700000003 | ringing | Bob sonne |
| 2018-10-25T09:26:30.277Z | Sortie | Inconnu | 447700000003 | answered | Bob répond |
| 2018-10-25T09:26:30.340Z | Inbound | 447700000001 | 447700000002 | answered | Alice et Bob sont connectés |
| 2018-10-25T09:31:30.179Z | Inbound | 447700000001 | 447700000002 | completed | Le trajet entrant s'achève |
| 2018-10-25T09:31:30.179Z | Sortie | Inconnu | 447700000003 | completed | L'étape sortante est terminée |
Cela montre que Bob completed l'appel, et la conversation a été supprimée par la suite.
Jusqu'à présent, cette description a porté sur un appel vocal (média) sur un téléphone (canal) avec deux segments. Cependant, les mêmes concepts de base s'appliquent à différents médias (texte, voix ou vidéo) et à différents canaux (téléphone, SIP, Websocket ou In-App Video). Les détails des différents types d'appels seraient un peu différents, par exemple les appels vidéo incluraient différents types d'événements.