Anrufbenachrichtigungen

Während eines Anrufs werden Informationen zu sechs verschiedenen Zeitpunkten an die angegebene URL gesendet – bei eingehenden, internen und ausgehenden Gesprächen: Erstellt, Klingelt, Angenommen, Warme Weiterleitung, Kalte Weiterleitung und Aufgelegt. 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 versendet. Weiter unten kannst du nachlesen, welche Informationen genau gesendet werden.

Erstellt

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

• call_id: Eine eindeutige Zeichenkette zur Identifikation des Anrufs.
• timestamp: Datum und Uhrzeit, wann der Webhook generiert wird, im ISO-8601-Format.
• status: Der Status des Anrufs. Bei diesem Benachrichtigungstyp ist es created.
• version: Ein Versionsattribut, das in Zukunft verwendet werden kann, um auf eine andere Version der Webhooks zu migrieren. Aktuell ist es immer v2.
• direction: Ob ein Anruf eingehend (inbound) oder ausgehend (outbound) ist. Das created-Ereignis wird nur bei eingehenden Anrufen 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.

Klingelt

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 Zeichenkette zur Identifikation des Anrufs.
• timestamp: Datum und Uhrzeit, wann der Webhook generiert wird, im ISO-8601-Format.
• status: Der Status des Anrufs. Bei diesem Benachrichtigungstyp ist es ringing.
• version: Ein Versionsattribut, das in Zukunft verwendet werden kann, um auf eine andere Version der Webhooks zu migrieren. 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: 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 dieselbe wie 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 als erreichbar eingerichtet 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 (in Bearbeitung)

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. Aufgrund der Anrufübernahme kann es vorkommen, dass der Anruf auf einem anderen Gerät angenommen wird.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung 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 Version der Webhooks verwendet werden kann. Aktuell ist es immer v2.
• direction: Gibt an, 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 (sofern verfügbar, bei eingehenden Anrufen ist dies fast immer null).
• 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.
• 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 jedoch ä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 so eingerichtet haben, dass sie erreichbar sind (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.

Warme Weiterleitung

Eine warm-transfer-Benachrichtigung wird gesendet, wenn ein Anruf „warm" weitergeleitet wird. Bei einer warmen Weiterleitung ruft der Weiterleitende zuerst 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 Teilnehmer 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 einbezogen und anschließend verworfen.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung des Anrufs, die von einem der vorherigen Anrufe übernommen wurde.
• 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 Version der Webhooks verwendet werden kann. Aktuell ist es immer v2.
• direction: Gibt an, 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 (sofern verfügbar, bei eingehenden Anrufen ist dies fast immer null).
• 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.
• 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 jedoch ä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 so eingerichtet haben, dass sie erreichbar sind (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.
• 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 (sofern verfügbar, bei eingehenden Anrufen ist dies fast immer null).
• 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.

Kalte Vermittlung

Eine cold-transfer Benachrichtigung wird gesendet, wenn ein Gespräch kalt vermittelt wird. Bei einer kalten Vermittlung ruft der Vermittelnde den neuen Teilnehmer an, vermittelt das Gespräch jedoch weiter, ohne abzuwarten, ob oder wer abnimmt.

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

• Bei einer warmen Vermittlung gibt es immer einen Angerufenen, während bei einer kalten Vermittlung mehrere vorhanden sein können (z. B. wenn das Gespräch an eine Anrufgruppe weitergeleitet wird).
• Bei einer warmen Vermittlung werden zunächst ringing und in-progress Benachrichtigungen generiert. Bei einer kalten Vermittlung wird nur eine ringing Benachrichtigung gesendet, und eine in-progress Benachrichtigung folgt nur dann, wenn der Dritte den Anruf annimmt.

Der Anruf vom Vermittelnden zum Dritten erzeugt ebenfalls eine ringing Benachrichtigung mit einer eigenen call_id. Während einer Vermittlung 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 Vermittlung verwendet. Die andere call_id wird in der Vermittlung als merged_id angegeben und anschließend verworfen.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung des Gesprächs, die von einem der vorherigen Gespräche übernommen wird.
• merged_id: Die call_id des anderen vorherigen Gesprächs, die nicht mehr verwendet wird.
• timestamp: Das Datum und die Uhrzeit, zu der der Webhook generiert wird, im ISO 8601 Format.
• status: Der Status des Gesprächs. Bei diesem Benachrichtigungstyp ist es transfer.
• version: Ein Versionsattribut, das in Zukunft verwendet werden kann, um zu einer anderen Version der Webhooks zu migrieren. Derzeit ist es immer v2.
• direction: Ob ein Anruf eingehend oder ausgehend ist. Derzeit 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 Anrufen 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 diesen Anruf klingeln. Telefone, die nicht erreichbar sind, werden nicht angezeigt.
• number: Die Nummer, die angerufen wird. Diese ist normalerweise dieselbe wie destination.number, kann sich jedoch ä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 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 Vermittlung durchgeführt hat.
• number: Die Telefonnummer, die der Vermittelnde verwendet.
• name: Der Name des Vermittelnden.
• account_number: Die interne Nummer des VoIP Accounts (falls verfügbar, bei eingehenden Anrufen 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 (beendet)

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 geantwortet hat, oder als einzige Benachrichtigung, wenn keine Geräte erreichbar waren.

• call_id: Eine eindeutige Zeichenfolge zur Identifizierung des Gesprächs.
• timestamp: Das Datum und die Uhrzeit, zu der der Webhook generiert wird, im ISO 8601 Format.
• status: Der Status des Gesprächs. Bei diesem 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 den Anruf aus verschiedenen Gründen beantwortet.
4. failed: Ein Fehler ist aufgetreten, der verhindert hat, dass das Gespräch aufgebaut werden konnte.
5. cancelled: Der Anrufer hat aufgelegt, bevor jemand antworten konnte.
6. abandon: Der Anrufer hat aufgelegt, während er in der Warteschleife gewartet hat.
• version: Ein Versionsattribut, das in Zukunft verwendet werden kann, um zu einer anderen Version der Webhooks zu migrieren. Derzeit 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.

Transkription erstellt

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

Falls Voys Intelligence aktiviert ist. Dies ist das erste Event, das nach einer 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. Dies 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 verwenden, um die Aufnahme mit deinem API-Schlüssel abzurufen. Du musst die URL nicht selbst erstellen 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 Package-Optionen, es sei denn, du möchtest eine Standardoption verwenden.
• Gib die URL ein, an die die Gesprächsbenachrichtigungen gesendet werden sollen.
• Gib das API token ein, falls dein gewähltes Package eines bereitstellt.

Hinweis: Dies ist nur erforderlich, wenn dein Package ein API-Token bereitstellt.

• Klicke auf Speichern.