NAV Navbar
cURL PHP Python

API Voice v1.0

Bienvenido a la documentación de API Voice v1.0 de Netelip.

API Voice facilita a tus aplicaciones WEB el control en vivo de tus llamadas de teléfono, tanto entrantes como salientes, permitiéndote realizar acciones sobre estas en función de lo que el llamante o llamado diga o marque en el teclado de su teléfono. Podrás montar fácilmente servicios telefónicos de reservas, gestión de cobros, control de acceso a IVRs, encuestas telefónicas, etc

Tenemos ejemplos en lenguajes de shell, php y python que pueden ver en el área oscura de la derecha. Puede cambiar el lenguaje de programación de los ejemplos en las pestañas que aparecen arriba a la derecha.

Para conocer todas las APIs disponibles, información general y restricciones aplicadas a su uso consulte "Documentación APIs".

¿Qué necesito para utilizar API Voice?

Solo necesitarás tener una cuenta de cliente de netelip con el servicio API Voice activo, y un servidor WEB en el que correrán las aplicaciones que establecerán las comunicaciones con API Voice de netelip.

Si todavía no es cliente de netelip puede registrarse en el siguiente enlace.

¿Cómo funciona API Voice?

API Voice v1.0 de Netelip tiene un conjunto de comandos que se utilizan para indicar a Netelip qué hacer cuando se realiza o se recibe una llamada a través de API Voice.

Cuando alguien hace una llamada a uno de tus números de teléfono de API Voice, buscaremos la "URL de control para llamadas entrantes" asociada a ese número de teléfono, y se hará una petición a dicha URL, facilitando información de la llamada entrante y esperando recibir instrucciones sobre qué hacer con la llamada.

Algunas de las instrucciones disponibles son:

También se podrán realizar otras acciones si dispones del servicio vPBX, como:

Así mismo, tus aplicaciones podrán lanzar llamadas a números de teléfono de la red telefónica pública, a través de envío de un POST con autentificación por Token + IP (si lo especifica). Una vez contestada la llamada, esta pasará a ser gestionada por la “URL de control para llamadas salientes” de su servidor WEB.

Puede consultar la lista completa de comandos en el apartado "Comandos disponibles".

Funcionalidades

Las aplicaciones de API Voice v1.0 de Netelip son muchas pero las funcionalidades principales son:

El control de las llamadas se realizará a través de las "URLs de control de llamadas" ubicadas en su servidor WEB.

Estas URLs realizarán las comprobaciones o tareas programadas a su interés, y enviarán a API Voice los comandos a ejecutar para la llamada en curso.

Cuando API Voice finalice la ejecución de un comando, conectará con su URL de control para indicar el resultado del comando previo, y mantendrá la llamada activa a la espera de recibir el siguiente comando a ejecutar.

Este comportamiento se repetirá indefinidamente hasta que alguno de los extremos cuelgue la llamada en curso, ya sea tu URL de control mediante el comando de colgado, o el llamante o llamado mediante la tecla de colgado de tu terminal telefónico.

Para ver como se implementa un servicio para controlar las "URLS de control de llamadas" consulte el apartado "Controlador de llamadas".

Puede consultar la lista completa de comandos en el apartado "Comandos disponibles" y ver un caso práctico en el apartado "Caso práctico: flujo".

API Voice de netelip ofrece la opción de enviar el estado de las llamadas realizadas a una "URL de reporte de llamadas".

Debe configurar su "URL de reporte de llamadas" en su panel de control de API Voice, inserta la dirección web donde recibir el registro de llamadas realizadas/recibidas.

Para ver como se implementa un servicio para gestionar la información de llamadas consulte el apartado "Informe de llamadas".

El control de notificaciones de eventos de llamadas se realizará a través de la "URL enventos de llamadas" ubicada en su servidor WEB.

Esta URL realizará las comprobaciones y gestión de los eventos según su interés.

Para ver como se implementa un servicio para gestionar las notificacieones consulte el apartado "Notificaciones de estados".

Activar vPBX para API Voice

Para controlar las llamadas que realizan las extensiones de tu vPBX a través de API Voice, tiene que acceder al panel de control de netelip, sección "vPBX", editar una extensión e indicarle que la extensión va a utilizar el Plan de marcado API Voice y seleccionar uno de nuestros API Voice disponibles.

Seguridad

En este apartado se describen los mecanísmos de seguridad y algunas recomendaciones.

Autentificación

Todos los ejemplos de la documentación se basan en este esqueleto:

# Asegurese de pasar siempre las cabeceras correctamente.
curl -X POST https//api.netelip.com/v1/voice/{endpoint} \
  --data "token=69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz"
<?php
$url="https://api.netelip.com/v1/voice/{endpoint}";
$post = array(
   "token" => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
);

$request = curl_init($url);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_TIMEOUT, 180);
curl_setopt($request, CURLOPT_POSTFIELDS, $post);
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($request);
if ($response !== false) {
   // Manejar datos devueltos por la petición
} else {
   // Manejar error de conexión
}

curl_close($request);
?>
#!/usr/bin/env python

import requests

url = 'https://api.netelip.com/v1/voice/{endpoint}'
data = {
    'token': '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
}

response = requests.post(url=url, data=data)

if response:
    # Manejar datos devueltos por la petición
else:
    # Manejar error de conexión

Reemplazar {endpoint} por el punto de entrada correcto.
El token usado es un token de ejemplo no válido.

API Voice de Netelip usa autentificación por token, para obtener su token acceda a 'Token de seguridad' que encontrará en su 'Panel de control' en sección datos personales.

Si todavía no es cliente de netelip puede registrarse en el siguiente enlace.

API Voice de Netelip espera en todas sus peticiones que se autentifique con un token similar a este:

69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz

Redes de confianza.

Para usar el servicio de API Voice v1.0 de Netelip es necesario que desarrolle servicios (controladores) en sus propios servidores y esto supone tener abierto los servicios al público.

Se recomienda filtrar los accesos mediante IPs de confianza.
Las redes de confianza de Netelip son:

Datacenter Network
Europa 185.8.244.0/24
América 192.99.91.144/29

HTTPS

La comunitcación entre API Voice v1.0 de Netelip y sus servidores se realiza mediante los protocolos HTTP y HTTPS.

Netelip recomienda siempre el uso de HTTPS para garantizar que la comunicación entre sus servidores y API Voice viaje en un canal cifrado.

Netelip no aplica restricciones en cuanto al uso de certificados autofirmados.

Controlador de llamadas

Ejemplo de controlador de llamadas que pide un código de usuario para poder acceder al menú

# Se puede capturar una petición HTTP con lenguajes scripts como bash, perl, etc.
#
# Pero se recomienda usar lenguajes como php o python para realizar esta tarea
# ya que están orientados a servicios web y puede encontrar más documentación. 
#
# Elija el lenguaje php o python en las pestañas superiores para ver el ejemplo
# de un controlador.
#
# Si aún así lo necesita debe configurar correctamente su servidor web para ejecutar
# scripts (CGI).
<?php
// Obtenemos los datos de la llamada y las guardamos en variables
$src = $_POST["src"];
$dst = $_POST["dst"];
$id = $_POST["ID"];

if ($src == "" || $dst == "" || $id != "") die(); // Algo está mal, terminamos

$dtmf = $_POST["dtmf"];

// Datos del ultimo comando ejecutado si no estamos al comienzo de una llamada
$command = $_POST["command"];
$options = $_POST["options"];
$userfield = ($_POST["userfield"] == "") ? "1" : $_POST["userfield"];

