Anruf HTTP GET Schnittstelle V2

📞 Anruf-API – Version 2

Die Anruf-API dient dazu, Anrufe per Webhook in die CRM-Infrastruktur infra-struktur einzutragen und zu aktualisieren. Die Schnittstelle kann per HTTP GET oder POST aufgerufen werden – GET hat Vorrang.

1. Anruf eintragen

Endpoint: http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/index.php

Pflichtparameter

Parameter	Beschreibung
isdnKey	Der ISDN-Key
location	Name eines in der Anrufliste konfigurierten Standortes
msn	Name einer in der Anrufliste konfigurierten eingehenden Rufnummer/Nebenstelle
number	Rufnummer des Anrufers (muss URL-encodiert werden, z. B. +492941247790 → %2B492941247790)

Optionale Parameter

Parameter	Beschreibung
reason	Base64-codierter Grund des Anrufs
fileSource	Base64-codierter Inhalt einer Datei
fileType	Dateityp (Standard: fax)
mimeType	MIME-Type (Standard: application/download)
timestamp	Unix-Timestamp (Standard: Zeitpunkt des Aufrufs)
direction	"in" oder "out" (Standard: in)
duration	Dauer in Minuten eines Anrufs.
externalId	Eine eigene ID des Telefonsystems über den ich später mit dem update Aufruf einen Eintrag exakt diesem Eintrag zuordnen kann.

Rückgabe/Response

Parameter	Beschreibung
Done XYZ	Der Wert "Done" zeigt den erfolgreichen Eintrag an gefolgt von der vom System vergebenen ID. Über die kann der Anruf später weiter aktualisiert werden.

2. Anruf aktualisieren

Endpoint: http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/update.php

Pflichtparameter

Parameter	Beschreibung
isdnKey	Der ISDN-Key
number	Rufnummer des zu aktualisierenden Anrufs (muss URL-encodiert werden) (Wird nicht gebraucht wenn eine externalId übergeben wird.)

Mit der Rufnummer wird nach Anrufen in den letzten 60 Minuten mit der gleichen Rufnummer gesucht und der Anruf wird dann für den Grund verwendet.

Optionale Parameter

Parameter	Beschreibung
AnrufID	ID des Anrufs (hat Vorrang vor number)
externalId	wurde beim initialen Eintrag des Anrufs eine externalId übergeben kann das update damit genau auf den Eintrag gemünzt werden.
reason	Grund (Base64 oder Klartext, bei GET zusätzlich URL-encodiert)
reasonAppend	Ergänzung zum Grund (Base64 oder Klartext, bei GET zusätzlich URL-encodiert)
acceptedBy	Benutzerkürzel für „angenommen durch“
callFor	Benutzerkürzel für „Anruf für“
recall	Angabe, ob ein Rückruf gewünscht ist als "ja" oder "nein"

3. Sonderfall: OpenAI Whisper Integration 🎙️

Jede infra-struktur-Instanz verfügt über einen lokalen Whisper-Server, der Audiodateien automatisch transkribiert. Die Transkription wird im Anruf gespeichert, die Originaldatei bleibt zusätzlich im Anruf per Mediaplayer abspielbar.

Parameter

Parameter	Beschreibung
fileSourceRaw	Audiodatei im Binary-Format (nur via POST möglich, wegen Größe und Format)

3.1 Gesprächszusammenfassung mit getrennten Audiostreams

Alternativ zu einer einzelnen Audiodatei können der eingehende und der ausgehende Audiostream eines Gesprächs getrennt übertragen werden.

Die beiden Audiodateien werden dem über die externalId identifizierten Anruf zugeordnet und zur automatischen Transkription und Erstellung einer Anrufzusammenfassung verarbeitet.

Der Aufruf ist aufgrund der binären Audiodateien ausschließlich per HTTP POST mit multipart/form-data möglich.

Parameter

Parameter	Beschreibung
externalId	Eindeutige ID des Gesprächs aus dem Telefonsystem. Die ID muss bereits beim initialen Eintragen des Anrufs übergeben worden sein und ordnet die Audiodateien exakt dem zugehörigen Anruf zu.
ownerInitial	Benutzerkürzel des internen Benutzers, der das Gespräch geführt hat, beispielsweise CT.
fileSourceOut	Binäre Audiodatei mit dem ausgehenden Audiostream des Gesprächs. Die Datei muss als Datei-Upload per multipart/form-data übertragen werden.
fileSourceIn	Binäre Audiodatei mit dem eingehenden Audiostream des Gesprächs. Die Datei muss als Datei-Upload per multipart/form-data übertragen werden.

Die Parameter fileSourceOut und fileSourceIn ermöglichen eine getrennte Verarbeitung beider Gesprächsseiten. Dadurch kann der interne Benutzer über ownerInitial dem Gespräch zugeordnet und eine automatische Zusammenfassung des Telefonats erzeugt werden.

Mindestens die zur eindeutigen Zuordnung benötigten Parameter isdnKey und externalId müssen übergeben werden.

4. Fehlercodes

4.1 Fehlende Parameter

Code	Beschreibung
1001	isdnKey fehlt
1002	location fehlt
1003	msn fehlt
1004	number fehlt

4.2 Datenbankverbindung

