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:

Conversation

In this tutorial

Prerequisites

  1. Create a Vonage account - you won't get far without this.
  2. Rent a Vonage Number - you should have a couple of Euros free credit. It's more than enough.
  3. Install the Nexmo Command Line tools - you will need Node installed but using Nexmo CLI is quick and convenient.
  4. 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:

Copy to Clipboard
nexmo app:create "Conversation App" http://demo.ngrok.io/webhooks/answer http://demo.ngrok.io/webhooks/event --keyfile private.key

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.

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:

Copy to Clipboard
nexmo link:app VONAGE_NUMBER APP_ID

Create a JWT

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

Copy to Clipboard
JWT="$(nexmo jwt:generate private.key exp=$(($(date +%s)+86400)) application_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:

Copy to Clipboard
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:

Copy to Clipboard
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:

Copy to Clipboard
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:

Copy to Clipboard
...
{
   '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:

Copy to Clipboard
curl "https://api.nexmo.com/beta/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 nexmo@beta

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

Copy to Clipboard
const Vonage = require('@vonage/server-sdk')

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET,
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH
})

View full source

Write the code

Add the following to get-conversation.js:

Copy to Clipboard
vonage.conversations.get(CONVERSATION_ID, (error, result) => {
    if(error) {
        console.error(error);
    }
    else {
        console.log(result);
    }
});

View full source

Run your code

Save this file to your machine and run it:

node get-conversation.js

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

Copy to Clipboard
{
    "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"
        }
    }
}

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.

Resources