$messages = array(
    1 => "Bienvenido a mi empresa, por favor escriba a continuacion su usuario.",
    2 => "Su usuario es correcto, accedemos al menu del servicio.",
    3 => "Su usuario es incorrecto, para acceder a este servicio debes de ser usuario.",
    4 => "Pulse uno para hablar con atencion al cliente, pulse dos, para hablar con soporte.",
);

switch($userfield) {

   case "0": // colgamos la llamada
      $command = "hangup";
      $options = "";
      $userfield = "";
      break;

   case "1": // reproducimos una locucion esperando una respuesta
      $command = "speak_getdtmf";
      $options  = "google;es;".$messages[1].";5000;4;1.2";
      $userfield = "2";
      break;

   case "2":
      $command = "speak_getdtmf";
      switch($dtmf) {

         case "timeout": // tiempo agotado, locucion y repetimos
            $options = "netelip;Pedro;".$messages[1].";5000;4";
            $userfield = "2";
            break;

         case("1111"): // usuario correcto, locucion y a la cola
            $options = "netelip;Pedro;".$messages[2].$messages[4].";5000;1";
            $userfield = "3";
            break;

         default: // usuario incorrecto, locución de despedida y colgamos
            $command = "speak";
            $options = "netelip;Pedro;".$messages[3];
            $userfield = "0";
         }
      }
      break;

   case "3":
      $command = "queue";
      $userfield = "0";
      switch($dtmf) {

         case "timeout": // tiempo agotado, locucion y repetimos
            $command = "speak_getdtmf";
            $options = "netelip;Pedro;".$messages[4].";5000;1";
            $userfield = "3";
            break;

         case "1": // ejecutamos la cola de atencion de la vPBX con prioridad 2
            $options = "colaatencion;2";
            break;

         case "2": // ejecutamos la cola de soporte de la vPBX con prioridad 1
            $options = "colasoporte;1";
            break;
      }
      break;
}

$cadena = array("command"=>$comand, "options"=>$options, "userfield"=>$userfield);
echo(json_encode($cadena));
?>
#!/usr/bin/env python

messages = [
    'Bienvenido a mi empresa, por favor escriba a continuacion su usuario.',
    'Su usuario es correcto, accedemos al menu del servicio.',
    'Su usuario es incorrecto, para acceder a este servicio debes de ser usuario.',
    'Pulse uno para hablar con atencion al cliente, pulse dos, para hablar con soporte.',
]

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/controller', methods=['GET','POST'])
def controller():

    if request.method == 'POST':
        # Obtenemos los datos de la llamada y las guardamos en variables
        src = request.form.get('src')
        dst = request.form.get('dst')
        idc = request.form.get('ID')

        if src == None or dst == None or idc == None: 
            return jsonify(error='No se han definido argumentos')
        if src == "" or dst == "" or idc == "": 
            return jsonify(error='Los argumentos no pueden ir vacios')

        dtmf = request.form.get("dtmf")

        # Datos del ultimo comando ejecutado
        c = {
            'command'  : request.form.get("command"),
            'options'  : request.form.get("options"),
            'userfield': request.form.get("userfield")
        }

        if c['userfield'] == "0": # colgamos la llamada
            c['command'] = "hangup"
            c['options'] = ""
            c['userfield'] = ""

        elif c['userfield'] == "1" or c['userfield'] == "" or c['userfield'] == None: 
            # reproducimos una locucion esperando una respuesta (llamada entrante)
            c['command'] = "speak_getdtmf"
            c['options'] = "google;es;%s;5000;4;1.2" % messages[0]
            c['userfield'] = "2"

        elif c['userfield'] == "2":
            c['command'] = "speak_getdtmf"

            if dtmf == "timeout": # tiempo agotado, locucion y repetimos
                c['options'] = "netelip;Pedro;%s;5000;1" % messages[0]
                c['userfield'] = "2"

            elif dtmf == "1111": # usuario correcto, locucion y a la cola
                c['options'] = "netelip;Pedro;%s%s;5000;1" % (messages[1], messages[3])
                c['userfield'] = "3"

            else: # usuario incorrecto, locución de despedida y colgamos
                c['command'] = "speak"
                c['options'] = "netelip;Pedro;%s" % messages[2]
                c['userfield'] = "0"

        elif c['userfield'] == "3":
            c['command'] = "queue"
            c['userfield'] = "0"

            if dtmf == "timeout": # tiempo agotado, locucion y repetimos
                c['command'] = "speak_getdtmf"
                c['options'] = "netelip;Pedro;%s;5000;1" % messages[3]
                c['userfield'] = "3"

            elif dtmf == "1": # ejecutamos la cola de atencion de la vPBX con prioridad 2
                c['options'] = "colaatencion;2"

            elif dtmf == "2": # ejecutamos la cola de soporte de la vPBX con prioridad 1
                c['options'] = "colasoporte;1"

        print(jsonify(c))
        return jsonify(c)
    else:
        return jsonify(error='Metodo no permitido') 

if __name__ == '__name__':
    app.run()

Para controlar las llamadas que entran en su servicio de API Voice necesita desarrollar un controlador que gestione todas las peticiones que API Voice envíe a su "URLs de control de llamadas".

El código de este controlador puede estar escrito en cualquier lenguaje de programación web ya que la comunicación entre su servidor WEB y API Voice es mediante peticiones HTTP de tipo POST con una estructura "json".

API Voice se comunicará con su servidor WEB mediante método HTTP POST o Secure HTTP POST, enviando a su URL de control los datos de la llamada y el resultado del comando ejecutado.

Una vez que API Voice realice una petición a su URL de control este quedará a la espera de que su URL de control conteste con el siguiente comando a ejecutar.

Petición

Contenido de la variable POST cuando se recibe un llamada y API Voice realiza la petición a su controlador:

{
   "ID": "1576556033.1735",
   "api": "Mi API",
   "src": "638829213",
   "dst": "34951504990",
   "startcall": "2019-11-12 11:04:26",
   "typesrc": "did",
   "usersrc": "638829213"
}

Las posibles variables que se incluirán en la petición POST cuando API Voice conecte con su URL de control serán:

Clave Descripción
ID ID único de la llamada
api Nombre del API destino de la llamada
src Número de origen de la llamada
dst Número de destino de la llamada
startcall Fecha y hora en la que comenzó la llamada
durationcall Duración actual de la llamada
durationcallanswered Duración de la llamada una vez atendida por un agente
command Comando ejecutado
options Opciones del comando ejecutado
description Descripción del resultado de la ejecución del comando
statuscode Código de estado de la ejecución
statuscall Estado de la llamada, ver valores
userfield Variable establecida por el usuario
userdata Variable opcional reservada para el usuario.
typesrc Tipo de origen, ver valores
usersrc Usuario del origen de la llamada, ver valores

statuscall

Posibles valores de statuscall:

Valor Descripción
CHANUNAVAIL El número llamado no existe
BUSY El número llamado está ocupado
NOANSWER El número llamado no contesta
ANSWER El número llamado ha contestado
CANCEL El número llamado ha colgado
CONGESTION Fallo en red telefónica por congestión
UNKNOW Fallo en red telefónica desconocido

typesrc

Posibles valores de typesrc:

Valor Descripción
ext Llamada con origen una extensión de tu vPBX cuando ésta tiene el asociado el "Plan de marcado de API Voice".
did Llamada con destino un número de teléfono de netelip gestionado por API Voice.

usersrc

Este valor depende directamente de la clave typesrc.

Si typesrc es "ext", el valor de usersrc será el usuario SIP de la extensión que realiza la llamada.

