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 ohne <dtmf/>-Tag

Wird während des Calls eine Nummerntaste gedrückt und sofern der Anruf sich aktuell nicht explizit in einem <dtmf/>-Tag befindet, wird das DTMF-Signal an die in Ihrem Account hinterlegte Webhook-URL ü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
  }
}

Auswertung DTMF Tastendruck mit <dtmf/>-Tag

Sie können das <dtmf/>-Tag verwenden, um den Empfänger aufzufordern, eine Taste auf dem Telefon zu drücken. Mit den Attributen min, max und wait können Sie die Anzahl der erwarteten Ziffern, die maximale Anzahl der Ziffern und die Wartezeit in Millisekunden festlegen. Mit dem Attribut invalid können Sie eine benutzerdefinierte Nachricht für eine ungültige Eingabe festlegen. Mit dem Attribut exit können Sie eine benutzerdefinierte Nachricht für das Beenden der Eingabe festlegen. Über das Attribute callback wird die URL für den Webhook festgelegt, an die die DTMF-Eingabe als JSON Payload übermittelt wird. Über das Attribut allowed_digits können Sie die erlaubten Ziffern als regulären Ausdruck festlegen.

Beispiel

<voice name = "de-de-female">
  Hallo, Sie werden nun aufgefordert, zwei Zahlen einzugeben.
  <dtmf 
    callback="https://ihre-url.de/dtmf-callback" 
    allowed_digits="^[0-9#*]+"
    min="3" 
    max="4" 
    wait="5000" 
    invalid="Ungültige Eingabe. Bitte versuchen sie es noch einmal." 
    exit="Danke! Auf Wiederhören">
    Bitte geben Sie zwei Zahlen an.
  </dtmf>
</voice>

Sobald eine gültige Eingabe erfolgt, wird der Webhook mit folgenden Daten an die angegebene URL gesendet, wobei digits die eingegebene Ziffernfolge ist:

{
  "webhook_event": "dtmf",
  "webhook_timestamp": "2024-11-05T10:23:04+01:00",
  "data": {
    "id": "1732712",
    "callerId": "4943130149270",
    "recipient": "49176123456789",
    "foreign_id": "MyForeignId",
    "voice_name": "de-DE-KatjaNeural",
    "digits": "65"
  }
}

Antwort des Webhooks

Sie können nun über die Antwort des Webhooks den weiteren Ablauf des Anrufs steuern und so eine kaskadierte Anrufsteuerung realisieren. Lassen Sie den Webhook beispielsweise eine weitere Ansage abspielen oder den Anruf beenden. Geben Sie dazu einfach die nächste Ansage oder den Befehl zum Beenden des Anrufs als JSON zurück.

Beispielantworten

Beenden Sie den Anruf:

{
  hangup: true
}

Leiten Sie den Anruf weiter:

{
  bridge: "+49431123456789"
}

Spielen Sie eine weitere Ansage ab. Hier können Sie auch wieder beliebiges SSML verwenden:

{
  text: "<voice name=\"de-de-female\">Danke für Ihre Eingabe. Auf Wiederhören.</voice>"
}

Wenn Sie keine oder keine gültige Antwort senden, wird der Anruf automatisch beendet.

Status des Anrufs

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