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.

POST/api/voice

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

POST
/api/sms
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.

StatusDescription
failedThe call has failed
initiatedThe call has been initiated.
ringingIt is ringing.
in-progressThe call is active.
busyThe number is busy.
rejectedThe call has been rejected.
no-answerThe call was not answered after the defined ring duration.
completedThe call has been completed.