Y si typesrc es "did" el valor de usersrc será el número de teléfono de origen de la llamada, tendrá el mismo valor que src.

Respuesta

Ejemplo de una respuesta a API Voice:

{
   "command": "speak",
   "options": "netelip;Pedro;Espere por favor.",
   "userfield":"2;espera;200"
}

API Voice quedará a la espera de que su URL de control conteste con el siguiente comando a ejecutar, siempre que la variable statuscall se mantenga con valor ANSWER o sea la primera petición de recepción de llamada.

Su URL de control debe responder indicando el comando u orden que API Voice debe ejecutar (command), las opciones de configuración del comando (options) y datos personalizados que puede indicar el controlador (userfield).

Una vez procesado el comando API Voice volverá a conectar con su URL de control para indicarle el estado de la llamada y esperará a la siguiente orden.

Este proceso ser repetirá hasta que la llamada termine.

Puede consultar la lista completa de comandos y su configuración en el apartado "Comandos disponibles".

Lanzador de llamadas

Ejemplo de petición de llamada:

curl -X POST https//api.netelip.com/v1/voice \
  --data "token=69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz" \
  --data "api=Mi API" \
  --data "src=34951223344" \
  --data "dst=0034666554433" \
  --data "duration=30" \
  --data "typesrc=did"
<?php
$url="https://api.netelip.com/v1/voice";
$post = array(
   "token"     => "69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz",
   "api"       => "Mi API",
   "src"       => "34951223344",
   "dst"       => "0034666554433",
   "duration"  => "30",
   "typesrc"   => "did",
);

$request = curl_init($url);
curl_setopt($request, CURLOPT_POST, 1);
curl_setopt($request, CURLOPT_TIMEOUT, 5);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_MAXREDIRS, 3);
curl_setopt($request, CURLOPT_POSTFIELDS, $post);
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($request);
$response_code = curl_getinfo($request, CURLINFO_HTTP_CODE);
if ($response !== false) {
   if ($response_code == 200) {
      echo $response;   
   }
} else {
   echo "Error: ".$response_code);
}

curl_close($request);
?>
#!/usr/bin/env python

import requests

url = 'https://api.netelip.com/v1/voice'
data = {
    'token'    : '69cizi7zc2394b9f84e97e78b8913d0ie1z2i6b58iec943fbz478z13c00d59cz',
    'api'      : 'Mi API',
    'src'      : '34951223344',
    'dst'      : '0034666554433',
    'duration' : '30',
    'typesrc'  : 'did',
}

response = requests.post(url=url, data=data, timeout=(5, 5), max_redirects=3)

if response:
    if response.status_code == 200:
        print(response.text)
else:
    print("Error: %s" % $response.status_code)

Para realizar una llamada a través de API Voice solo es necesario enviar a la URL, 'https://api.netelip.com/v1/voice', mediante método POST, los siguientes datos:

Clave Descripción
api Nombre de la API a utilizar.
token Palabra de seguridad asociada a la API a utilizar.
src Identificador de llamada que se mostrará al usuario que recepciona la llamada.
dst Número de teléfono a llamar.
duration Duración máxima del intento de llamada en segundos. Entre 1 y 60.
userdata Variable opcional reservada para el usuario.
typedst Tipo de destino de la llamada, ver valores

typedst

Posibles valores de typedst:

Valor Descripción
pstn Llamada hacia la red pública.
extension Llamada hacia una extensión de tu vpbx.

Llamada rechazada

Respuesta de llamada rechazada:

{
    "response": "400"
}

API Voice podrá rechazar la llamada con un código 400 (unauthorized) en formato json, si el token enviado o la IP desde la que se origina la petición no es válida.

Llamada aceptada

Respuesta de llamada aceptada:

{
    "response": "200",
    "ID": "1576556033.1735"
}

Si API Voice acepta la llamada lo indicará con un código 200 (OK) y el ID único de la llamada a través de una cadena con estructura json.

El resultado del lanzamiento de la llamada se enviará a su URL de control de llamadas como se indica en el apartado "Controlador de llamadas - Petición".

La petición se realizará con la siguiente información:

Clave Descripción
ID ID único de la llamada
api Nombre del API destino de la llamada
src Número de origen de la llamada
dst Número de destino de la llamada
startcall Fecha y hora en la que comenzó la llamada
statuscall Estado de la llamada, ver valores

De este modo, tu URL de control llamadas salientes tomará el control de la llamada en curso y podrá contestar a API Voice con el siguiente comando a ejecutar como se indica en el apartado "Controlador de llamadas - Respuesta".

Puede consultar la lista completa de comandos y su configuración en el apartado "Comandos disponibles".

Destino no contesta

En caso de responder el lanzador de llamadas satisfactoriamente pero el destinatario no coger la llamada, se devolverá el estado de tal llamada a la URL de control de llamadas salientes, con la siguiente información:

Clave Descripción
ID ID único de la llamada
token Token que se utilizó en el lanzador de llamadas
api Nombre del API destino de la llamada
src Número de origen de la llamada
dst Número de destino de la llamada
duration Duración del ring de la llamada
typedst Tipo de destino de la llamada
userdata Variable establecida por el usuario
startcall Fecha de la llamada
statuscall Estado de la llamada

Para ver como API Voice trata las peticiones consultar el apartado "Controlador de llamadas - Respuesta".

Puede consultar la lista completa de comandos y su configuración en el apartado "Comandos disponibles".

Integraciones

La realización de llamadas puede ser ejecutada desde una aplicación de escritorio o web, solo es necesario que la aplicación integre el protocolo de comunicación HTTPS.

Puede consultar todos los ejemplos de esta API para ver como se realizan peticiones HTTP con curl, php y python.

Informe de llamadas

Ejemplo para almacenar en un fichero la información de las llamadas:

# Se puede capturar una petición HTTP con lenguajes scripts como bash, perl, etc.
#
# Pero se recomienda usar lenguajes como php o python para realizar esta tarea
# ya que están orientados a servicios web y puede encontrar más documentación. 
#
# Elija el lenguaje php o python en las pestañas superiores para ver el ejemplo
# de un controlador.
#
# Si aún así lo necesita debe configurar correctamente su servidor web para ejecutar
# scripts (CGI).
<?php
$file = "calls.csv";
$linecall = "";

$calls = json_decode($_POST["calls"], true);

//recorremos las llamadas
foreach($calls as $call){
   // recorremos cada uno de los valores de la llamada para montar una linea csv
   foreach($call as $value) {
      $linecall = $linecall.";".$value;
   }
   $linecall=$linecall."\n";
}

// añadimos la linea de registro de la llamada a nuestro fichero de llamadas
file_put_contents($file, $linecall, FILE_APPEND);
?>
#!/usr/bin/env python

import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/reporter', methods=['GET','POST'])
def controller():

    if request.method == 'POST':

        calls = json.loads(request.form.get('calls'))
        with open('calls.csv', 'a') as f:
            for call in calls:
                line = ','.join(call.values()) + '\n'
                f.write(line)

        return jsonify(calls=len(calls))
    else:
        return jsonify(error='Metodo no permitido')

if __name__ == '__name__':
    app.run()

Para gestionar la información de las llamadas que entran en su servicio de API Voice necesita desarrollar un controlador que gestione todas las peticiones que API Voice envíe a su "URL de reporte de llamadas".

El código de este controlador puede estar escrito en cualquier lenguaje de programación web, ya que la comunicación entre su servidor WEB y API Voice es mediante peticiones HTTP de tipo POST con una estructura "json".

