Voice - Integration API¶

OBM API is the voice provider that allows calls to be made and a list of .wav files to be played. It also uses TTS for message composition, allowing more detailed and easier-to-understand messages to be generated.

1. HTTP request to be made by the client¶

The payload to make a call is as follows:

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
        }
    ]
}

Important

Voice templates are also supported. In this case, instead of sending voice, send template_id with the template identification code.

Important

To use .wav files, they must be uploaded to the File Server and the file ID must be sent in voice.messages.file.id.

2. Required data¶

The following data is required:

Field	Description	Required
phone	Phone number to which the call will be made. It must be compatible with the E.164 recommendation.	Yes
from	Sender phone number.	Yes
reference	Individual message reference value.	No
template_id	Template ID. If this field is sent, `voice` is ignored.	No
not_sent_after	Any message processed after the specified time will be marked with the `cancelled` status. The time format must be `UTC`. This field is not required, but it is recommended to avoid sending notifications outside regulated hours. See the policies section.	No
replay_times	Number of times the call audio will be repeated.	No
voice.name	Name of the voice used for TTS generation.	No
voice.audio	Data for TTS audio configuration.	No
voice.audio.pitch	Defines the voice pitch.	No
voice.audio.speed	Defines the voice speed.	No
voice.audio.volume_db	Defines the voice volume.	No
voice.audio.profile	Defines the voice optimization profile.	No
voice.messages	Set of messages to be played during the call.	Yes
voice.messages.type	Defines the message type. Available types: `wav` and `tts`.	No
voice.messages.file	`.wav` file data. Applies only to `type=wav`.	No
voice.messages.file.id	File ID in the File Server.	Yes
voice.messages.input	Data for `tts` generation. Applies only to `type=tts`.	No
voice.messages.input.text	Text to convert to speech.	Yes
fields	Set of dynamic fields associated with the message.	No
fields.name	Field name.	Yes
fields.value	Field value.	Yes
fields.short	Indicates whether the field value should be shortened.	No

2.1 Sample JSON payload¶

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
        }
    ]
}

Try it in Postman

2.2 Response¶

If the call is completed successfully, the API returns 200 OK with the following JSON payload:

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

2.3 Response field description¶

Field	Description
id	Message identification code.
phone	Recipient phone number.
reference	Message reference value, corresponding to the same value sent.
group	Group reference value, corresponding to the same value sent.
status	Current message status. Possible values are `received` and `error`.
created_at	Date when the message is received, in RFC 3339 format.

3. TTS support¶

We provide a wide variety of voices. Available types include:

Neural2: voices based on the same technology used to create custom voices. Neural2 represents an advanced generation of synthetic voice and can be used without training a custom voice.
WaveNet: deep neural network used to generate audio sample by sample.

More information

To learn more about these services, click this link.

To query the available voices, use the following endpoint:

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

This endpoint returns a response similar to the following:

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