Voice
Place a call to a specific phone number via the Voice API of seven. In the simplest version, you can enter a text which is then read out to the recipient via our text-to-speech (TTS) gateway. For more advanced applications, you have the option of sending the text in SSML format.
Send voice call
Create a new TTS call to a phone number.
Parameter
- Name
to
- Type
- string
- Description
Recipient number of the SMS. This can also be the name of a contact or a group. Our API accepts all common formats such as 0049171123456789, 49171123456789, +49171123456789. Multiple recipients are transferred comma-separated. Ideally, you should enter the phone number in international format after E.164.
- Name
text
- Type
- string
- Description
Text message to be read out. Optionally as plain text or as SSML.
Optional parameters
- Name
from
- Type
- string
- Description
Caller ID of the call. Please only use verified sender IDs or one of your phone numbers booked with us.
- Name
ringtime
- Type
- integer
- Description
The duration of how long the recipient should hear the call before hanging up. Between 5 and 60 seconds are possible here.
Request
curl -X POST https://gateway.seven.io/api/voice \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-d "to=49176123456789" \
-d "text=Hello world!"
Answer
{
"success": "100",
"total_price": 0.045,
"balance": 3509.236,
"debug": false,
"messages": [
{
"id": 1384013,
"sender": "sender",
"recipient": "49176123456789",
"text": "Hello world!",
"price": 0.045,
"success": true,
"error": null,
"error_text": null
}
]
}
SSML
You can use the Speech Synthesis Markup Language (SSML) to control speech generation. Use SSML to record audio files, change the voice and language, insert pauses and much more.
Detailed information on the use of SSML and the possible commands can be found in the Microsoft documentation.
Pauses
Would you like a little more pause at a certain point? You can control pauses as you wish.
Now comes a pause.
<break time="2s" />
The pause is over.
Different voices
With SSML you have the option of selecting different voices. You can differentiate between female, male or child voices.
Many international languages are also available, e.g. English dialects, French, Arabic, Asian, Croatian or Russian.
The children's voices are not available in every language.
For the voice tag, the name
attribute is composed of the region abbreviation (de-DE, or en-US) and the gender. Example "en-us-female".
<voice name="en-gb-female">"Great Britain, whose children we are, and whose language we speak,
should no longer be our standard; for the taste of her writers is already corrupted,
and her language on the decline." -Noah Webster, 1789 </voice>
Sentences and paragraphs
You can use the p
and s
tags to structure a paragraph and the sentences it contains.
<p>
<s>Hello, this is the audio book of the little girl with the red balloon!</s>
<s>I have them read to me every night to fall asleep.</s>
</p>
Codes and numbers
For codes, reading as individual letters and characters is recommended. Numbers can be divided into integers, single digits and ordinals. Below are three examples from everyday use.
<voice name="de-de-male">
Your code is:
<prosody rate="slow">
<say-as interpret-as="number_digit">967354</say-as>
</prosody>
</voice>
To transfer a code, it is better to read it out character by character and slightly slower. Note in this example that the small "p" is also only read out as "P". We therefore split the example code "LK9p7U" into two say-as tags:
<voice name="de-de-female">
Your code reads:
<prosody rate="x-slow">
<say-as interpret-as="characters">LK9small</say-as>P
<say-as interpret-as="characters">7U</say-as>
</prosody>
</voice>
We synthesize integers without a tag. Speech synthesis automatically recognizes monetary amounts and reads "13.50 euros" as "13 euros 50 cents".
<voice name="de-de-female">
The sum is 13.50 euros.
</voice>
For length or weight specifications, it is best to write out the units.
<voice name="de-de-female">
The building is 18 meters high. The fish weighs 3.5 kilos.
</voice>
Output of an audio file
You can play audio files from any source in your SSML.
<audio src="https://static.seven.io/sample.mp3" />
You can also combine the synthesis of your text and the playback of an external media file.
<voice name="de-de-child">
Hello, listen to this
<audio src="https://static.seven.io/sample.mp3" />
</voice>
Status of the call
You receive the current status of the call immediately with every change via webhook.
Status | Description |
---|---|
failed | The call has failed |
initiated | The call has been initiated. |
ringing | It is ringing. |
in-progress | The call is active. |
busy | The number is busy. |
rejected | The call has been rejected. |
no-answer | The call was not answered after the defined ring duration. |
completed | The call has been completed. |