API Voice se comunicará periódicamente con su servidor WEB mediante método HTTP POST o Secure HTTP POST, enviando a su "URL de reporte de llamadas" los datos de las llamadas del último periódo y el resultado del comando ejecutado.

Informe

Ejemplo de dos registros (genérico y vPBX) en el array 'calls':

[
 ...
 {
   "ID": "",
   "startdate": "2020-04-23 12:17:40.897837",
   "stopdate": "2020-04-23 12:17:45.897837",
   "src": "667001122",
   "dst": "34915221100",
   "dstname": "",
   "duration": "5", 
   "cost":0,
   "status": "answer",
   "ip": "",
   "useragent": "",
   "plan":""
 },
 ...
 {
   "ID": "",
   "startdate": "2020-04-23 12:29:01.47034",
   "stopdate": "2020-04-23 12:29:06.47034",
   "src": "34815111000 (Ext 101)","dst":"666334455",
   "dstname": "Espa\\u00f1a - m\\u00f3vil",
   "duration": "5",
   "cost": 0.0024,
   "status": "answer",
   "ip": "192.168.1.33",
   "useragent": "MyAgent\\/SPA333-1.2.3","plan":""
 }
 ...
]

El registro de llamadas se enviará a la "URL de reporte de llamadas" mediante método POST y se entregará una lista con indice "calls" en formato "json".

La estructura de los registros de la lista en "json" que API Voice entregará al conectar con su "URL de reporte de llamadas" será:

Clave Descripción
startdate Fecha de inicio de la llamada.
stopdate Fecha de finalización de la llamada.
src Origen de la llamada.
dst Destino de la llamada.
dstname Nombre del destino de la llamada.
cost Coste de la llamada.
status Estado de la llamada.
ip IP del dispositivo desde la que ha realizado la llamada
duration Duración de la llamada.
useragent Nombre del dispositivo que ha realizado la llamada.
plan Plan de llamadas utilizado en la llamada.

Notificaciones de estado

Ejemplo para gestionar las notificaciones:

# Se puede capturar una petición HTTP con lenguajes scripts como bash, perl, etc.
#
# Pero se recomienda usar lenguajes como php o python para realizar esta tarea
# ya que están orientados a servicios web y puede encontrar más documentación. 
#
# Elija el lenguaje php o python en las pestañas superiores para ver el ejemplo
# de un controlador.
#
# Si aún así lo necesita debe configurar correctamente su servidor web para ejecutar
# scripts (CGI).
<?php
$call = json_decode($_POST["call"], true);

switch ($call['status']) {
   case 'ring':
      ...
      break;
   case 'answer':
      ...
   case 'hangup':
      ...
      break;
   case 'busy':
      ...
      break;
   case 'noanswer':
      ...
      break;
   case 'notavailable':
      ...
      break;
}
?>
#!/usr/bin/env python

import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/notifications', methods=['POST'])
def controller():

    if request.method == 'POST':

        call = json.loads(request.form.get('call'))
        if call['status'] == 'ring':
            ...
        elif call['status'] == 'answer':
            ...
        elif call['status'] == 'hangup':
            ...
        elif call['status'] == 'busy':
            ...
        elif call['status'] == 'noanswer':
            ...
        elif call['status'] == 'notavailable':
            ...

        return jsonify(call=len(call))
    else:
        return jsonify(error='Metodo no permitido')

if __name__ == '__name__':
    app.run()

Las notificaciones de estado de extensiones en vPBX, permiten comunicar los cambios de estado de su extensiones, indicando cuando una llamada ha sido contestada, colgada, cancelada, etc, en sus extensiones. Estas notificaciones se realizaran a una URL de control ("URL eventos de llamada") y que usted definirá y programara en sus servidores.

El código del manejador de su "URL eventos de llamada" puede estar escrito en cualquier lenguaje de programación web, ya que la comunicación entre su servidor WEB y API Voice es mediante peticiones HTTP de tipo POST con una estructura "json".

API Voice se comunicará con su servidor WEB cada vez que se produzca un evento mediante método HTTP POST o Secure HTTP POST, enviando a su "URL eventos de llamada" los datos del evento.

Notificación

Ejemplo de contenido del índice 'call' de la variable POST cuando se envía una notificación a su URL de notificación de eventos en llamadas:

{
   "uniqueid": "1576556033.1735",
   "src": "638829213",
   "dst": "34951504990",
   "userexten": "7491464423100",
   "status": "ring",
   "date": "2020-04-21",
   "time": "10:44:10",
   "type": "inbound"
}

Los eventos de las llamadas se enviará a la url "URL eventos de llamada" mediante método POST con el índice "call" en formato "json".

La estructura de comunicación "json" será:

Clave Descripción
uniqueid ID de llamada unico
src Origen de la llamada
dst Destino de la llamada
userexten Usuario SIP de la extensión que notifica el evento
status Estado del evento. Valores: ring, answer, hangup, busy, noanswer o notavailable
date Fecha del evento, con formato YYYY-MM-DD
time Hora del evento, con formato HH:MM:SS. La hora se presentará en la zona horaria GMT
type Tipo de llamada. Valores: inbound o outbound
transferid ID de llamada transferida, aparecerá cuando se transfiere la llamada a otra extensión
transferuserexten usuario SIP de la extensión que transfiere la llamada, aparecerá cuando se transfiere la llamada a otra extensión

Comandos disponibles

Esquema de un comando:

{
    "command": "nombrecomando",
    "options": "option1[;option2;option3]",
    "userfield": "customvalue"
}

Para controlar la realización y recepción de llamadas API Voice de Netelip admite un conjunto de comandos amplio.

Cada comando está definido por 3 argumento y se entrega a API Voice en formato json.

Argumento Descripción
command Nombre de la orden o comando
options Valores separados por "," o ";" que modifican el comportamiento del comando
userfield Campo de uso libre para el usuario, se suele usar para indicar el estado o fase en el que se encuentra la llamada.

userfield es un valor definido por tu URL de control y que podrás aprovechar para indicarle en que momento de la ejecución se encuentra la llamada dentro del flujo de llamada planificado por ti.
Este campo no se procesa por API Voice y es devuelto exactamente igual en la siguiente petición.

busy

Ejemplo de busy:

{
    "command"  : "busy",
    "options"  : "10",
    "userfield": "ocupado"
}

Dar señal de ocupado en la llamada actual.

Valores que contine options

"options": "{seconds}",

Valor Descripción Tipo Defecto
seconds Duración en segundos de los tonos de ocupado antes de colgar De 0 a 30 30

callerid

Ejemplo de callerid:

{
    "command": "callerid",
    "options": "Netelip;951223344",
    "userfield": "1"
}

Cambia el identificador llamada y se suele usar antes de realizar un desvío o transferencia. Por ejemplo antes de ejecutar un comando dial.

El nombre a mostrar es un texto breve que sólo será visible en la recepción de llamadas en aplicaciones o dispositivos de VoIP.

El número de teléfono a mostrar, será visible en la recepción de llamadas en aplicaciones o dispositivos de VoIP y en llamadas a números de teléfono de la red telefónica publica.

Valores que contine options

"options": "{name};{phone}",

Valor Descripción Tipo Defecto
name Nombre a mostrar string
phone Número de teléfono a mostrar phone

conferenceroom

Ejemplo de conferenceroom:

{
    "command"  : "conferenceroom",
    "options"  : "",
    "userfield": "4"
}

Transfiere una llamada a su sala de conferencias de vPBX.

Valores que contine options

El argumento options no se usa con el comando conferenceroom, se recomienda poner una cadena vacía o un valor 0.

congestion

Ejemplo de congestion:

