Anruf HTTP GET Schnittstelle V2: Unterschied zwischen den Versionen

Aus infra-struktur AdminWiki 2.10
Zur Navigation springenZur Suche springen
← Zum vorherigen VersionsunterschiedZum nächsten Versionsunterschied →
Keine Bearbeitungszusammenfassung
Keine Bearbeitungszusammenfassung
Zeile 1: Zeile 1:
'''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'''.


Übergabe als webhook per GET oder POST (GET hat Vorrang vor POST)
== 1. Anruf eintragen ==


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


'''Folgende Werte müssen übergeben werden:'''
=== Pflichtparameter ===
isdnKey - Der ISDN-Key.
{| class="wikitable"
location - Der Name eines in der Anrufliste konfigurierten Standortes.
! Parameter
msn - Der Name einer in der Anrufliste konfigurierten eingehenden Rufnummern/Nebenstellen.
! Beschreibung
number - Die Nummer des Anrufers.
|-
| 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>)
|}


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)
=== 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>)
|}


== 2. Anruf aktualisieren ==


'''Folgende Werte können übergeben werden:'''
'''Endpoint:'''
reason - Der base64 codierte Grund eines Anrufes.
<code>
fileSource - Der base64 codierte Inhalt einer Datei.
http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/update.php
fileType - Der Typ einer Datei. Der Standardwert liegt auf „fax“.
</code>
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.
direction - entweder "in" oder "out für eingehende oder ausgehende Anrufe. Default ist "in".


'''Um einen bestehenden Anruf zu aktualisieren kann folgender Webhook genutzt werden.'''
=== Pflichtparameter ===
{| class="wikitable"
! Parameter
! Beschreibung
|-
| isdnKey
| Der ISDN-Key
|-
| number
| Rufnummer des zu aktualisierenden Anrufs ('''muss URL-encodiert werden''')
|}


Adresse: http://[instance]-classic.infra-struktur.[eu|com]/api/calllist/update.php
=== Optionale Parameter ===
{| class="wikitable"
! Parameter
! Beschreibung
|-
| id
| ID des Anrufs (hat Vorrang vor <code>number</code>)
|-
| 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
|}


Übergabe als webhook per GET oder POST (GET hat Vorrang vor POST)
== 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.


'''Folgende Werte müssen übergeben werden:'''
=== Parameter ===
isdnKey - Der ISDN-Key.
{| class="wikitable"
number - Die Nummer des Anrufs der aktualisiert werden soll.
! Parameter
! Beschreibung
|-
| fileSourceRaw
| Audiodatei im '''Binary-Format''' (nur via '''POST''' möglich, wegen Größe und Format)
|}


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)
== 4. Fehlercodes ==


=== 4.1 Fehlende Parameter ===
{| class="wikitable"
! Code
! Beschreibung
|-
| 1001
| isdnKey fehlt
|-
| 1002
| location fehlt
|-
| 1003
| msn fehlt
|-
| 1004
| number fehlt
|}


'''Folgende Werte können übergeben werden:'''
=== 4.2 Datenbankverbindung ===
id - die ID des Anrufs die beim anlegen des Anrufs zurückgegeben wurde. Die hat auch vorrang vor einer übergebenen Rufnummer.
{| class="wikitable"
reason - ein Anrufgrund der als base64 oder im Klartext übergeben werden kann. Als GET ert muss das natürlich URLencoded werden.
! Code
reasonAppend - ein Ergänzung zu einem Anrufgrund der als base64 oder im Klartext übergeben werden kann. Als GET ert muss das natürlich URLencoded werden.
! Beschreibung
acceptedBy - das Kürzel des Benutzer der in "angenommen durch" eingetragen werden soll.
|-
callFor - das Kürzel des Benutzer der in "Anruf für" eingetragen werden soll.
| 2001
recall - Die Information ob ein Rückruf gewünscht ist.
| host fehlt
'''Sonderfall OpenAI Whisper Integration'''
|-
Jede infra-struktur hat einen integrierten lokalen Whisper-Server der aus Audiodateien transkriptionen erzeugen kann.
| 2002
Dafür kann der update.php eine Audiodatei übergeben werden. Diese wird dann in Text gewandelt und der Text wird in den Anruf geschrieben. Die Audiodatei
| username fehlt
ist mit einem Mediaplayer auch noch abspielbar unter dem Anruf.
|-
| 2003
fileSourceRaw - Eine Audiodatei im binary Format. Aufgrund des Formats und der Größe nur mit POST zu nutzen.
| 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


'''Es können folgende Fehlerwerte auftreten:'''
(Alle Fehler mit MySQLi-Fehlernummer und Fehlermeldung.)


1001 - MISSING_MANDATORY_REQUEST_PARAM_ISDNKEY
=== 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
|}


Meldung: „isdnKey“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
== 5. Beispiele ==


