Voice¶

Before you begin¶

Prepare the destination and origin numbers, and choose a voice template or a voice composition. TTS means text-to-speech. For WAV blocks, upload the audio to the File Server and retain its file ID.

Review Authentication and replace all example values, including template IDs and dates, before submitting a request.

Request workflow¶

Prepare the HTTP request shown below.
Complete the required fields and only the optional fields needed by your integration.
Submit the request and inspect its response.
Retain the returned identifier, when provided, and check the result before repeating a delivery.

HTTP request¶

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.

Request fields¶

The table identifies required and optional fields. Requirements for nested fields apply when the corresponding object or message type is used.

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

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

Response¶

The endpoint returns 200 OK with the following JSON response. Inspect status; this response alone does not confirm that the call was answered or completed.

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

Response fields¶

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.

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://send.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
}

Check results and errors¶

Review the channel records in Activities. Keep the reference and group used by your integration to locate the records. For unsuccessful requests, see Error responses.