Anruf HTTP GET Schnittstelle V2: Unterschied zwischen den Versionen

Aus infra-struktur AdminWiki 2.10
Zur Navigation springenZur Suche springen
← Zum vorherigen Versionsunterschied
Keine Bearbeitungszusammenfassung
 
(23 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
'''Neue Anruflisten API'''
= 📞 Anruf-API – Version 2 =


Adresse: http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/index.php
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 ==


Übergabe per GET oder POST (GET hat Vorrang vor POST)
'''Endpoint:'''
<code>http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/index.php</code>


=== Pflichtparameter ===
{| class="wikitable"
! 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. <code>+492941247790</code> → <code>%2B492941247790</code>)
|}


Folgende Werte müssen übergeben werden:
=== Optionale Parameter ===
{| class="wikitable"
! Parameter
! Beschreibung
|-
| reason
| Base64-codierter Grund des Anrufs
|-
| fileSource
| Base64-codierter Inhalt einer Datei
|-
| fileType
| Dateityp (Standard: <code>fax</code>)
|-
| mimeType
| MIME-Type (Standard: <code>application/download</code>)
|-
| timestamp
| Unix-Timestamp (Standard: Zeitpunkt des Aufrufs)
|-
| direction
| <code>"in"</code> oder <code>"out"</code> (Standard: <code>in</code>)
|-
| 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.
|}


isdnKey - Der ISDN-Key.
=== Rückgabe/Response ===
location - Der Name eines in der Anrufliste konfigurierten Standortes.
{| class="wikitable"
msn - Der Name einer in der Anrufliste konfigurierten MSN.
! Parameter
number - Die Nummer des Anrufers.
! 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.
|}


