Zammad Hub

Deutsch

English
српски

Deutsch

English
српски

Appearance

Allgemeine CTI ​

Einführung ​

Auf dieser Seite werden die allgemeinen CTI-API-Bereiche und -Funktionen beschrieben.

WARNING

  • Die Authentifizierung an diesem Endpunkt funktioniert grundlegend anders als der Rest der API.
  • API-Clients arbeiten nicht mit den CTI-Endpunkten, es sei denn, dies wird ausdrücklich vom Client-Anbieter angegeben!
  • Die CTI-Endpunkte sind nur für PBX-Systeme relevant.

Features ​

Hier ist eine kleine, komprimierte Liste der Möglichkeiten, die diese CTI API bietet.

Eingehend ​

  • Anruferprotokollfunktionen für Ihre Agenten.
  • Blockieren von Caller IDs während der Anruf-Signalisierung.

Ausgehend ​

  • Anruferprotokollfunktionen für Ihre Agenten.
  • Stellen Sie ausgehende Caller IDs je nach Ziel der Caller ID ein.

Endpunkt ​

Der Endpunkt ist in der generischen CTI-Integration zu finden und enthält ein eindeutiges Token, das zur Authentifizierung dient. Achten Sie darauf, dass Sie die URL dieses Endpunkts sicher aufbewahren.

INFO

Die generische CTI-Konfiguration und den richtigen Endpunkt finden Sie in Ihrem Zammad in der Verwaltungsoberfläche unter System > Integrationen > CTI (generic).

Bitte beachten Sie auch die dort aufgeführten Anforderungen und Einschränkungen. Alle Optionen, die Rückgaben erfordern (z.B. Blockieren, Manipulation von ausgehenden Anrufer IDs) sind abhängig von Konfigurationen innerhalb der Zammad CTI Integration Seite.

TIP

Es gibt zwei Möglichkeiten, wie man die relevanten Daten an Zammad "posten" (POST) kann:

  • JSON (empfohlen)
  • Form-Daten

Ereignisse ​

Es gibt mehrere Ereignisse im Zusammenhang mit einem laufenden Anruf. Diese Aktionen kommen immer von Ihrem PBX-System und können sein:

  • Ereignis "newCall" (Einleitung eines Anrufs)
  • Ereignis "hangup" (Beendigung des Anrufs)
  • Ereignis "answer" (d.h. Annehmen des Gesprächs)

In einigen Situationen kann Zammad eine Rückmeldung an Ihre PBX-Anlage geben (z.B. eine Ablehnung), wenn Sie einen bestimmten Anrufer blockiert haben. Zammad wird jedoch niemals eine Aktion an Ihrer Telefonanlage initiieren. Zammad ist in allen beschriebenen Fällen eine passive Komponente.

Verwendete Beispiele ​

Beispiel: Die nachstehenden Anrufe wurden mit der folgenden Konfiguration gesendet. Dies ist wichtig für Sie, um die hier gezeigten Antworten zu verstehen.

Ausgehend:

  • Ziel-ID Anrufer 4989* setzt für ausgehende Anrufer ID 498999998145 den Hinweis "Alle aus München"
  • Ziel-ID Anrufer 4930* setzt für ausgehende Anrufer ID 493023125877 den Hinweis "Alle aus Berlin"

Andere Einstellungen:

  • Standard-Anrufer-ID für ausgehende Anrufe 496990009111

Neues Anrufereignis ​

Allgemein ​

Verfügbare Attribute und Beispiel-Daten:

event newCall
Zammad mitteilen, dass es einen neuen Anruf gibt.
from 4930555716000
Nummer, von der der Anruf ausgeht. Kann auch anonymous sein.
to 4930555716000
Nummer, die aufgerufen wird.
direction in
Die Richtung des Anrufs. Wenn Ihr Agent einen Anruf initiiert, ist dies out. Anrufe von externer Seite an Sie sind in.
callId 53ba82e2bd6d12d9fb2d3838f0cfb070
Eine ID, die für den Anruf eindeutig ist. Zammad verwendet diese ID zur Identifizierung eines bestehenden Anrufs mit folgenden Aktionen (z.B. Annehmen oder Auflegen).
user John Doe
Der echte Name des/der beteiligten Benutzer(s). Sie müssen die Parameter möglicherweise im Array-Stil ([]) angeben, abhängig von der von Ihnen gewählten Aufrufmethode. Wenn die Richtung out ist, ist dies der Name der anrufenden Person(en). Wenn die Richtung in ist, ist dies der Name der angerufenen Person(en).
queue support
Ein optionaler Name der Warteschlange; diese Option ist für den Anruferprotokollfilter relevant. Dieser Wert ist optional.

Ausgehend ​

Show examples

POST-Request gesendet: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json
{
  "event": "newCall",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
  "user": "Lauren Brooks"
}

Response:

json
{
  "action": "dial",
  "caller_id": "496990009111",
  "number": "492214710334"
}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "event": "newCall",
    "from": "493023125741",
    "to": "492214710334",
    "direction": "out",
    "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
    "user": "Lauren Brooks"
  }'

Eingehend ​

Show examples

Payload:

json
{
  "event": "newCall",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
  "user": [
    "Lauren Brooks",
    "Ethan Kwan"
  ]
}

Response:

json
{}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "newCall",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "user": ["Lauren Brooks", "Ethan Kwan"]
  }'

Situationsbezogene Antworten ​

Je nach gewählter Rufrichtung gibt Zammad entweder eine (optional) konfigurierte Call ID zurück oder blockiert einen Anrufer (optional) . Wenn Ihr Zammad eine oder beide Optionen nicht konfiguriert hat, ist der Rückgabewert leer.

INFO

Dies muss von Ihrer Telefonanlage unterstützt werden, damit es funktioniert.

Ablehnen blockierter Anrufer IDs ​

Wenn ein eingehender neuer Anruf mit einer zu blockierenden Nummer übereinstimmt, gibt Zammad folgendes zurück.

json
{
  "action": "reject",
  "reason": "busy"
}

Wenn keine der zu blockierenden Nummern übereinstimmen, gibt Zammad folgendes zurück.

json
{}

WARNING

Ihre Telefonanlage muss den Anruf noch beenden (hangup-Ereignis). Andernfalls wird der Anruf nicht nur in der Anruferliste von Zammad erscheinen, sondern auch als klingelnder Anruf.

Festlegen einer bestimmten ID für ausgehende Anrufe ​

Falls Ihre Instanz eine passende, überschreibende Caller ID konfiguriert hat, wird Zammad folgende Payload zurückgeben.

json
{
  "action": "dial",
  "callerId": "493055571642",
  "number": "491711234567890"
}

Wenn keine Übereinstimmung beim Überschreiben gefunden wird oder Sie nichts konfiguriert haben, gibt Zammad Folgendes zurück.

json
{}

Anrufannahme-Ereignis ​

Allgemein ​

Verfügbare Attribute und Beispiel-Daten:

event answer:
Sagt Zammad, dass jemand den Anruf entgegengenommen hat.
from 493055571600:
Nummer, von der der Anruf ausgeht.
to 493055571600:
Nummer, die angerufen wird.
direction in:
Die Richtung des Anrufs - wenn Ihr Agent einen Anruf initiiert, ist dies out.
callId 53ba82e2bd6d12d9fb2d3838f0cfb070
Eine ID, die für den Anruf eindeutig ist. Zammad verwendet diese ID zur Identifizierung eines bestehenden Anrufs mit folgenden Aktionen (z.B. Annehmen oder Auflegen).
answeringNumber 493055571600:
Zammad sucht nach einem Benutzer mit dem angegebenen Wert; die folgenden Attribute werden in der angegebenen Reihenfolge ausgewertet: - user.phone - user.login - user.if Dieser Wert ist optional.
user John Doe:
Der echte Name des/der betreffenden Benutzer(s). Sie müssen die Parameter eventuell im Array-Stil ([]) angeben, abhängig von der von Ihnen gewählten Aufrufmethode. Wenn die Richtung out ist, ist dies der Name der anrufenden Person(en). Wenn die Richtung in ist, ist dies der Name der angerufenen Person(en). Dieser Wert ist optional.