1002 - MISSING_MANDATORY_REQUEST_PARAM_LOCATION
=== 5.1 POST-Beispiel: Audiodatei hochladen & transkribieren (Whisper) ===
<syntaxhighlight lang="bash">
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"
</syntaxhighlight>


Meldung: „location“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
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.


1003 - MISSING_MANDATORY_REQUEST_PARAM_MSN
=== 5.2 POST-Beispiel: Audiodatei mit zusätzlichen Parametern ===
<syntaxhighlight lang="bash">
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"
</syntaxhighlight>


Meldung: „msn“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
Hier wird neben der Audiodatei zusätzlich ein '''Anrufgrund''' gesetzt (reason) und ein Bearbeiter eingetragen (acceptedBy).


1004 - MISSING_MANDATORY_REQUEST_PARAM_NUMBER
=== 5.3 GET-Beispiel: Text-Update ohne Datei ===
<syntaxhighlight lang="bash">
curl "http://[instance]-classic.infra-struktur.eu/api/calllist/update.php?isdnKey=DEIN_ISDN_KEY&number=%2B492941247790&reason=Rückruf+gewünscht&acceptedBy=AB"
</syntaxhighlight>


Meldung: „number“ request param is mandatory, provide it via GET or POST (if both are set, GET will be preferred)
Ergebnis:
 
* Der Anruf mit der Nummer <code>+492941247790</code> wird aktualisiert.
 
* Als Grund wird ''Rückruf gewünscht'' gespeichert.
2001 - MISSING_MANDATORY_DATABASE_CONNECTION_PARAM_HOST
* Der Anruf wird als '''angenommen durch Benutzer AB''' markiert.
 
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
 
Meldung: Connection Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3101 - DATABASE_QUERY_ON_VALIDATE_ISDNKEY_IN_DB
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3102 - DATABASE_QUERY_ON_GET_LOCATIONID_BY_LOCATIONNAME
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while trying to get the location id by location name
 
3103 - DATABASE_QUERY_ON_GET_LOCATION_CONFIGURATION
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while trying to get the location configuration
 
3104 - DATABASE_QUERY_ON_GET_INTERNATIONAL_PREFIX_ID_BY_INTERNATIONAL_PREFIX
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while trying to get the internationalPrefixId
 
3105 - DATABASE_QUERY_ON_IS_MSN_A_FAX_MSN_FOR_MSN_AND_LOCATIONID
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while checking if the msn is a fax msn
 
3106 - DATABASE_QUERY_ON_CHECK_SIGNAL_TOLERANCE
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3107 - DATABASE_QUERY_ON_GET_LIST_ID_FOR_MSN_AND_LOCATION_ID
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while trying to get the list id for msn and location id
 
3108 - DATABASE_QUERY_ON_GET_NUMBER_TO_NAME_ID_BY_NUMBER
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3109 - DATABASE_QUERY_ON_GET_MSN_ID_BY_MSN_AND_LOCATION_ID
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
Meldung: No results found while trying to get the msn id by msn and location id
 
3110 - DATABASE_QUERY_ON_INSERT_ENTRY
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3111 - DATABASE_QUERY_ON_CITY_NAME_BY_PREFIX_AND_INTERNATIONAL_PREFIX
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3112 - DATABASE_QUERY_ON_FORMAT_NUMBER_WITH_LOCATION
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
3113 - DATABASE_QUERY_ON_INSERT_CALL_TO_CALLLIST
 
Meldung: Query Error (MySQLi: [MySQLi Fehlernummer]) [MySQLi Fehlermeldung]
 
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
 
Meldung: the provided isdn key „[isdnKey]“ is not valid
 
4002 - API_NOT_VALIDATED
 
Meldung: you first need to validate your isdn key
 
4101 - API_MINIMUM_NUMBER_LENGTH
 
Meldung: the number „[number]“ is below the required minimum number length of [minimumNumberLength]
 
4102 - API_NUMBER_IS_HIDDEN_SIGNAL
 
Meldung: the number „[number]“ is the hidden signal „[hiddenSignal]“
 
4103 - API_CALL_IS_WITHIN_SIGNAL_TOLERANCE
 
Meldung: the call from the number „[number]“ is within the signal tolerance of [signalTolerance] seconds
 
4104 - API_NO_CALLLIST_FOUND
 
Meldung: no appropriate call list found for MSN „[msn]“ and location id [locationId]

Version vom 22. August 2025, 10:23 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)

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)

Optionale Parameter

Parameter Beschreibung
id ID des Anrufs (hat Vorrang vor number)
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

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)

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)

<syntaxhighlight lang="bash"> 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"

</syntaxhighlight>

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

<syntaxhighlight lang="bash"> 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"

</syntaxhighlight>

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

5.3 GET-Beispiel: Text-Update ohne Datei

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

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.
Abgerufen von „https://adminwiki210.infra-struktur.de/index.php?title=Anruf_HTTP_GET_Schnittstelle_V2&oldid=2747“