Es sollte beachtet werden, das z.b. die Nummer „+492941247790“ zur Übergabe als Parameter codiert werden muss, damit das führende + auf dem Server passend ausgewertet werden kann. (http://de.wikipedia.org/wiki/URL-Encoding)
== 2. Anruf aktualisieren ==


Folgende Werte können übergeben werden:
'''Endpoint:'''
reason - Der base64 codierte Grund eines Anrufes.
<code>http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/update.php</code>
fileSource - Der base64 codierte Inhalt einer Datei.
fileType - Der Typ einer Datei. Der Standardwert liegt auf „fax“.
mimeType - Der mimetype einer Datei. Der Standardwert liegt auf „application/download“.
timestamp - Ein Unixtimestamp mit der der Eintrag erzeugt werden soll. Der Standardwert liegt auf dem Zeitpunkt des Aufrufs.


Es können folgende Fehlerwerte auftreten:
=== Pflichtparameter ===
1001 - MISSING_MANDATORY_REQUEST_PARAM_ISDNKEY
{| class="wikitable"
Meldung: „isdnKey“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
! Parameter
1002 - MISSING_MANDATORY_REQUEST_PARAM_LOCATION
! Beschreibung
Meldung: „location“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
|-
1003 - MISSING_MANDATORY_REQUEST_PARAM_MSN
| isdnKey
Meldung: „msn“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
| Der ISDN-Key
1004 - MISSING_MANDATORY_REQUEST_PARAM_NUMBER
|-
Meldung: „number“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
| number
| Rufnummer des zu aktualisierenden Anrufs ('''muss URL-encodiert werden''') (Wird nicht gebraucht wenn eine externalId übergeben wird.)
|}


2001 - MISSING_MANDATORY_DATABASE_CONNECTION_PARAM_HOST
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.
Meldung: „host“ database connection param is mandatory, please contact the support
2002 - MISSING_MANDATORY_DATABASE_CONNECTION_PARAM_USERNAME
Meldung: „username“ database connection param is mandatory, please contact the support
2003 - MISSING_MANDATORY_DATABASE_CONNECTION_PARAM_PASSWORD
Meldung: „password“ database connection param is mandatory, please contact the support
2004 - MISSING_MANDATORY_DATABASE_CONNECTION_PARAM_DATABASE
Meldung: „database“ database connection param is mandatory, please contact the support


3001 - DATABASE_CONNECTION_CREATE
=== Optionale Parameter ===
Meldung: Connection Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
{| class="wikitable"
3101 - DATABASE_QUERY_ON_VALIDATE_ISDNKEY_IN_DB
! Parameter
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
! Beschreibung
3102 - DATABASE_QUERY_ON_GET_LOCATIONID_BY_LOCATIONNAME
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| AnrufID
Meldung: No results found while trying to get the location id by location name
| ID des Anrufs (hat Vorrang vor <code>number</code>)
3103 - DATABASE_QUERY_ON_GET_LOCATION_CONFIGURATION
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| externalId
Meldung: No results found while trying to get the location configuration
| wurde beim initialen Eintrag des Anrufs eine externalId übergeben kann das update damit genau auf den Eintrag gemünzt werden.
3104 - DATABASE_QUERY_ON_GET_INTERNATIONAL_PREFIX_ID_BY_INTERNATIONAL_PREFIX
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| reason
Meldung: No results found while trying to get the internationalPrefixId
| Grund (Base64 oder Klartext, bei GET zusätzlich URL-encodiert)
3105 - DATABASE_QUERY_ON_IS_MSN_A_FAX_MSN_FOR_MSN_AND_LOCATIONID
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| reasonAppend
Meldung: No results found while checking if the msn is a fax msn
| Ergänzung zum Grund (Base64 oder Klartext, bei GET zusätzlich URL-encodiert)
3106 - DATABASE_QUERY_ON_CHECK_SIGNAL_TOLERANCE
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| acceptedBy
3107 - DATABASE_QUERY_ON_GET_LIST_ID_FOR_MSN_AND_LOCATION_ID
| Benutzerkürzel für „angenommen durch“
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
|-
Meldung: No results found while trying to get the list id for msn and location id
| callFor
3108 - DATABASE_QUERY_ON_GET_NUMBER_TO_NAME_ID_BY_NUMBER
| Benutzerkürzel für „Anruf für“
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
|-
3109 - DATABASE_QUERY_ON_GET_MSN_ID_BY_MSN_AND_LOCATION_ID
| recall
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| Angabe, ob ein Rückruf gewünscht ist als "ja" oder "nein"
Meldung: No results found while trying to get the msn id by msn and location id
|-
3110 - DATABASE_QUERY_ON_INSERT_ENTRY
| ownerInitial
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| Benutzerkürzel des internen Benutzers, der das Gespräch geführt hat
3111 - DATABASE_QUERY_ON_CITY_NAME_BY_PREFIX_AND_INTERNATIONAL_PREFIX
|-
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| fileSourceOut
3112 - DATABASE_QUERY_ON_FORMAT_NUMBER_WITH_LOCATION
| Ausgehender Audiostream als binärer Datei-Upload; nur via POST mit <code>multipart/form-data</code>
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
|-
3113 - DATABASE_QUERY_ON_INSERT_CALL_TO_CALLLIST
| fileSourceIn
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
| Eingehender Audiostream als binärer Datei-Upload; nur via POST mit <code>multipart/form-data</code>
3114 - DATABASE_QUERY_ON_INSERT_FILE
|}
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
3115 - DATABASE_QUERY_ON_SET_REASON
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
3116 - DATABASE_QUERY_ON_GET_COUNTRY_NAME_FOR_NATIONAL_PREFIX_ID
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]


4001 - API_INVALID_ISDNKEY
== 3. Sonderfall: OpenAI Whisper Integration 🎙️ ==
Meldung: the provided isdn key „[isdnKey]“ is not valid
 
4002 - API_NOT_VALIDATED
Jede ''infra-struktur''-Instanz verfügt über einen lokalen Whisper-Server, der Audiodateien automatisch transkribiert.
Meldung: you first need to validate your isdn key
Die '''Transkription wird im Anruf gespeichert''', die Originaldatei bleibt zusätzlich im Anruf per Mediaplayer abspielbar.
4101 - API_MINIMUM_NUMBER_LENGTH
 
