Voz - API de integración¶

OBM API es el proveedor de voz que permite realizar llamadas y reproducir una lista de archivos .wav. También utiliza TTS para la composición del mensaje, permitiendo generar mensajes más detallados y fáciles de entender.

1. Solicitud HTTP que debe realizar el cliente¶

La trama para realizar una llamada es la siguiente:

POST https://send.obmessage.ai/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": 1,
    "voice": {
        "name": "string",
        "audio": {
            "pitch": 0,
            "speed": 0,
            "volume_db": 0,
            "profile": "string"
        },
        "messages": [
            {
                "type": "string",
                "file": {
                    "id": "string"
                }
            },
            {
                "type": "string",
                "input": {
                    "text": "string"
                }
            }
        ]
    },
    "fields": [
        {
            "name": "string",
            "value": "string",
            "short": true
        }
    ]
}

Importante

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

Importante

Para usar archivos .wav, estos deben subirse al File Server y se debe 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 E.164.	Sí
from	Número telefónico del emisor.	Sí
reference	Valor de referencia individual del mensaje.	No
template_id	ID de la plantilla. Si este campo se envía, se ignora `voice`.	No
not_sent_after	Todo mensaje procesado después de la hora indicada se marcará con estado `cancelled`. El formato de hora debe ser `UTC`. Este campo no es obligatorio, pero es recomendable para evitar envíos fuera del horario regulado. Ver el apartado de políticas.	No
replay_times	Cantidad de veces que se repetirá el audio de la 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 la voz.	No
voice.audio.volume_db	Define el volumen de la voz.	No
voice.audio.profile	Define el perfil de optimización de voz.	No
voice.messages	Conjunto de mensajes para reproducir durante la llamada.	Sí
voice.messages.type	Define el tipo de mensaje. Tipos disponibles: `wav` y `tts`.	No
voice.messages.file	Datos del archivo `.wav`. Solo aplica para `type=wav`.	No
voice.messages.file.id	ID del archivo en el File Server.	Sí
voice.messages.input	Datos para la generación de `tts`. Solo aplica para `type=tts`.	No
voice.messages.input.text	Texto para convertir a voz.	Sí
fields	Conjunto de campos dinámicos asociados al mensaje.	No
fields.name	Nombre del campo.	Sí
fields.value	Valor correspondiente al campo.	Sí
fields.short	Indica si el valor del campo será acortado.	No

2.1 Trama JSON de ejemplo¶

POST https://send.obmessage.ai/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": "cuota",
            "value": "138.98",
            "short": false
        }
    ]
}

Pruébalo 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, correspondiente al mismo valor enviado.
group	Valor de referencia grupal del mensaje, correspondiente al 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 RFC 3339.

3. Soporte TTS¶

Contamos con una amplia variedad de voces. Entre los tipos disponibles se encuentran:

Neural2: voces basadas en la misma tecnología utilizada para crear voces personalizadas. Neural2 representa una generación avanzada de voz sintética y permite su uso sin necesidad de entrenar una voz personalizada.
WaveNet: red neuronal profunda para generar audio muestra a muestra.

Más información

Para conocer más sobre estos servicios, puede hacer clic en este enlace.

Para consultar las voces disponibles, utilice el siguiente endpoint:

GET https://api.obmessage.ai/api/v1/voices

Este endpoint retorna una respuesta similar a la siguiente:

{
    "name": "gl-ro-RO-Wavenet-A",
    "language_code": "ro-RO",
    "type": "wavenet",
    "gender": "female",
    "natural_sample_rate_hertz": 24000
}