Es gibt zwei Möglichkeiten, wie Sie die relevanten Daten an Zammad "posten" (POST) können.

Ausgehend ​

Show examples

POST-Request gesendet: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json
{
  "event": "answer",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
  "caller": "Lauren Brooks"
}

Response:

json
{}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "answer",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "out",
     "callId": "9f1840cb-8be9-4d3a-8200-3da2937085f0",
     "caller": "Lauren Brooks"
  }'

Eingehend ​

Show examples

Payload:

json
{
  "event": "answer",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
  "answeringNumber": "emily@fastlane.inc",
  "caller": [
    "Lauren Brooks",
    "Emily Tran"
  ]
}

Response:

json
{}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "answer",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "answeringNumber": "emily@fastlane.inc",
     "caller": ["Lauren Brooks", "Emily Tran"]
  }'

Beenden eines Anrufs ​

Allgemein ​

event hangup:
Teilt Zammad mit, dass jemand den Anruf entgegengenommen hat.
from 493055571600:
Nummer, von der der Anruf ausgeht.
to 493055571600:
Nummer, die angerufen wird.
direction in:
Die Richtung des Anrufs - wenn Ihr Agent einen Anruf initiiert, ist dies out.
callId 53ba82e2bd6d12d9fb2d3838f0cfb070
Eine ID, die für den Anruf eindeutig ist. Zammad verwendet diese ID zur Identifizierung eines bestehenden Anrufs mit folgenden Aktionen (z.B. Annehmen oder Auflegen).
cause
Hier wird der Grund für die Beendigung angegeben. Zammad wertet den Grund aus und zeigt z.B. verpasste Anrufe entsprechend im Anruferprotokoll an. Mögliche Werte sind:
  • normalClearing (eine der Parteien hat aufgelegt, nachdem das Gespräch zustande gekommen ist)
  • busy (der angerufene Teilnehmer war besetzt)
  • cancel (der Anrufer hat aufgelegt, bevor der angerufene Teilnehmer abgenommen hat)
  • noAnswer (der angerufene Teilnehmer hat den Anruf abgelehnt, z.B. durch eine DND-Einstellung)
  • congestion (der angerufene Teilnehmer konnte nicht erreicht werden)
  • notFound (die angerufene Nummer existiert nicht oder der angerufene Teilnehmer ist offline)
  • forwarded (der Anruf wurde an einen anderen Teilnehmer weitergeleitet)
answeringNumber 493055571600:
Zammad sucht nach einem Benutzer mit einem entsprechenden Wert. Die folgenden Attribute werden in der angegebenen Reihenfolge ausgewertet:
  • user.phone
  • user.login
  • user.if Dieser Wert ist optional.

Ausgehend ​

Show examples

POST-Request gesendet: https://{FQDN-Zammad}/api/v1/cti/{instance specific token}

Payload:

json
{
  "event": "hangup",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "out",
  "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
  "cause": "cancel"
}

Response:

json
{}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "hangup",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "out",
     "callId": "f4ebd2be-7b9a-4d58-94c2-eb06a3c2ce76",
     "cause": "cancel"
  }'

Eingehend ​

Show examples

Payload:

json
{
  "event": "hangup",
  "from": "493023125741",
  "to": "492214710334",
  "direction": "in",
  "callId": "2d77882f-68df-40f0-8c62-b642589c00bc",
  "answeringNumber": "emily@fastlane.inc",
  "cause": "normalClearing"
}

Response:

json
{}

Beispiel curl Befehl:

sh
curl --request POST 'https://{FQDN-Zammad}/api/v1/cti/{instance specific token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
     "event": "hangup",
     "from": "493023125741",
     "to": "492214710334",
     "direction": "in",
     "callId": "307fa962-de8d-4ffc-817b-7f6993204159",
     "answeringNumber": "emily@fastlane.inc",
     "cause": "normalClearing"
  }'