{
    "command"  : "congestion",
    "options"  : "10",
    "userfield": "congestionado"
}

Dar señal de congestion en la red en la llamada actual.

Valores que contine options

"options": "{seconds}",

Valor Descripción Tipo Defecto
seconds Duración en segundos de los tonos de congestion antes de colgar De 0 a 30 30

dial

Ejemplo de dial a una extensión:

{
    "command": "dial",
    "options": "extension,102,10,called,180",
    "userfield": "3"
}

Ejemplo dial a un número:

{
    "command": "dial",
    "options": "pstn,0034951223344,15,calling,180",
    "userfield": "3"
}

Ejemplo dial a un cuenta sip:

{
    "command": "dial",
    "options": "sipserver,103@pbx.midominio.com:5060,15,calling,180",
    "userfield": "3"
}

Hace una llamada a un destino, ya sea extensión de vPBX, teléfono de la red pública o extensión de un servidor SIP.

Puedes añadir varios destinos a la llamada concatenando cada número de teléfono o extensión por “&”.

Valores que contine options

"options": "{type},{destination},{max_ring},{transfer},{timeout}",

Valor Descripción Tipo Defecto
type Destino de la llamada string
destination Extensión, número o cuenta sip de destino string
max_ring Duración máxima del ring en segundos integer
transfer Permiso de transferencia de llamadas string
timeout Tiempo máximo de duración de la llamada integer

"type" puede tomar los valores "extension", "pstn" o "sipserver".

Se pueden añadir varios destionos a llamada concatenado cada número, extensión o cuenta sip con "&" en "destination".

"transfer" puede tomar los valores "calling" o "called".

"timeout" permite al usuario establecer la duración máxima de conversación en la llamada, siendo el valor mínimo de 5 segundos y máximo de 10 horas (36000 segundos).

Respuesta

La ejecución de “dial” devolverá el estado de la llamada dentro de la variable "description".

Valor Descripción
CHANUNAVAIL No existe destinatario de la llamada
BUSY El destinatario de la llamada da ocupado
NOANSWER El destinatario de la llamada no contesta la llamada
ANSWER El destinatario de la llamada contesta la llamada
CANCEL El llamante cuelga la llamada antes de que el destinatario la descuelgue
CONGESTION La llamada no se establece por problemas en la red telefónica.

google_voice2text

Ejemplo de google_voice2text:

{
    "command": "google_voice2text",
    "options": "AIzaSyBgfkU6CBytS1i9cbQKPX5zATwRQ2ml5Qo;es;15;0",
    "userfield": "3"
}

Se utiliza el servicio de reconocimiento de voz de Google para convertir la voz del llamante o llamado en texto legible por la aplicación del cliente.

Valores que contine options

"options": "{key};{language};{wait};{beep}",

Valor Descripción Tipo Defecto
key Generada en la API de reconocimiento de voz de Google APIs. string
language Código del idioma a reconocer de la "Tabla de idiomas de reconocimiento de voz" string
wait Nº de segundos de silencio que espera detectar hasta mandar la petición a Google integer
beep Reproducir el sonido "beep" para indicar el comienzo de la escucha 0 o 1

"key" debe ser una Key de Google válida y para obtener una consulta el apartado para "Voice to Text".

"beep" solo tiene dos valores: 0 reproduce el sonido "Beep" y 1 no lo reproduce.

Respuesta

La ejecución de este comando devolverá dos valores:

hangup

Ejemplo de hangup:

{
    "command"  : "hangup",
    "options"  : "",
    "userfield": "colgando"
}

Cuelga la llamada en curso.

Valores que contine options

El argumento options no se usa con el comando hangup, se recomienda poner una cadena vacía o un valor 0.

ivr

Ejemplo de ivr:

{
    "command"  : "ivr",
    "options"  : "eligedepartamento",
    "userfield": 3
}

Transfiere una llamada a un IVR existente en vPBX.

Valores que contine options

"options": "{name}",

Valor Descripción Tipo Defecto
name Nombre del ivr

language

Ejemplo de language:

{
    "command"  : "language",
    "options"  : "es",
    "userfield": 2
}

Establece el idioma para las locuciones predeterminadas cuando una llamada se desvía a vPBX.

Un ejemplo de locución puede ser "Por favor deje su mensaje después de la señal".

Por defecto el valor es el inglés (en).

Valores que contine options

"options": "{language}",

Valor Descripción Valores Defecto
language Dos caracteres que indican el idioma de las locuciones "en" o "es" "en"

play

Ejemplos de play:

{
    "command"  : "play",
    "options"  : "local;musica1&musica2&musica3",
    "userfield": 4
}
{
    "command"  : "play",
    "options"  : "remote;http://www.midominio.com/mimusica.mp3",
    "userfield": "musica"
}

Reproduce un fichero de sonido guardado en vPBX.

La localización del fichero se indica con "local" o "remote", se usa ";" para separar la localización del nombre del fichero.

"local" indica un fichero ubicado en vPBX y "remote" indica una url accesible públicamente donde se encuentra el fichero de audio.

Se pueden reproducir varios ficheros de forma secuencial usando como separador entre ficheros "&" (solo disponible para localización "local").

Valores que contine options

"options": "{location};{files}",

Valor Descripción Tipo Defecto
location Localización "local" o "remote"
files fichero o ficheros separados por "&" string

play_getdtmf

Ejemplos de play_getdtmf:

{
    "command"  : "play_getdtmf",
    "options"  : "local;musicadtmf;6000;3",
    "userfield": 2
}
{
    "command"  : "play_getdtmf",
    "options"  : "remote;http://www.midominio.com/mimusicadtmf.mp3;6000;2",
    "userfield": 2
}

Reproduce un fichero de sonido guardado en vPBX y espera a que sea marcada una opción DTMF.

La localización del fichero se indica con "local" o "remote", se usa ";" para separar la localización del nombre del fichero.

Una vez se pulse la cantidad máxima de dígitos DTMF parará la reproducción del fichero de audio y se enviara en la variable "dtmf" los dígitos marcados. En caso de no marcar ninguna tecla y pasado el tiempo de espera se enviará la variable "dtmf" con el valor “timeout”.

Valores que contine options

"options": "{location};{files};{wait};{digits}",

Valor Descripción Tipo Defecto
location Localización "local" o "remote"
file nombre de fichero o url string
wait Tiempo de espera en milisegundos integer
digits Máximo de dígitos DTMF integer

queue

Ejemplo de queue:

{
    "command": "queue",
    "options": "soporte;3",
    "userfield": ""
}

Transfiere una llamada a una cola de llamadas existente en vPBX con o sin prioridad.

La prioridad tiene un valor entre 1 y 10 siendo 1 la mayor prioridad. El valor por defecto es 0 (sin prioridad). Cada llamada es encolada por orden de entrada (FIFO).

Valores que contine options

"options": "{name};{priority}",

Valor Descripción Tipo Defecto
name Nombre de la cola
priority Valor de la prioridad De 0 a 10 0

record

Ejemplo de record:

{
    "command": "record",
    "options": "",
    "userfield": 1
}
{
    "command": "record",
    "options": "noconnect",
    "userfield": 1
}

Inicia la grabación de la llamada y finalizará cuando finalice la llamada.

La grabación de llamadas se realizará sobre el almacenamiento de netelip vDrive, con lo que será necesario activarlo antes de utilizar este comando (vDrive en su versión gratuita).

Una vez finalizada la llamada y realizada la grabación se devolverá la ruta del fichero en vDrive en la variable "description" con valor “/APIVoice/Record/fecha_llamada/nombre_fichero”.

Valores que contine options