Meldung: the number „[number]“ is below the required minimum number length of [minimumNumberLength]
=== Parameter ===
4102 - API_NUMBER_IS_HIDDEN_SIGNAL
{| class="wikitable"
Meldung: the number „[number]“ is the hidden signal „[hiddenSignal]“
! Parameter
4103 - API_CALL_IS_WITHIN_SIGNAL_TOLERANCE
! Beschreibung
Meldung: the call from the number „[number]“ is within the signal tolerance of [signalTolerance] seconds
|-
4104 - API_NO_CALLLIST_FOUND
| fileSourceRaw
Meldung: no appropriate call list found for MSN „[msn]“ and location id [locationId]
| 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 <code>externalId</code> 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 <code>multipart/form-data</code> möglich.
 
==== Parameter ====
 
{| class="wikitable"
! 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 <code>CT</code>.
|-
| fileSourceOut
| Binäre Audiodatei mit dem '''ausgehenden Audiostream''' des Gesprächs. Die Datei muss als Datei-Upload per <code>multipart/form-data</code> übertragen werden.
|-
| fileSourceIn
| Binäre Audiodatei mit dem '''eingehenden Audiostream''' des Gesprächs. Die Datei muss als Datei-Upload per <code>multipart/form-data</code> übertragen werden.
|}
 
Die Parameter <code>fileSourceOut</code> und <code>fileSourceIn</code> ermöglichen eine getrennte Verarbeitung beider Gesprächsseiten. Dadurch kann der interne Benutzer über <code>ownerInitial</code> dem Gespräch zugeordnet und eine automatische Zusammenfassung des Telefonats erzeugt werden.
 
Mindestens die zur eindeutigen Zuordnung benötigten Parameter <code>isdnKey</code> und <code>externalId</code> müssen übergeben werden.
 
== 4. Fehlercodes ==
 
=== 4.1 Fehlende Parameter ===
{| class="wikitable"
! Code
! Beschreibung
|-
| 1001
| isdnKey fehlt
|-
| 1002
| location fehlt
|-
| 1003
| msn fehlt
|-
| 1004
| number fehlt
|}
 
=== 4.2 Datenbankverbindung ===
{| class="wikitable"
! 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 ===
{| class="wikitable"
! 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) ===
<pre>
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"
</pre>
 
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 ===
<pre>
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"
</pre>
 
Hier wird neben der Audiodatei zusätzlich ein '''Anrufgrund''' gesetzt (reason) und ein Bearbeiter eingetragen (acceptedBy).
 
=== 5.3 GET-Beispiel: Text-Update ohne Datei ===
<pre>
curl "http://[instance]-classic.infra-struktur.eu/api/calllist/update.php?isdnKey=DEIN_ISDN_KEY&amp;number=%2B492941247790&amp;reason=Rückruf+gewünscht&amp;acceptedBy=AB"
</pre>
 
Ergebnis:
* Der Anruf mit der Nummer <code>+492941247790</code> 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 ===
 
<pre>
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"
</pre>
 
'''Bedeutung der Parameter:'''
 
{| class="wikitable"
! Parameter
! Beispielwert
! Bedeutung
|-
| isdnKey
| <code>247790</code>
| ISDN-Key der ''infra-struktur''-Instanz
|-
| ownerInitial
| <code>CT</code>
| Kürzel des internen Benutzers, der das Gespräch geführt hat
|-
| externalId
| <code>21cf1ada-a93c-4436-b3c9-eb404c1b954c</code>
| Eindeutige Gesprächs-ID des Telefonsystems
|-
| fileSourceOut
| <code>@/pfad/zum/audiostream.wav</code>
| Ausgehender Audiostream als binärer Datei-Upload
|-
| fileSourceIn
| <code>@/pfad/zum/audiostream.wav</code>
| Eingehender Audiostream als binärer Datei-Upload
|}
 
'''Ergebnis:'''
 
* Der über <code>externalId</code> identifizierte Anruf wird aktualisiert.
* Der eingehende und der ausgehende Audiostream werden dem Anruf zugeordnet.
* Das Benutzerkürzel aus <code>ownerInitial</code> 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 <code>fileSourceOut</code> und <code>fileSourceIn</code> 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.

Aktuelle Version vom 22. Oktober 2026, 13:43 Uhr

📞 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"
ownerInitial Benutzerkürzel des internen Benutzers, der das Gespräch geführt hat
fileSourceOut Ausgehender Audiostream als binärer Datei-Upload; nur via POST mit multipart/form-data
fileSourceIn Eingehender Audiostream als binärer Datei-Upload; nur via POST mit multipart/form-data

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.

Abgerufen von „https://adminwiki210.infra-struktur.de/index.php?title=Anruf_HTTP_GET_Schnittstelle_V2&oldid=2816“