Anrufbenachrichtigungen

Während eines Anrufs werden Informationen zu sechs verschiedenen Zeitpunkten an die angegebene URL gesendet – für eingehende, interne und ausgehende Anrufe: Created, Ringing, Answered, Warm transfer, Cold transfer und Hang-up. Benachrichtigungen werden bei verschiedenen wichtigen Ereignissen während eines Anrufs an die angegebene URL gesendet. Die Benachrichtigungen werden als POST-Anfrage mit den Daten in einem JSON-Dokument übermittelt. Weiter unten kannst Du nachlesen, welche Informationen genau gesendet werden.

Created

Ein created-Ereignis wird ausgelöst, wenn ein eingehender Anruf initiiert wird.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung des Anrufs.
• timestamp: Datum und Uhrzeit, zu der der Webhook generiert wird, im ISO-8601-Format.
• status: Der Status des Anrufs. Für diesen Benachrichtigungstyp ist es created.
• version: Ein Versionsattribut, das in Zukunft zur Migration auf eine andere Version der Webhooks verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Das created-Ereignis wird nur für eingehende Anrufe gesendet.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Diese Information wird beim created-Ereignis nicht mitgesendet.
• user_numbers: Diese Information wird beim created-Ereignis nicht mitgesendet.
• user_emails: Diese Information wird beim created-Ereignis nicht mitgesendet.
• destination: Informationen darüber, wohin der Anruf geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.

Ringing

Eine ringing-Benachrichtigung wird gesendet, wenn Telefone aufgrund eines eingehenden Anrufs zu klingeln beginnen.