"options": {option},

Valor Descripción Tipo Defecto
option vacío o "noconnect" ""

Options puede estar vacío "" o tener el valor "noconnect". Cuando se activa "noconnect" la grabación comenzará en el mismo momento en el que se ejecute el comando. Por defecto cuando no se añade esta opción la grabación de la llamada comienza cuando se conecta con una extensión, número de teléfono o servidor.

send_dtmf

Ejemplo de send_dtmf:

{
    "command": "send_dtmf",
    "options": "123;0.25",
    "userfield": "1"
}

Genera tonos DTMF en la llamada en curso.

Valores que contine options

"options": "{digits};{timeout}",

Valor Descripción Tipo Defecto
digits Lista de dítgitos, comprendidos entre 0-9,a-d,A-D,# y * string
timeout Duración en segundos entre tono y tono. Enter 1 y 60 float

speak

Ejemplos de speak:

{
    "command"  : "speak",
    "options"  : "netelip;Pedro;Bienvenido a Netelip;1.2",
    "userfield": 2
}
{
    "command"  : "speak",
    "options"  : "google;es;Bienvenido a Netelip;1.2",
    "userfield": 2
}

Reproduce el texto con la voz que se especifica (Text to speech).

Los proveedores de TTS disponibles son "netelip" y "google".

Para ver el código de voz que usará el proveedor consultar el apartado con la tabla de códigos TTS.

Valores que contine options

"options": "{provider};{code};{text};{speed}",

Valor Descripción Tipo Defecto
provider Proveedor: netelip o google
code Tabla de idiomas TTS. Consultar apartado.
text Texto a reproducir string
speed Velocidad de reproducción entre 1 y 2 float

speak_getdtmf

Ejemplos de speak_getdtmf:

{
    "command"  : "speak_getdtmf",
    "options"  : "netelip;Pedro;Introduzca su código de cliente;10000;5;1.2",
    "userfield": 2
}
{
    "command"  : "speak_getdtmf",
    "options"  : "google;es;Introduzca su código de cliente;10000;5;1.2",
    "userfield": 2
}

Reproduce el texto con la voz que se especifica (Text to speech) y espera a que sea marcada una opción DTMF.

Los proveedores de TTS disponibles son "netelip" y "google".

Para ver el código de voz que usará el proveedor consultar el apartado con la tabla de códigos TTS.

Una vez se pulse la cantidad máxima de dígitos DTMF se enviara en la variable "dtmf" los dígitos marcados. En caso de no marcar ninguna tecla y pasado el tiempo de espera se enviará la variable "dtmf" con el valor “timeout”.

Valores que contine options

"options": "{provider};{code};{text};{wait};{digits};{speed}",

Valor Descripción Tipo Defecto
provider Proveedor: netelip o google
code Tabla de idiomas TTS. Consultar apartado.
text Texto a reproducir string
wait Tiempo de espera en milisegundos integer
digits Máximo de dígitos DTMF integer
speed Velocidad de reproducción entre 1 y 2 float

voicemail

Ejemplos de voicemail:

{
    "command": "voicemail",
    "options": "100",
    "userfield": 9
}
{
    "command": "voicemail",
    "options": "110&112",
    "userfield": 11
}

Deja un mensaje en el buzón de voz de una o varias extensiones de vPBX. Si se añaden varias extensiones deben ir separadas por "&".

Valores que contine options

"options": "{extensions}",

Valor Descripción Tipo Defecto
extensions Extensión o extensiones de vPBX separadas por "&" De 100 a 199

Errores

API Voice de Netelip usa los siguientes códigos de error.

Estatos Descripción Cód. Respuesta
OK OK 200
ERROR Unauthorized 400
ERROR Command not found 401
ERROR Language not found 402
ERROR Invalid audio file 403
ERROR Invalid option/s 404
ERROR Options or userfield is empty 405
ERROR Userfield is empty 406
ERROR Invalid voicemail status 407
ERROR Voicemail do not exist 408
ERROR Extension/s do not exist 409
ERROR Invalid phone number 410
ERROR Queue do not exist 411
ERROR Conference room is not activated 412
ERROR vDrive service is not activated 413
ERROR netelip user do not exist or is not activated 414
ERROR Voice to text failed 415
ERROR Unable to get data recognition 416
ERROR Invalid send_dtmf options 417
ERROR Invalid SIP server port 418
ERROR Invalid SIP server IP address 419
ERROR File greater than 2MB 420
ERROR Invalid option timeout for dial command 422
ERROR Internal error server 500
ERROR Service Unavailable 503

Text to Speech (TTS)

API Voice de Netelip dispone de dos proveedores para usar Text to Speech (TTS), Netelip o Google.

Netelip

Tabla de idiomas:

Proveedor Idioma Código Ejemplo options para speak
netelip Español masculino Pedro options: "netelip;Pedro;Bienvenido a Netelip;1.2"
netelip Español femenino Silvia options: "netelip;Silvia;Bienvenido a Netelip;1.2"
netelip Catalan masculino Jordi options: "netelip;Jordi;Bienvenido a Netelip;1.2"
netelip Ingles masculino Brian options: "netelip;Brian;Bienvenido a Netelip;1.2"

Google

Tabla de idiomas:

