Recuperar detalhes da conversa

É possível recuperar os detalhes de um objeto Conversation referente a uma chamada de voz usando a Conversation API.

Embora este tutorial trate especificamente da recuperação dos detalhes de uma chamada de voz, há muitos outros casos de uso possíveis com outros recursos, como uma chamada de vídeo ou uma sessão de bate-papo por texto. O objetivo deste tutorial é fornecer uma visão geral da estrutura de uma Conversação, já que a Conversação é um objeto importante que está na base de grande parte da tecnologia da Vonage. Trata-se de uma estrutura de dados fundamental para as atividades de comunicação, pois toda a comunicação ocorre por meio de uma Conversação.

A configuração que você terá neste tutorial está ilustrada no diagrama a seguir:

Neste tutorial

• Pré-requisitos
• Criar um aplicativo da Vonage
• Criar um JWT
• Execute seu servidor de webhooks
• Ligue para o seu número da Vonage
• Veja os detalhes da conversa
• Conclusão
• Recursos

Pré-requisitos

1. Crie um account na Vonage - você não vai chegar muito longe sem isso.
2. Alugue um número da Vonage - você deve ter alguns euros de crédito disponível. É mais do que o suficiente.
3. Instale as ferramentas de linha de comando do Vonage - você vai precisar de Nó A instalação já está feita, mas usar a CLI da Vonage é rápido e prático.
4. Você deveria ter Python 3 e Frasco instalados. Eles são necessários para o seu servidor de webhooks.

Este tutorial pressupõe que você estará executando Ngrok para executar seu webhook servidor localmente.

Caso você não esteja familiarizado com o Ngrok, consulte nosso Tutorial do Ngrok antes de prosseguir.

Você também precisará de dois celulares para este tutorial!

Então, se você estiver pronto para continuar...

Criar uma aplicação da Vonage

Primeiro, você precisará criar uma Application da Vonage, caso ainda não tenha feito isso:

Nesse comando anterior, você precisará substituir demo de acordo com o que se aplica à sua configuração.

Anote o ID do aplicativo gerado (APP_ID), você precisará disso ao gerar um JWT.

Vincule um número da Vonage ao seu aplicativo

Supondo que você já tenha alugado um número da Vonage (VONAGE_NUMBER), você pode vincular seu número da Vonage ao seu aplicativo no Painel de Controle ou por meio da linha de comando:

Criar um JWT

A Conversation API é autenticada por meio de JWTs. Você pode gerar um JWT com o seguinte comando:

Você precisa substituir APP_ID com o ID do seu aplicativo. Além disso, private.key é a chave associada a esse mesmo aplicativo.

Em seguida, você pode visualizar o JWT com:

Execute seu servidor de webhooks

Você precisa executar um servidor de webhooks para ajudar a obter o ID da conversa da chamada em andamento. O código Python a seguir é suficiente:

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)

Execute este servidor de webhooks localmente com:

Ligue para o seu número da Vonage

Ligue para o seu número da Vonage usando o telefone 1 (Alice). A chamada recebida é encaminhada para o seu segundo telefone, o telefone 2 (Bob). Atenda a chamada no telefone 2 (Bob). Não cancele a chamada neste momento.

Agora verifique os registros gerados pelo seu servidor de webhook. Você deverá ver algo semelhante a:

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

Você está interessado apenas no ID da conversa, que tem o formato CON-<uuid>. Copie e cole esse ID em algum lugar de fácil acesso.

Veja os detalhes da conversa

Você pode obter detalhes do objeto “Conversation” da chamada atual executando o comando a seguir em outra aba do terminal.

Obtenha os detalhes da conversa da chamada de voz da seguinte forma:

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

npm install @vonage/server-sdk

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

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

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

implementation 'com.vonage:server-sdk:9.3.1'

VonageClient client = VonageClient.builder()
        .applicationId(VONAGE_APPLICATION_ID)
        .privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
        .build();

var conversation = client.getConversationsClient().getConversation(CONV_ID);
System.out.println(conversation);

apply plugin: 'application'
mainClassName = project.hasProperty('main') ? project.getProperty('main') : ''

Install-Package Vonage

using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Vonage;
using Vonage.Conversations.GetConversation;
using Vonage.Request;

var credentials = Credentials.FromAppIdAndPrivateKeyPath(VONAGE_APPLICATION_ID, VONAGE_PRIVATE_KEY_PATH);
var client = new VonageClient(credentials);

var response = await client.ConversationsClient.GetConversationAsync(GetConversationRequest.Parse(CONV_ID));

composer require vonage/client

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);

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

Essa chamada de API fornecerá uma resposta semelhante à seguinte:

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

Essa resposta é explicada com mais detalhes no Conversa tópico.

Agora você pode desligar o telefone 1 (Alice) e o telefone 2 (Bob) para encerrar a ligação.

Conclusão

Você já viu como usar a Conversation API para obter o objeto Conversation de uma chamada de voz.

Recursos

• Documentação da Conversation API
• Referência da Conversation API