Voice

Setzen Sie über die Voice API von seven einen Anruf an eine bestimmte Rufnummer ab. In der einfachsten Variante können Sie einen Text angeben, der dann über unser Text-To-Speech (TTS) Gateway beim Empfänger vorgelesen wird. Für erweiterte Anwendungen haben Sie die Möglichkeit, den Text im SSML Format zu senden.

Voice Anruf senden

Erstellen Sie einen neuen TTS Anruf an eine Rufnummer.

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

Anruf beenden

Dieser Endpunkt beendet einen aktiven Anruf. Es können nur Anrufe beendet werden, deren Status in-progress ist.

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

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

SSML

Über die Speech Synthesis Markup Language (SSML) können Sie die Spracherzeugung steuern. Nutzen Sie SSML zum Einspielen von Audiodateien, zur Änderung der Stimme und Sprache, zum Einbauen von Pausen und vieles mehr.

Detaillierte Informationen zur Verwendung von SSML und den möglichen Befehlen können Sie der Dokumentation von Microsoft entnehmen.

Pausen

Möchten Sie etwas mehr Pause an einer bestimmten Stelle? Sie können Pausen beliebig steuern.

Jetzt kommt eine Pause.
<break time="2s" />
Die Pause ist vorbei.

Verschiedene Stimmen

Mit SSML haben Sie die Möglichkeit, verschiedene Stimmen auszuwählen. Sie können das Geschlecht unterschieden nach weiblich (female), männlich (male) oder Kinderstimme (child) einsetzen. Ebenso sind viele internationale Sprachen für z.B. englische Dialekte, Französisch, Arabisch, Asiatisch, Kroatisch oder Russisch verfügbar. Die Kinderstimmen sind nicht in jeder Sprache verfügbar. Für den Voice-Tag wird das Attribut name aus dem Regionskürzel (de-DE, oder en-US) und dem Geschlecht zusammengesetzt. Beispiel "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>

Sätze und Absätze

Mit den Tags p und s können Sie einen Absatz und die darin enthaltenen Sätze strukturieren.

<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 und Zahlen

Für Codes empfiehlt sich die Lesung als einzelne Buchstaben und Zeichen. Zahlen können in Ganzzahlen, Einzelziffen und Ordinale unterschieden werden. Im folgenden drei Beispiele dazu aus dem täglichen Gebrauch.

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

Für die Übergabe eines Codes liest man besser Zeichen für Zeichen und etwas verlangsamt vor. Beachten Sie in diesem Beispiel, dass das kleine "p" auch nur als "P" vorgelesen wird. Deshalb trennen wir den Beispielcode "LK9p7U" in zwei say-as-Tags auf:

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

Ganzzahlen synthetisieren wir ohne Tag. Die Sprachsynthese erkennt Geldbeträge automatisch und liest "13,50 Euro" als "13 Euro 50 Cent".

<voice name="de-de-female">
  Die Summe beträgt 13,50 Euro.
</voice>

Für Längen- oder Gewichtsangaben schreiben Sie die Einheiten am besten aus.

<voice name="de-de-female">
  Das Gebäude ist 18 Meter hoch. Der Fisch wiegt 3,5 Kilo.
</voice>

Ausgabe einer Audiodatei

In Ihrem SSML können Sie Audiodateien von beliebiger Quelle abspielen lassen.

<audio src="https://static.seven.io/sample.mp3" />

Sie können die Synthetisierung Ihres Textes und das Abspielen einer externen Mediendatei auch kombinieren.

<voice name="de-de-child">
  Hallo, hör dir das mal an
  <audio src="https://static.seven.io/sample.mp3" />
</voice>

Wiederholung eines Voice-Tags

Für den voice-Tag wird das Attribut loop verwendet, um die Anzahl der Wiederholungen festzulegen. Mit dem optionalen Attribut loop-info können Sie die jeweilige Wiederholung ankündigen.

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

DTMF

DTMF (Dual-Tone Multi-Frequency) ist ein Verfahren zur Übertragung von Ziffern über das Telefonnetz. Es wird auch als Mehrfrequenzwahlverfahren bezeichnet. Mit DTMF können Sie den Empfänger auffordern, eine Taste auf dem Telefon zu drücken. Dies kann z.B. für die Bestätigung einer Buchung oder die Weiterleitung eines Anrufs an eine bestimmte Abteilung verwendet werden. Für die Auswertung von DTMF-Signalen können Sie im SSML das DTMF-Tag einsetzen.

Auswertung DTMF Tastendruck

Wird während des Calls eine Nummerntaste gedrückt, wird das DTMF-Signal an die angegebene Webhook-URL über ein JSON-Objekt übergeben und im Feld "voice-dtmf" angezeigt. Information zum Einrichten von Webhooks finden Sie auf unserer Webhook-Seite.

{
  "webhook_event": "voice_dtmf",
  "webhook_timestamp": "2024-08-02T07:28:59+02:00",
  "data": {
    "id": 0,
    "callerId": "4943160049851",
    "recipient": "4943160049851",
    "status": "completed",
    "system": "4915170517246",
    "timestamp": 1722576539,
    "duration": 2.76,
    "pricePerMinute": 0.045,
    "dtmf_digit": 9,
    "total_price": 0.045
  }
}

Status des Anrufs

Sie erhalten den aktuellen Status des Anrufs sofort bei jeder Änderung per Webhook.