Proveedor Idioma Código Ejemplo options para speak
google Afrikaans af options: "google;af;Bienvenido a Netelip;1.2"
google Albanian sq options: "google;sq;Bienvenido a Netelip;1.2"
google Amharic am options: "google;am;Bienvenido a Netelip;1.2"
google Arabic ar options: "google;ar;Bienvenido a Netelip;1.2"
google Armenian hy options: "google;hy;Bienvenido a Netelip;1.2"
google Azerbaijani az options: "google;az;Bienvenido a Netelip;1.2"
google Basque eu options: "google;eu;Bienvenido a Netelip;1.2"
google Belarusian be options: "google;be;Bienvenido a Netelip;1.2"
google Bengali bn options: "google;bn;Bienvenido a Netelip;1.2"
google Bihari bh options: "google;bh;Bienvenido a Netelip;1.2"
google Bosnian bs options: "google;bs;Bienvenido a Netelip;1.2"
google Breton br options: "google;br;Bienvenido a Netelip;1.2"
google Bulgarian bg options: "google;bg;Bienvenido a Netelip;1.2"
google Cambodian km options: "google;km;Bienvenido a Netelip;1.2"
google Catalan ca options: "google;ca;Bienvenido a Netelip;1.2"
google Chinese Simplified zh-CN options: "google;zh-CN;Bienvenido a Netelip;1.2"
google Chinese Traditional zh-TW options: "google;zh-TW;Bienvenido a Netelip;1.2"
google Corsican co options: "google;co;Bienvenido a Netelip;1.2"
google Croatian hr options: "google;hr;Bienvenido a Netelip;1.2"
google Czech cs options: "google;cs;Bienvenido a Netelip;1.2"
google Danish da options: "google;da;Bienvenido a Netelip;1.2"
google Dutch nl options: "google;nl;Bienvenido a Netelip;1.2"
google English en options: "google;en;Bienvenido a Netelip;1.2"
google Esperanto eo options: "google;eo;Bienvenido a Netelip;1.2"
google Estonian et options: "google;et;Bienvenido a Netelip;1.2"
google Faroese fo options: "google;fo;Bienvenido a Netelip;1.2"
google Filipino tl options: "google;tl;Bienvenido a Netelip;1.2"
google Finnish fi options: "google;fi;Bienvenido a Netelip;1.2"
google French fr options: "google;fr;Bienvenido a Netelip;1.2"
google Frisian fy options: "google;fy;Bienvenido a Netelip;1.2"
google Galician gl options: "google;gl;Bienvenido a Netelip;1.2"
google Georgian ka options: "google;ka;Bienvenido a Netelip;1.2"
google German de options: "google;de;Bienvenido a Netelip;1.2"
google Greek el options: "google;el;Bienvenido a Netelip;1.2"
google Guarani gn options: "google;gn;Bienvenido a Netelip;1.2"
google Gujarati gu options: "google;gu;Bienvenido a Netelip;1.2"
google Hacker xx-hacker options: "google;xx-hacker;Bienvenido a Netelip;1.2"
google Hausa ha options: "google;ha;Bienvenido a Netelip;1.2"
google Hebrew iw options: "google;iw;Bienvenido a Netelip;1.2"
google Hindi hi options: "google;hi;Bienvenido a Netelip;1.2"
google Hungarian hu options: "google;hu;Bienvenido a Netelip;1.2"
google Icelandic is options: "google;is;Bienvenido a Netelip;1.2"
google Indonesian id options: "google;id;Bienvenido a Netelip;1.2"
google Interlingua ia options: "google;ia;Bienvenido a Netelip;1.2"
google Irish ga options: "google;ga;Bienvenido a Netelip;1.2"
google Italian it options: "google;it;Bienvenido a Netelip;1.2"
google Japanese ja options: "google;ja;Bienvenido a Netelip;1.2"
google Javanese jw options: "google;jw;Bienvenido a Netelip;1.2"
google Kannada kn options: "google;kn;Bienvenido a Netelip;1.2"
google Kazakh kk options: "google;kk;Bienvenido a Netelip;1.2"
google Kinyarwanda rw options: "google;rw;Bienvenido a Netelip;1.2"
google Kirundi rn options: "google;rn;Bienvenido a Netelip;1.2"
google Klingon xx-klingon options: "google;xx-klingon;Bienvenido a Netelip;1.2"
google Korean ko options: "google;ko;Bienvenido a Netelip;1.2"
google Kurdish ku options: "google;ku;Bienvenido a Netelip;1.2"
google Kyrgyz ky options: "google;ky;Bienvenido a Netelip;1.2"
google Laothian lo options: "google;lo;Bienvenido a Netelip;1.2"
google Latin la options: "google;la;Bienvenido a Netelip;1.2"
google Latvian lv options: "google;lv;Bienvenido a Netelip;1.2"
google Lingala ln options: "google;ln;Bienvenido a Netelip;1.2"
google Lithuanian lt options: "google;lt;Bienvenido a Netelip;1.2"
google Macedonian mk options: "google;mk;Bienvenido a Netelip;1.2"
google Malagasy mg options: "google;mg;Bienvenido a Netelip;1.2"
google Malay ms options: "google;ms;Bienvenido a Netelip;1.2"
google Malayalam ml options: "google;ml;Bienvenido a Netelip;1.2"
google Maltese mt options: "google;mt;Bienvenido a Netelip;1.2"
google Maori mi options: "google;mi;Bienvenido a Netelip;1.2"
google Marathi mr options: "google;mr;Bienvenido a Netelip;1.2"
google Moldavian mo options: "google;mo;Bienvenido a Netelip;1.2"
google Mongolian mn options: "google;mn;Bienvenido a Netelip;1.2"
google Montenegrin sr-ME options: "google;sr-ME;Bienvenido a Netelip;1.2"
google Nepali ne options: "google;ne;Bienvenido a Netelip;1.2"
google Norwegian no options: "google;no;Bienvenido a Netelip;1.2"
google Norwegian Nynorsk nn options: "google;nn;Bienvenido a Netelip;1.2"
google Occitan oc options: "google;oc;Bienvenido a Netelip;1.2"
google Oriya or options: "google;or;Bienvenido a Netelip;1.2"
google Oromo om options: "google;om;Bienvenido a Netelip;1.2"
google Pashto ps options: "google;ps;Bienvenido a Netelip;1.2"
google Persian fa options: "google;fa;Bienvenido a Netelip;1.2"
google Pirate xx-pirate options: "google;xx-pirate;Bienvenido a Netelip;1.2"
google Polish pl options: "google;pl;Bienvenido a Netelip;1.2"
google Portuguese pt options: "google;pt;Bienvenido a Netelip;1.2"
google Portuguese Brazil pt-BR options: "google;pt-BR;Bienvenido a Netelip;1.2"
google Portuguese Portugal pt-PT options: "google;pt-PT;Bienvenido a Netelip;1.2"
google Punjabi pa options: "google;pa;Bienvenido a Netelip;1.2"
google Quechua qu options: "google;qu;Bienvenido a Netelip;1.2"
google Romanian ro options: "google;ro;Bienvenido a Netelip;1.2"
google Romansh rm options: "google;rm;Bienvenido a Netelip;1.2"
google Russian ru options: "google;ru;Bienvenido a Netelip;1.2"
google Scots Gaelic gd options: "google;gd;Bienvenido a Netelip;1.2"
google Serbian sr options: "google;sr;Bienvenido a Netelip;1.2"
google Serbo-Croatian sh options: "google;sh;Bienvenido a Netelip;1.2"
google Sesotho st options: "google;st;Bienvenido a Netelip;1.2"
google Shona sn options: "google;sn;Bienvenido a Netelip;1.2"
google Sindhi sd options: "google;sd;Bienvenido a Netelip;1.2"
google Sinhalese si options: "google;si;Bienvenido a Netelip;1.2"
google Slovak sk options: "google;sk;Bienvenido a Netelip;1.2"
google Slovenian sl options: "google;sl;Bienvenido a Netelip;1.2"
google Somali so options: "google;so;Bienvenido a Netelip;1.2"
google Spanish es options: "google;es;Bienvenido a Netelip;1.2"
google Sundanese su options: "google;su;Bienvenido a Netelip;1.2"
google Swahili sw options: "google;sw;Bienvenido a Netelip;1.2"
google Swedish sv options: "google;sv;Bienvenido a Netelip;1.2"
google Tajik tg options: "google;tg;Bienvenido a Netelip;1.2"
google Tamil ta options: "google;ta;Bienvenido a Netelip;1.2"
google Tatar tt options: "google;tt;Bienvenido a Netelip;1.2"
google Telugu te options: "google;te;Bienvenido a Netelip;1.2"
google Thai th options: "google;th;Bienvenido a Netelip;1.2"
google Tigrinya ti options: "google;ti;Bienvenido a Netelip;1.2"
google Tonga to options: "google;to;Bienvenido a Netelip;1.2"
google Turkish tr options: "google;tr;Bienvenido a Netelip;1.2"
google Turkmen tk options: "google;tk;Bienvenido a Netelip;1.2"
google Twi tw options: "google;tw;Bienvenido a Netelip;1.2"
google Uighur ug options: "google;ug;Bienvenido a Netelip;1.2"
google Ukrainian uk options: "google;uk;Bienvenido a Netelip;1.2"
google Urdu ur options: "google;ur;Bienvenido a Netelip;1.2"
google Uzbek uz options: "google;uz;Bienvenido a Netelip;1.2"
google Vietnamese vi options: "google;vi;Bienvenido a Netelip;1.2"
google Welsh cy options: "google;cy;Bienvenido a Netelip;1.2"
google Xhosa xh options: "google;xh;Bienvenido a Netelip;1.2"
google Yiddish yi options: "google;yi;Bienvenido a Netelip;1.2"
google Yoruba yo options: "google;yo;Bienvenido a Netelip;1.2"
google Zulu zu options: "google;zu;Bienvenido a Netelip;1.2"

