Voice

Make a call to a specific number using seven's Voice API. In the simplest variant, you can specify a text that will then be read out to the recipient via our Text-To-Speech (TTS) Gateway. For advanced applications, you have the option to send the text in SSML format.

Send Voice Call

Create a new TTS call to a number.

curl -X POST https://gateway.seven.io/api/voice \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -d "to=49176123456789" \
  -d "text=Hallo Welt!"

{
  "success": "100",
  "total_price": 0.045,
  "balance": 3509.236,
  "debug": false,
  "messages": [
    {
      "id": 1384013,
      "sender": "sender",
      "recipient": "49176123456789",
      "text": "Hallo Welt!",
      "price": 0.045,
      "success": true,
      "error": null,
      "error_text": null
    }
  ]
}

Hangup a call

This endpoint ends an active call. Only calls with the status in-progress can be ended.

curl -X POST https://gateway.seven.io/api/voice/123456/hangup \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

{
  "success": true,
  "error": null
}

SSML

The Speech Synthesis Markup Language (SSML) allows you to control speech generation. Use SSML to play audio files, change the voice and language, insert pauses, and much more.

Detailed information on how to use SSML and the possible commands can be found in the Microsoft documentation.

Pauses

Do you want a little more pause at a certain point? You can control pauses as you like.

Now comes a pause.
<break time="2s" />
The pause is over.

Different Voices

With SSML, you have the option to select different voices. You can distinguish the gender as female, male, or child's voice. Also, many international languages are available for e.g. English dialects, French, Arabic, Asian, Croatian, or Russian. The child 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

With the p and s tags, you can structure a paragraph and the sentences contained in it.

<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, it is recommended to read as individual letters and characters. Numbers can be distinguished in integers, single digits, and ordinals. Here are three examples from everyday use.

<voice name="de-de-female">
    Der Bestätigungscode lautet:
    <prosody rate="slow">
    <say-as interpret-as="characters">967354</say-as>
    </prosody>
</voice>

For the transfer of a code, it is better to read character by character and a little slowed down. Note in this example that the small "p" is also only read as "P". Therefore, we divide the example code "LK9p7U" into two say-as tags:

<voice name="de-de-female">
  Ihr Code lautet:
  <prosody rate="x-slow">
    <say-as interpret-as="characters">LK9</say-as>klein P
    <say-as interpret-as="characters">7U</say-as>
  </prosody>
</voice>

We synthesize integers without a tag. The speech synthesis automatically recognizes amounts of money and reads "13,50 Euro" as "13 Euros 50 cents".

<voice name="de-de-female">
  The total 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

In your SSML, you can play audio files from any source.

<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">
  Hallo, hör dir das mal an
  <audio src="https://static.seven.io/sample.mp3" />
</voice>

Repetition of a voice tag

For the voice tag, the loop attribute is used to determine the number of repetitions. With the optional loop-info attribute, you can announce each repetition.

<voice name="de-de-female" loop="2" loop-info="Ich wiederhole">
    Der Bestätigungscode lautet:
    <say-as interpret-as="characters">5684</say-as>
</voice>

Call status

You will receive the current status of the call immediately with each change via webhook.