Es ist möglich, dass mehrere ringing-Benachrichtigungen nacheinander gesendet werden, wenn neue Geräte zu klingeln beginnen.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung des Anrufs.
• timestamp: Datum und Uhrzeit, zu der der Webhook generiert wird, im ISO-8601-Format.
• status: Der Status des Anrufs. Für diesen Benachrichtigungstyp ist es ringing.
• version: Ein Versionsattribut, das in Zukunft zur Migration auf eine andere Version der Webhooks verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Anrufe zwischen Kollegen werden als outbound markiert.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Diese Information wird beim ringing-Ereignis nicht mitgesendet.
• user_numbers: Diese Information wird beim ringing-Ereignis nicht mitgesendet.
• user_emails: Diese Information wird beim ringing-Ereignis nicht mitgesendet.
• destination: Informationen darüber, wohin der Anruf geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.
• targets: Die Telefone, die für diesen Anruf klingeln. Telefone, die nicht erreichbar sind, werden nicht angezeigt.
• number: Die Nummer, die angerufen wird. Diese ist normalerweise identisch mit destination.number, kann sich aber ändern, wenn der Anruf weitergeleitet wird.
• name: Der Name der Person, die angerufen wird. Bei eingehenden Anrufen ist dies fast immer null.
• account_number: Die internen Nummern der User, die ihren VoIP Account auf erreichbar gestellt haben (sofern verfügbar, kann ein leeres Array sein).
• user_numbers: Die internen Nummern der User, die erreichbar sind (sofern verfügbar, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.

Angenommen (läuft)

Eine in-progress-Benachrichtigung wird gesendet, wenn ein Anruf angenommen wird.

Hinweis! Das target, das den Anruf annimmt, ist nicht immer eines der Geräte, die ursprünglich geklingelt haben. Durch Anrufübernahme kann es vorkommen, dass der Anruf auf einem anderen Gerät angenommen wird.

• call_id: Eine eindeutige Zeichenfolge zur Identifikation des Anrufs.
• timestamp: Datum und Uhrzeit der Webhook-Generierung im ISO-8601-Format.
• status: Der Status des Anrufs. Für diesen Benachrichtigungstyp ist es in-progress.
• version: Ein Versionsattribut, das in Zukunft für die Migration zu einer anderen Webhook-Version verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Anrufe zwischen Kollegen werden als outbound markiert.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Die interne Nummer des VoIP Accounts (falls vorhanden, bei eingehenden Anrufen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• destination: Informationen darüber, wohin der Anruf geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.
• targets: Die Telefone, die für diesen Anruf klingeln. Nicht erreichbare Telefone werden nicht angezeigt.
• number: Die angerufene Nummer. Dies ist normalerweise identisch mit destination.number, kann sich aber ändern, wenn der Anruf weitergeleitet wird.
• name: Der Name der angerufenen Person. Bei eingehenden Anrufen ist dies fast immer null.
• account_number: Die internen Nummern der User, die ihren VoIP Account als erreichbar eingerichtet haben (falls vorhanden, kann ein leeres Array sein).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.

Warm Transfer

Eine warm-transfer-Benachrichtigung wird gesendet, wenn ein Anruf „warm" weitergeleitet wird. Bei einem Warm Transfer ruft der Weiterleitende zunächst den neuen Teilnehmer an, der neue Teilnehmer nimmt ab, spricht mit dem Weiterleitenden, und dann wird der Anruf weitergeleitet.

Der Anruf vom Weiterleitenden zum Dritten erzeugt ebenfalls ringing- und in-progress-Benachrichtigungen mit eigener call_id. Während einer Weiterleitung werden diese beiden Anrufe im Wesentlichen zu einem einzigen Anruf zusammengeführt. Die call_id eines der beiden Anrufe wird dann für den Anruf nach der Weiterleitung verwendet. Die andere call_id wird in der Weiterleitung als merged_id angegeben und dann verworfen.

• call_id: Eine eindeutige Zeichenfolge zur Identifikation des Anrufs, übernommen von einem der vorherigen Anrufe.
• merged_id: Die call_id des anderen vorherigen Anrufs, die nicht mehr verwendet wird.
• timestamp: Datum und Uhrzeit der Webhook-Generierung im ISO-8601-Format.
• status: Der Status des Anrufs. Für diesen Benachrichtigungstyp ist es transfer.
• version: Ein Versionsattribut, das in Zukunft für die Migration zu einer anderen Webhook-Version verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Anrufe zwischen Kollegen werden als outbound markiert.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Die interne Nummer des VoIP Accounts (falls vorhanden, bei eingehenden Anrufen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• destination: Informationen darüber, wohin der Anruf geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.
• targets: Die Telefone, die für diesen Anruf klingeln. Nicht erreichbare Telefone werden nicht angezeigt.
• number: Die angerufene Nummer. Dies ist normalerweise identisch mit destination.number, kann sich aber ändern, wenn der Anruf weitergeleitet wird.
• name: Der Name der angerufenen Person. Bei eingehenden Anrufen ist dies fast immer null.
• account_number: Die internen Nummern der User, die ihren VoIP Account als erreichbar eingerichtet haben (falls vorhanden, kann ein leeres Array sein).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• redirector: Informationen über den Teilnehmer, der die Weiterleitung durchgeführt hat.
• number: Die Telefonnummer, die der Weiterleitende verwendet.
• name: Der Name des Weiterleitenden.
• account_number: Die interne Nummer des VoIP Accounts (falls vorhanden, bei eingehenden Anrufen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.

Cold Transfer

Eine cold-transfer-Benachrichtigung wird gesendet, wenn ein Anruf per Cold Transfer weitergeleitet wird. Bei einem Cold Transfer ruft die weitergebende Person den neuen Teilnehmer an, leitet das Gespräch jedoch weiter, ohne abzuwarten, ob oder wer abnimmt.

Es gibt zwei wesentliche Unterschiede zwischen einem cold-transfer und einem warm-transfer:

• Bei einem Warm Transfer gibt es immer einen angerufenen Teilnehmer, während es bei einem Cold Transfer mehrere sein können (z. B. wenn das Gespräch an eine Anrufgruppe weitergeleitet wird).
• Bei einem Warm Transfer werden zuerst ringing- und in-progress-Benachrichtigungen generiert. Bei einem Cold Transfer wird nur eine ringing-Benachrichtigung gesendet, und eine in-progress-Benachrichtigung folgt nur, wenn der dritte Teilnehmer das Gespräch annimmt.

Das Gespräch der weitergebenden Person zum dritten Teilnehmer erzeugt ebenfalls eine ringing-Benachrichtigung mit einer eigenen call_id. Während einer Weiterleitung werden diese beiden Gespräche im Wesentlichen zu einem einzigen Gespräch zusammengeführt. Die call_id eines der beiden Gespräche wird dann für das Gespräch nach der Weiterleitung verwendet. Die andere call_id wird in der Weiterleitung als merged_id angegeben und anschließend verworfen.

• call_id: Ein eindeutiger String zur Identifizierung des Gesprächs, übernommen von einem der vorherigen Gespräche.
• merged_id: Die call_id des anderen vorherigen Gesprächs, die nicht mehr verwendet wird.
• timestamp: Datum und Uhrzeit der Webhook-Generierung im ISO-8601-Format.
• status: Der Status des Gesprächs. Für diesen Benachrichtigungstyp ist es transfer.
• version: Ein Versionsattribut, das in Zukunft für die Migration auf eine andere Webhook-Version verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend oder ausgehend ist. Aktuell werden nur eingehende Anrufe unterstützt, daher ist dieser Wert immer inbound.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Die interne Nummer des VoIP Accounts (falls verfügbar, bei eingehenden Gesprächen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls verfügbar, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• destination: Informationen darüber, wohin das Gespräch geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.
• targets: Die Telefone, die für dieses Gespräch klingeln. Telefone, die nicht erreichbar sind, werden nicht angezeigt.
• number: Die Nummer, die angerufen wird. Diese ist normalerweise identisch mit destination.number, kann sich aber ändern, wenn das Gespräch weitergeleitet wird.
• name: Der Name der angerufenen Person. Bei eingehenden Gesprächen ist dies fast immer null.
• account_number: Die internen Nummern der User, die ihren VoIP Account so eingerichtet haben, dass sie erreichbar sind (falls verfügbar, kann ein leeres Array sein).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls verfügbar, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• redirector: Informationen über den Teilnehmer, der die Weiterleitung durchgeführt hat.
• number: Die Telefonnummer, die der Weiterleitende verwendet.
• name: Der Name des Weiterleitenden.
• account_number: Die interne Nummer des VoIP Accounts (falls verfügbar, bei eingehenden Gesprächen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (falls verfügbar, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.

Auflegen (ended)

Eine ended-Benachrichtigung wird gesendet, wenn ein Gespräch beendet wird. Es gibt mehrere Gründe, warum ein Gespräch enden kann.

Eine ended-Benachrichtigung kann nach einer in-progress-Benachrichtigung gesendet werden, wenn das Gespräch von einem der Teilnehmer beendet wurde, nach einer ringing-Benachrichtigung, wenn niemand abgenommen hat, oder als einzige Benachrichtigung, wenn keine Geräte erreichbar waren.

• call_id: Ein eindeutiger String zur Identifizierung des Gesprächs.
• timestamp: Datum und Uhrzeit der Webhook-Generierung im ISO-8601-Format.
• status: Der Status des Gesprächs. Für diesen Benachrichtigungstyp ist es ended.
• reason: Der Grund, warum das Gespräch beendet wurde. Der Grund kann einer der folgenden Werte sein:
1. completed: Das Gespräch wurde erfolgreich abgeschlossen.
2. busy: Der Anruf wurde abgelehnt, der Angerufene war besetzt.
3. no-answer: Niemand hat das Gespräch aus verschiedenen Gründen angenommen.
4. failed: Es ist ein Fehler aufgetreten, der den Aufbau des Gesprächs verhindert hat.
5. cancelled: Der Anrufer hat aufgelegt, bevor jemand abnehmen konnte.
6. abandon: Der Anrufer hat während des Wartens in der Warteschleife aufgelegt.
• version: Ein Versionsattribut, das in Zukunft für die Migration auf eine andere Webhook-Version verwendet werden kann. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Gespräche zwischen Kollegen werden als outbound markiert.
• caller: Informationen über den Anrufer.
• number: Die Telefonnummer, die der Anrufer verwendet.
• name: Der Name des Anrufers.
• account_number: Die interne Nummer des VoIP Accounts (soweit vorhanden, bei eingehenden Anrufen ist dies fast immer null).
• user_numbers: Die internen Nummern der User, die erreichbar sind (soweit vorhanden, kann ein leeres Array sein).
• user_emails: Die E-Mail-Adressen der User.
• destination: Informationen darüber, wohin der Anruf geleitet wird.
• number: Die Telefonnummer, die der Anrufer gewählt hat.

Transkription erstellt

Eine call_transcription-Benachrichtigung wird gesendet, sobald die Transkription fertig ist.

Falls Voys Intelligence aktiviert ist. Das ist das erste Event, das auf eine ended-Benachrichtigung folgt. Falls Gesprächszusammenfassungen aktiviert sind, folgt das summary-Event in Kürze.

{            
  "call_id": "ua0-grq-prd-1780997460.58680",
  "call_transcription": "Speaker 1: Hi how are you.\nSpeaker 2: Hey great that you called.",        
}

Zusammenfassung erstellt

Eine summary-Benachrichtigung wird gesendet, sobald die Gesprächszusammenfassung fertig ist.

Falls Voys Intelligence aktiviert ist. Das ist das letzte Event für einen bestimmten Anruf.

{
  "call_id": "ua0-grq-prd-1780997460.58680", 
  "summary": "This was a great call."
}

Gesprächsaufnahme erstellt

Ein call recording created-Event wird gesendet, sobald eine Aufnahme des Gesprächs verfügbar ist.

Der Inhalt des Events sieht so aus:

{
"call_id": "ua0-grq-prd-1741083170.160935",
"recording_url": "https://api.voys.nl/api/v2/clients/9f515223-c139-4704-a031-57342c8809a4/callrecordings/ua0-grq-prd-1741083170.160935/audio"
}

Du kannst recording_url direkt nutzen, um die Aufnahme mit Deinem API-Key abzurufen. Du musst die URL nicht selbst zusammenbauen oder Deine Kunden-ID nachschlagen.

• Gehe zu Anrufbenachrichtigungen.
• Klicke auf Hinzufügen.
• Gib eine Beschreibung im Feld Beschreibung ein, um den Zweck der Benachrichtigung festzulegen.
• Wähle „Custom" aus den Paket-Optionen, es sei denn, Du möchtest eine Standardoption nutzen.
• Trage die URL ein, an die die Gesprächsbenachrichtigungen gesendet werden sollen.
• Trage das API-Token ein, falls Dein gewähltes Paket eines bereitstellt.

Hinweis: Dies ist nur erforderlich, wenn Dein Paket ein API-Token ausgibt.

• Klicke auf Speichern.