Voice to Text

Para poder usar el servicio de Google se deben seguir estos pasos:

1 Ir a la consola de Google Cloud

2 Habilitar el producto y servicio "Google Cloud Speech API"

3 Acceder a 'APIs y servicios -> Credenciales' y crear una clave de API. Para restringir el acceso por IP a la key generada para la API se debe pulsar sobre ella y añadir la IP, por ejemplo la ip de apivoice 185.8.244.102.

4 Obtenida la key ya está listo para añadirlo como parámetro en el comando.

Tabla de idiomas de reconocimiento de vox de Google:

País Idioma Código
Afrikaans af-ZA
Bahasa Indonesia id-ID
Bahasa Melayu ms-MY
Català ca-ES
Čeština cs-CZ
Deutsch de-DE
Australia English en-AU
Canada English en-CA
India English en-IN
New Zealand English en-NZ
South Africa English en-ZA
United Kingdom English en-GB
United States English en-US
Argentina Español es-AR
Bolivia Español es-BO
Chile Español es-CL
Colombia Español es-CO
Costa Rica Español es-CR
Ecuador Español es-EC
El Salvador Español es-SV
España Español es-ES
Estados Unidos Español es-US
Guatemala Español es-GT
Honduras Español es-HN
México Español es-MX
Nicaragua Español es-NI
Panamá Español es-PA
Paraguay Español es-PY
Perú Español es-PE
Puerto Rico Español es-PR
República Dominicana Español es-DO
Uruguay Español es-UY
Venezuela Español es-VE
Euskara eu-ES
Français fr-FR
Galego gl-ES
Hrvatski hr_HR
IsiZulu zu-ZA
Íslenska is-IS'
Italia Italiano it-IT
Svizzera Italiano it-CH
Magyar hu-HU
Nederlands nl-NL
Norsk bokmål nb-NO
Polski pl-PL
Brasil Português pt-BR
Portugal Português pt-PT
Română ro-RO
Slovenčina sk-SK
Suomi fi-FI
Svenska sv-SE
Türkçe tr-TR
български bg-BG
Pусский ru-RU
Српски sr-RS
한국어 ko-KR
普通� (中国大�) 中文 cmn-Hans-CN
普通� (香港) 中文 cmn-Hans-HK
中文 (台灣) 中文 cmn-Hant-TW
�語 (香港) 中文 yue-Hant-HK
日本語 ja-JP
Lingua latīna la

Caso práctico: flujo

Para ver el funcionamiento de API Voice se muestra a continuación el flujo de una llamada. Las peticiones que realiza API Voice se indican con "P:" y las respuestas del controlador del cliente con "R:".

P: Recepción de llamada

Petición #1:

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "startcall": "2019-11-14 11:04:26",
   "typesrc": "did",
   "usersrc": "638829213"
}

API Voice recibe una llamada y realiza una petición a su URL de control de llamadas con todos los datos en POST.

R: Locución de espera

Respuesta #1:

{
   "command"  : "speak",
   "options"  : "google;es;Espere por favor.",
   "userfield": "1"
}

El controlador recibe los datos de la llamada y le contesta a API Voice para que reproduzca una locución a partir del text con el comando speak.

P: Espera terminada

Petición #2:

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "startcall": "2019-11-14 11:04:26",
   "typesrc": "did",
   "usersrc": "638829213",
   "command": "speak", 
   "options": "google;es;Espere por favor.",
   "userfield": "1",
   "description": "OK",
   "statuscode": "200",
   "startcall": "2019-11-14 11:04:26",
   "durationcall": "3",
   "durationcallanswered": "", 
   "statuscall": "ANSWER", 
   "channel": "U5lQL1MTMy0wNDAwNGMlNQ==",
   "typesrc": "did",
   "usersrc": "683282931"
}

API Voice reproduce el texto y envía una nueva petición con el estado de la llamada.

API Voice copia los tres parámetros command, options y userfield tal como los recibió para que el controlador pueda saber que es lo último que hizo.

R: Grabar la llamada

Respuesta #2:

{
   "command": "record",
   "options": "",
   "userfield": "2"
}

El controlador responde a API Voice indicando que active la grabación de la llamada.

P: Grabando

Petición #3:

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "userfield": "2",
   "command": "record", 
   "options": "",
   "description": "OK",
   "statuscode": "200",
   "startcall": "2019-11-14 11:04:26",
   "durationcall": "4",
   "durationcallanswered": "",
   "dtmf": "",
   "statuscall": "ANSWER",
   "channel": "U5lQL1MTMy0wNDAwNGMlNQ==",
   "typesrc": "did",
   "usersrc": "638829213"
}

API Voice activa la grabación de la llamada, crea el fichero de audio y envía una petición a su URL de control de llamadas con la información de la llamada y el comando ejecutado.

R: Identificador de llamada

Respuesta #3

{
   "command": "callerid",
   "options": "638829213;34951504990",
   "userfield":"3"
}

El controlador indica a API Voice que cambie el identificador de llamada.

P: Identificador cambiado

Petición #4

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "userfield": "3",
   "command": "callerid", 
   "options": "638829213;34951504990",
   "description": "CallerID is updated 34951504990",
   "statuscode": "200",
   "startcall": "2019-11-14 11:04:26",
   "durationcall": "4",
   "durationcallanswered": "",
   "dtmf": "",
   "statuscall": "ANSWER",
   "channel": "U5lQL1MTMy0wNDAwNGMlNQ==",
   "typesrc": "did",
   "usersrc": "638829213"
}

API Voice cambia el identificador de llamada y envía una petición a su controlador indicando el estado de la llamada y espera nuevo comando.

R: Realizar una llamada

Respuesta #4

{
   "command": "dial",
   "options": "pstn,655443322,60",
   "userfield": "4"
}

El controlador responde indicando a API Voice que realice una llamada a un número de la red pública.

P: Llamada terminada

Petición #4: NOANSWER

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "userfield": "4",
   "command": "dial", 
   "options": "pstn,655443322,60",
   "description": "NOANSWER",
   "statuscode": "200",
   "startcall": "2019-11-14 11:04:26",
   "durationcall": "64",
   "durationcallanswered": "",
   "dtmf": "",
   "statuscall": "ANSWER",
   "channel": "U5lQL1MTMy0wNDAwNGMlNQ==",
   "typesrc": "did",
   "usersrc": "638829213"
}

Petición #4: ANSWER

{
   "ID": "1576556033.1735",
   "api": "API 13a05",
   "src": "638829213",
   "dst": "34951504990",
   "userfield": "4",
   "command": "dial", 
   "options": "pstn,655443322,60",
   "description": "ANSWER",
   "statuscode": "200",
   "startcall": "2019-11-14 11:04:26",
   "durationcall": "96",
   "durationcallanswered": "92",
   "dtmf": "",
   "statuscall": "ANSWER",
   "channel": "U5lQL1MTMy0wNDAwNGMlNQ==",
   "typesrc": "did",
   "usersrc": "638829213"
}

Una vez que API Voice realiza la llamada enviará el resultado de esta en una petición a su URL de control de llamadas.

El el campo description se indicará el resultado de la llamada realizada por el comando dial.

Los campos durationcall y durationcallanswered reflejarán la duración de la llamada.

Terminada la llamada API Voice envía la petición y espera la siguiente orden.

R: Colgando la llamada

Respuesta #5

{
   "command": "hangup",
   "options": "",
   "userfield":""
}

El controlador recibe el estado de la llamada realizada por API Voice e indica que se debe colgar la llamada y terminar el flujo de peticiones.