Retrieve Conversation details

You can retrieve the details of a Conversation object for a voice call using the Conversation API.

While this tutorial looks specifically at retrieving the details of a voice call, there are many other possible use cases with other capabilities, such as a video call or a text chat session. The purpose of this tutorial is to provide insight into the structure of a Conversation, as the Conversation is an important object that underlies much of the Vonage technology. It is a fundamental data structure for communication activities, as all communication takes place through a Conversation.

The setup you will have in this tutorial is illustrated in the following diagram:

In this tutorial

Prerequisites

Create a Vonage account - you won't get far without this.
Rent a Vonage Number - you should have a couple of Euros free credit. It's more than enough.
Install the Vonage Command Line tools - you will need Node installed but using Vonage CLI is quick and convenient.
You should have Python 3 and Flask installed. These are required for your webhook server.

This tutorial assumes you will be running Ngrok in order to run your webhook server locally.

If you are not familiar with Ngrok, please refer to our Ngrok tutorial before proceeding.

You will also need access to two phones for this tutorial!

So, if you are ready to continue...

Create a Vonage Application

First you will need to create a Vonage Application if you have not already done so:

vonage apps:create "Conversation App" --voice_answer_url=http://demo.ngrok.io/webhooks/answer --voice_event_url=http://demo.ngrok.io/webhooks/event

In this previous command you will need to replace demo by what applies to your setup.

Make a note of the generated Application ID (APP_ID), you will need this when you generate a JWT.

Link a Vonage Number to your Application

Assuming you have already rented a Vonage Number (VONAGE_NUMBER), you can link your Vonage Number with your application in the Dashboard or via the command line:

vonage apps:link:app APP_ID --number=VONAGE_NUMBER

Create a JWT

The Conversation API is authenticated using JWTs. You can generate a JWT with the following command:

JWT="$(vonage jwt --private_key=private.key --app_id=APP_ID)"

You need to replace APP_ID with the ID for your application. Also, private.key is the key associated with this same application.

NOTE: This JWT will be valid for one day.

You can then view the JWT with:

echo $JWT

TIP: You can verify your JWT at jwt.io.

Run your webhook server

You need to run a webhook server to help obtain the Conversation ID for the in-progress call. The following Python code will suffice:

from flask import Flask, request, jsonify
from pprint import pprint

app = Flask(__name__)

ncco = [{
        "action": "connect",
        "endpoint": [{
            "type": 'phone',
            "number": 'TO_NUMBER'
        }]
}]

@app.route("/webhooks/answer")
def answer_call():
    params = request.args
    pprint(params)
    return jsonify(ncco)

if __name__ == '__main__':
    app.run(port=3000)

IMPORTANT: You need to replace TO_NUMBER with the number of your second phone, phone 2 (Bob).

Run this webhook server locally with:

python3 app.py

Call your Vonage Number

Dial your Vonage Number with phone 1 (Alice). The inbound call is forwarded to your second phone, phone 2 (Bob). Answer the call on phone 2 (Bob). Do not cancel the call at this point.

Now check the logging produced by your webhook server. You should see something similar to:

...
{
   'conversation_uuid': 'CON-bc643220-2542-499a-892e-c982c4150c06',
   'from': '447700000001',
   'to': '447700000002',
   'uuid': '797168e24c19a3c45e74e05b10fef2b5'
}
...

You are interested only in the Conversation ID which has the form CON-<uuid>. Copy and paste that ID somewhere convenient.

Get the Conversation details

You can retrieve details of the Conversation object for the current call by running the following command in another terminal tab.

NOTE: You will need to make sure you replace $CONVERSATION_ID by the ID you obtained previously and $JWT by the JWT you created previously.

Obtain the Conversation details for the voice call with the following:

Write the code

Add the following to get-conversation.sh:

curl "https://api.nexmo.com/v0.3/conversations/$CONVERSATION_ID" \
     -H 'Authorization: Bearer '$JWT\
     -H 'Content-Type: application/json'

View full source

Run your code

Save this file to your machine and run it:

bash get-conversation.sh

Prerequisites

npm install @vonage/server-sdk

Create a file named get-conversation.js and add the following code:

const { Vonage } = require('@vonage/server-sdk');

const vonage = new Vonage({
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH,
});

View full source

Write the code

Add the following to get-conversation.js:

vonage.conversations.getConversation(CONVERSATION_ID)
  .then((conversation) => console.log(conversation))
  .catch((error) => console.error(error));

View full source

Run your code

Save this file to your machine and run it:

node get-conversation.js

Prerequisites

composer require vonage/client

Create a file named get-conversation.php and add the following code:

use Vonage\Conversation\ConversationObjects\CreateConversationRequest;

require_once __DIR__ . '../../config.php';
require_once __DIR__ . '../../vendor/autoload.php';

$keypair = new \Vonage\Client\Credentials\Keypair(
    file_get_contents(VONAGE_APPLICATION_PRIVATE_KEY_PATH),
    VONAGE_APPLICATION_ID
);

$client = new \Vonage\Client($keypair);

View full source

Write the code

Add the following to get-conversation.php:

$conversation = $client->conversation()->getConversationById(CONVERSATION_ID);

View full source

Run your code

Save this file to your machine and run it:

php get-conversation.php

This API call will give you a response similar to the following:

{
    "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"
        }
    }
}

This response is explained in more detail in the Conversation topic.

You can now hang up phone 1 (Alice) and phone 2 (Bob) to terminate the call.

Conclusion

You have seen how to use the Conversation API to obtain the Conversation object for a voice call.

Retrieve Conversation details

In this tutorial

Prerequisites

Create a Vonage Application

Link a Vonage Number to your Application

Create a JWT

Run your webhook server

Call your Vonage Number

Get the Conversation details

Write the code

Run your code

Prerequisites

Write the code

Run your code

Prerequisites

Write the code

Run your code

Conclusion

Resources