Saltar a contenido

Voz - API de integración

OBM API es el proveedor de voz que permite la realización de llamadas y reproducir una lista de archivos .wavs. También utiliza TTS para la composición del mensaje. Y asi conseguir un mensaje mas detallado y fácil de entender.

1. Solicitud HTTP que debe hacer el cliente

La trama para realizar una llamada es la siguiente:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
POST https://obm.ofimatic.net/api/v1/voice
X-API-Key: {{API_KEY}}
Content-Type: application/json

{
    "phone": string,
    "from": string,
    "reference": string,
    "group": string,
    "template_id": string,
    "not_sent_after": string,
    "replay_times": int,
    "voice": {
        "name": string,
        "audio": {
            "pitch": int,
            "speed": int,
            "volume_db": int,
            "profile": string
        },
        "messages": [
            {
                "type": string,
                "file": {
                    "id": string
                }
            },
            {
                "type": string,
                "input": {
                    "text": string
                }
            }
        ]
    },
    "fields": [
        {
            "name": string,
            "value": string,
            "short": boolean
        }
    ]
}

Importante

También es compatible el uso de plantilla de voz. En este caso en lugar de voice se envía template_id con el código de identificación de la plantilla.

Importante

Para el uso de archivos .wav se debe subir al fileserver y enviar el ID del archivo en voice.messages.file.id.

2. Datos obligatorios

Los siguientes datos son requeridos:

Campo Descripción Obligatorio
phone Número telefónico al cual se realiza la llamada. Debe ser compatible con la recomendación e164. SI
from Número telefónico del emisor. SI
reference Valor de referencia individual del mensaje. NO
template_id ID de plantilla. Si este campo se envía, se ignora el campo voice NO
not_sent_after Todo lo que sea enviado después de la hora indicada se le coloca el estado de cancelled, el formato de hora que se debe de utilizar es UTC. Esto no es obligatorio pero es recomendable para evitar envios de notificaciones fuera del horario regulado. Ver el apartado de políticas. NO
replay_times Se utiliza para repetir el audio le llamada. NO
voice.name Nombre de la voz utilizada para la generación de TTS. NO
voice.audio Datos para la configuración del audio TTS. NO
voice.audio.pitch Define el tono de voz. NO
voice.audio.speed Define la velocidad de voz. NO
voice.audio.volume_db Define el volumen de voz. NO
voice.audio.profile Define el perfil de optimización de voz. NO
voice.messages Conjunto de mensajes para reproducción en la llamada. SI
voice.messages.type Define el tipo de mensaje. Tipos disponibles: wav y tts NO
voice.messages.file Datos del archivo .wav. Solo para type=wav. NO
voice.messages.file.id ID del archivo en el Fileserver. SI
voice.messages.input Datos para la generación de tts. Solo para type=tts. NO
voice.messages.input.text Texto para la conversación a voz. SI
fields Conjunto de campos dinámicos asociados al mensaje. NO
fields.name Nombre del campo. SI
fields.value Valor correspondiente al campo. SI
fields.short Indica si el valor del campo sera acortado. NO

2.1 Trama JSON de ejemplo

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
POST https://obm.ofimatic.net/api/v1/voice
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{
    "phone": "+18099999999",
    "from": "8099999999",
    "reference": "9999",
    "group": "999",
    "template_id": "581970c8-f7ce-4533-be7e-8064c3adce0e", 
    "not_sent_after": "2024-02-12T23:30:59Z",
    "replay_times": 1,
    "fields":[
        {
            "name": string, 
            "value": string, 
            "short": boolean
        }
    ]
}
Pruebalo en Postman

2.2 Respuesta

Si la llamada se realiza correctamente, se retorna el código 200 OK con la siguiente trama JSON:

{
    "id": string, 
    "phone": string, 
    "reference": string, 
    "group": string, 
    "status": string, 
    "created_at": string
}

2.3 Descripción de los campos de la respuesta

Campo Descripción
id Código de identificación del mensaje.
phone Número telefónico del destinatario.
reference Valor de referencia del mensaje (mismo valor enviado).
group Valor de referencia grupal del mensaje (mismo valor enviado).
status Estado actual del mensaje. Los estados son received y error.
created_at Fecha en la que se recibe el mensaje en formato rfc3339.

3. Soporte TTS

Contamos con una amplia variedad de voces, contamos con dos tipos que son lideres en esto.

  • Neural2: se basan en la misma tecnología que se usa para crear una voz personalizada. Neural2 representa la ultima generación de voz sintética y permite que se pueda utilizar sin necesidad de entrenar esta voz.
  • WavNet: es una red neuronal profunda para generar audio muestra a muestra.

Mas información

Si quiere conocer más sobre estos servicios puede hacer clic en este enlace.

Para poder consumir las distintas voces disponibles utiliza este endpoint para poder ver las que están disponibles: 

https://tts-api.ofimatic.net/api/v1/voices
Este API retorna lo siguiente: 

1
2
3
4
5
6
7
{
    "name": "gl-ro-RO-Wavenet-A",
    "language_code": "ro-RO",
    "type": "wavenet",
    "gender": "female",
    "natural_sample_rate_hertz": 24000
}