Conversación
Una conversación es un componente central compartido en el que se basan las API de Vonage. Las conversaciones se producen a través de múltiples medios (texto, voz) y pueden tener asociados Usuarios a través de Miembro objetos.
El objeto Conversation es clave para entender la Conversation API. Para que los Usuarios puedan comunicarse, deben conectarse a una Conversación, en cuyo momento se crea un objeto Miembro asociado en esa Conversación.
Una conversación puede contener mensajes de texto o llamadas de audio. En el caso de los mensajes de texto, una conversación es como una sala de chat. Los usuarios pueden ser invitados a unirse a una conversación y pueden abandonarla. Un mismo usuario también puede unirse a varias conversaciones a través de varios objetos Miembros.
En el transcurso de una conversación, Vonage emite varias Eventos. Estos eventos pueden ser eventos de comunicación como mensajes y flujos de voz u otros eventos como usuarios agregados o eliminados, indicadores de tipeo, etc. La intención es que estos eventos se manejen a medida que ocurren, aunque Vonage registra un registro de eventos que puede consultarse posteriormente.
No puede haber comunicación fuera del contexto de una Conversación.
Una Conversación puede utilizarse para una única interacción de comunicación temporal con un principio y un final, como una llamada. Alternativamente, se puede utilizar como un contenedor permanente para el historial completo de todas las interacciones relacionadas.
Un ejemplo Conversación
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.
Considera el siguiente ejemplo. Un usuario llama a un número de Vonage asociado con una aplicación de Vonage. La aplicación reenvía la llamada a un segundo teléfono. Esto se ilustra en el siguiente diagrama:
Detalles de la conversación
La Llamada consta de dos tramos: entrante y saliente, y dos Miembros, todos ellos contenidos en un objeto Conversación. Si ha utilizado la llamada de la Conversation API Obtener conversación para obtener detalles de esta Conversación obtendría una respuesta similar a la siguiente:
{
"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"
}
}
}
En la respuesta anterior, los números de teléfono son los siguientes:
| Numbers | Descripción |
|---|---|
| 447700000001 | Teléfono haciendo llamada entrante (Alice) |
| 447700000002 | Número de Vonage vinculado a la aplicación de Vonage |
| 447700000003 | El teléfono de destino (Bob) |
Si examina detenidamente la respuesta podrá ver lo siguiente:
- Hay una Conversación identificada por el ID del formulario
CON-<uuid>. - Esta Conversación tiene dos Miembros - uno para cada Usuario.
- Ambos diputados son
JOINEDen la conversación. - Cada Miembro tiene un Canal que es del tipo
phone. - Cada canal tiene un ID.
- Cada canal tiene asociada una pierna diferente.
- Cada tramo tiene un identificador único.
Esto se ilustra en el siguiente diagrama:
En resumen, en este ejemplo hay una llamada y una conversación que consta de dos tramos (entrante y saliente). Cada usuario implicado en la llamada se une a la conversación convirtiéndose en miembro de la misma.
Eventos
Si, mientras la llamada está en sesión, obtiene Eventos para la Conversación utilizando la función Lista de eventos API verá los eventos que han tenido lugar durante la llamada:
[
{
"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"
}
]
Los Eventos que ocurrieron durante esta Conversación transitoria son los siguientes:
| ID del evento | ID de miembro | Tipo de acontecimiento | Descripción |
|---|---|---|---|
| 1 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | Número de Alice a Vonage |
| 2 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:ringing | Vonage a Bob |
| 3 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | sip:answered | Bob respondió |
| 4 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:joined | Bob se unió a la Conversación |
| 5 | MEM-25ccda92-839d-4ac6-a7b2-de310224878b | member:media | Bob configuración de audio |
| 6 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:answered | Alice responde |
| 7 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:joined | Alice se une a la conversación |
| 8 | MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 | member:media | Alice audio set up |
NOTA: Cada evento tiene un ID de evento.
Como se trata de una Conversación transitoria (llamada) una vez que la llamada finaliza la Conversación ya no estará disponible a menos que se especifique lo contrario, por lo que sólo se pueden ver los eventos que tienen lugar mientras la Conversación está en vivo, y no el evento de terminación. Una Conversación puede hacerse persistente, por ejemplo, especificando el parámetro conversation en una OCNC que controla la llamada. Podría ver el evento de terminación si mirara la actividad en el webhook de eventos de su aplicación, por ejemplo en https://www.example.com:9000/webhooks/event verías una serie de eventos como los siguientes:
| Marca de tiempo | Dirección (pierna) | En | A | Tipo de evento (estado) | Notas |
|---|---|---|---|---|---|
| 2018-10-25T09:26:18.991Z | Entrada | 447700000001 | 447700000002 | started | Llamadas Número de Vonage |
| 2018-10-25T09:26:18.991Z | Entrada | 447700000001 | 447700000002 | ringing | Ahora suena |
| 2018-10-25T09:26:19.827Z | N/A | 447700000001 | 447700000002 | N/A | En este punto se responde a la llamada |
| 2018-10-25T09:26:24.384Z | Salida | Desconocido | 447700000003 | started | Vonage llama |
| 2018-10-25T09:26:24.384Z | Salida | Desconocido | 447700000003 | ringing | Bob está sonando |
| 2018-10-25T09:26:30.277Z | Salida | Desconocido | 447700000003 | answered | Bob responde |
| 2018-10-25T09:26:30.340Z | Entrada | 447700000001 | 447700000002 | answered | Alice y Bob conectados |
| 2018-10-25T09:31:30.179Z | Entrada | 447700000001 | 447700000002 | completed | Tramo de entrada completado |
| 2018-10-25T09:31:30.179Z | Salida | Desconocido | 447700000003 | completed | Tramo de salida completado |
Esto demuestra que Bob completed la llamada, y la Conversación fue borrada posteriormente.
Hasta ahora, esta descripción se ha referido a una llamada de voz (medio) por teléfono (canal) con dos tramos. Sin embargo, los mismos Conceptos básicos se aplicarían para diferentes Medios (Texto, Voz o Video) y diferentes Canales (Teléfono, SIP, Websocket, o App). Los detalles para los diferentes tipos de llamada serían un poco diferentes, por ejemplo, las llamadas de vídeo incluirían diferentes tipos de eventos.