Code	Beschreibung
2001	host fehlt
2002	username fehlt
2003	password fehlt
2004	database fehlt
3001	Verbindungsfehler (MySQLi)

4.3 Datenbankabfragen

Fehler bei einzelnen Abfragen, z. B.:

• 3102 – kein Standort mit dem Namen gefunden
• 3105 – MSN ist keine Fax-MSN
• 3113 – Fehler beim Einfügen eines Anrufs in die Calllist
• 3115 – Fehler beim Setzen eines Grundes

(Alle Fehler mit MySQLi-Fehlernummer und Fehlermeldung.)

4.4 API-Fehler

Code	Beschreibung
4001	Ungültiger ISDN-Key
4002	ISDN-Key wurde noch nicht validiert
4101	Rufnummer zu kurz
4102	Rufnummer ist ein „Hidden Signal“
4103	Anruf liegt innerhalb der Signaltoleranz
4104	Keine passende Anrufliste für MSN & Standort gefunden

5. Beispiele

5.1 POST-Beispiel: Audiodatei hochladen & transkribieren (Whisper)

curl -X POST "http://[instance]-classic.infra-struktur.eu/api/calllist/update.php" \
  -F "isdnKey=DEIN_ISDN_KEY" \
  -F "number=%2B492941247790" \
  -F "fileSourceRaw=@anruf.mp3;type=audio/mpeg"

Ergebnis:

• Die Datei anruf.mp3 wird an den Anruf angehängt.
• Der Whisper-Server erzeugt eine Transkription und speichert sie im Anruf.
• Die Originaldatei ist zusätzlich im CRM über einen Mediaplayer abspielbar.

5.2 POST-Beispiel: Audiodatei mit zusätzlichen Parametern

curl -X POST "http://[instance]-classic.infra-struktur.eu/api/calllist/update.php" \
  -F "isdnKey=DEIN_ISDN_KEY" \
  -F "number=%2B492941247790" \
  -F "reason=Kundenrückruf" \
  -F "acceptedBy=AB" \
  -F "fileSourceRaw=@anruf.mp3;type=audio/mpeg"

Hier wird neben der Audiodatei zusätzlich ein Anrufgrund gesetzt (reason) und ein Bearbeiter eingetragen (acceptedBy).

5.3 GET-Beispiel: Text-Update ohne Datei

curl "http://[instance]-classic.infra-struktur.eu/api/calllist/update.php?isdnKey=DEIN_ISDN_KEY&number=%2B492941247790&reason=Rückruf+gewünscht&acceptedBy=AB"

Ergebnis:

• Der Anruf mit der Nummer +492941247790 wird aktualisiert.
• Als Grund wird Rückruf gewünscht gespeichert.
• Der Anruf wird als angenommen durch Benutzer AB markiert.

5.4 POST-Beispiel: Getrennte Audiostreams hochladen und Anruf zusammenfassen

curl -X POST "https://netzkultur-classic.infra-struktur.com/api/calllist/update.php" \
 -H "Content-Type: multipart/form-data" \
 -F "isdnKey=247790" \
 -F "ownerInitial=CT" \
 -F "externalId=21cf1ada-a93c-4436-b3c9-eb404c1b954c" \
 -F "fileSourceOut=@/var/starface/module/instances/repo/5dd8302c-eb41-4a3d-8479-29755315f960/var/files/monitor/21cf1ada-a93c-4436-b3c9-eb404c1b954c_00492941272630_0049532134070-in.wav" \
 -F "fileSourceIn=@/var/starface/module/instances/repo/5dd8302c-eb41-4a3d-8479-29755315f960/var/files/monitor/21cf1ada-a93c-4436-b3c9-eb404c1b954c_00492941272630_0049532134070-out.wav"

Bedeutung der Parameter:

Parameter	Beispielwert	Bedeutung
isdnKey	247790	ISDN-Key der infra-struktur-Instanz
ownerInitial	CT	Kürzel des internen Benutzers, der das Gespräch geführt hat
externalId	21cf1ada-a93c-4436-b3c9-eb404c1b954c	Eindeutige Gesprächs-ID des Telefonsystems
fileSourceOut	@/pfad/zum/audiostream.wav	Ausgehender Audiostream als binärer Datei-Upload
fileSourceIn	@/pfad/zum/audiostream.wav	Eingehender Audiostream als binärer Datei-Upload

Ergebnis:

• Der über externalId identifizierte Anruf wird aktualisiert.
• Der eingehende und der ausgehende Audiostream werden dem Anruf zugeordnet.
• Das Benutzerkürzel aus ownerInitial kennzeichnet den internen Gesprächsteilnehmer.
• Die Audiostreams werden automatisch verarbeitet.
• Im Anruf wird eine automatische Transkription beziehungsweise Anrufzusammenfassung gespeichert.
• Die zugehörigen Audiodateien bleiben beim Anruf verfügbar.

Hinweis: Die Zuordnung von fileSourceOut und fileSourceIn richtet sich nach der Perspektive beziehungsweise Exportlogik des angebundenen Telefonsystems. Bei der STARFACE-Integration kann die Bezeichnung innerhalb des Dateinamens von der Bezeichnung des API-Parameters abweichen. Maßgeblich ist daher die im Integrationsmodul konfigurierte Zuordnung.