Dokumentation

ACD API

Die ACD API ermöglicht es ACD-Funktionalität in Ihr Projekt zu integrieren. Die folgenden URLs stehen zur Verfügung:

Bereit-Status eines Agenten abfragen:

Mit dieser Methode kann der aktuelle Bereit-Status eines Agenten abgefragt werden. Verwendet die HTTP POST-Methode.

POSThttps://api.tenios.com/acd/agent-state/retrieve

 

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
email StringDie E-Mail Adresse des Agenten (Cloud PBX->BENUTZER DETAILS)

Antwortparameter:

state StringDer aktuelle Bereit-Status des Agenten. Kann den Wert READY oder NOT_READY haben.

Beispiel für eine erfolgreiche Anfrage:

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "test@test.com"
}

API Response:

HTTP Status Code: 200 (OK)

{
   "email": "test@test.com",
   "state": "NOT_READY"
}

Bereit-Status eines Agenten ändern:

Eine Methode um den Bereit-Status des Agenten zu ändern. Verwendet die HTTP-POST Methode.

POSThttps://api.tenios.com/acd/agent-state/change

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
email StringE-Mail Adresse des Agenten (Cloud PBX->BENUTZER DETAILS)
state StringDer Bereit-Status auf den der Agent gesetzt werden soll. Kann den Wert READY oder NOT_READY haben.
not_ready_reason String OptionalAkronym eines bereits vorkonfigurierten NBG.

Antwortparameter:

success booleanHat den Wert true, wenn der Bereit-Status erfolgreich gesetzt werden konnte, ansonsten false.

Beispiel für eine erfolgreiche Anfrage:

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "agent@test.com",
   "state": "READY",
   "not_ready_reason": "COF"
}

API Antwort:

HTTP Status Code: 200 (OK)

{
   "success": true
}

Beispiele für fehlerhafte Anfragen:

BAD_CREDENTIALS
Dieser Fehler wird zurückgegeben, wenn ein ungültiger access_key angegeben wurde.
Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "page": 1,
   "page_size": 10
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "BAD_CREDENTIALS",
   "error_message": "Bad credentials",
   "fields": []
}
FIELD_IS_REQUIRED
Dieser Fehler wird zurückgegeben, wenn in der Anfrage ein erforderlicher Parameter nicht angegeben wurde.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "page": 1
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "FIELD_IS_REQUIRED",
   "error_message": "Parameter 'page_size' is required",
   "fields": [ 
     "page_size"
   ]
}
INVALID_JSON
Dieser Fehler wird zurückgegeben, wenn das übergebene JSON unbekannte Parameter enthält oder generell ungültig ist.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "unknown_parameter": "unknown"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "INVALID_JSON",
   "error_message": "An invalid JSON object was provided in the request body.",
   "fields": [ 
        "unknown_parameter"
   ]
}
AGENT_NOT_FOUND
Dieser Fehler wird zurückgegeben, wenn eine unbekannte email in der Anfrage angegeben wurde.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "unknownemail@test.com"
}

 

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_NOT_FOUND",
   "error_message": "Agent not found.",
   "fields": [ ]
}
AGENT_STATE_INVALID_EMAIL
Dieser Fehler wird zurückgegeben, wenn eine ungültige email (falsche Syntax) in der Anfrage angegeben wurde.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "invalidemail@@test.com"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_STATE_INVALID_EMAIL",
   "error_message": "Invalid email. You can use only valid email of agent which belongs to your account.",
   "fields": [ 
       "email"
   ]
}
AGENT_NOT_READY_REASON_NOT_FOUND
Dieser Fehler wird zurückgegeben, wenn not_ready_reason ungültig ist.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "agent@test.com",
   "state": "READY",
   "not_ready_reason": "COF"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_NOT_READY_REASON_NOT_FOUND",
   "error_message": "Agent not ready reason not found.",
   "fields": [ 
       "not_ready_reason"
   ]
}

Initialen Status der Agenten abfragen:

Eine Methode um einen aktuellen Snapshot der Bereit-, InCall- und Wrapup-Status aller Agenten abzufragen. Verwendet die HTTP-POST Methode.

POSThttps://api.tenios.com/user-states/snapshot

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.

Antwortparameter:

successbooleanHat den Wert true, wenn der Bereit-Status erfolgreich gesetzt werden konnte, ansonsten false.
user_statesarray[user_states]Ein array mit allen user states des accounts
userStringDie E-Mail Adresse des Cloud-PBX Benutzers (Agents) .
statesstatesEin states-Objekt mit Ready-, InCall array mit allen user states des Cloud-PBX users
ready objektEin Ready-Objekt mit Ready-, InCall array mit allen user states des Cloud-PBX users
valueenumDer Ready-Status des Agenten. Kann die Werte READY oder NOT_READY haben.
tsspecial timestampEin Zeitstempel in einem speziellen Format, der angibt wann der Status begonnen hat.
in_callobjectEin InCall-Objekt
valueenumDer InCall-Status des Agenten. Kann die Werte IN_CALL oder NOT_IN_CALL haben.
tsspecial timestampEin Zeitstempel in einem speziellen Format, der angibt wann der Status begonnen hat.
wrap_upobjectEin Wrapup-Objekt
valuefrom / to attributesEin Wert mit den Attributen from und to mit Zeitstempeln wann der Wrapup-Status aktiv war.
tsspecial timestampEin Zeitstempel in einem speziellen Format, der angibt wann der Status begonnen hat.

 

Zeitstempel-Format

Der Zeitstempel besteht aus drei Teilen die durch einen Unterstrich ‚_‘ getrennt sind. Beispiel: 1526543964195_0000000021_cebccb2d3908ddbfe06922cd571de656ff7d1db0d2f567e5718522d891033a3a

  1. 1526543964195 – Millisekunden (UNIX timestamp)
  2. 0000000021 – 10-stelliger Zähler, der eine laufende Nummer der Nachricht während einer Verbindung angibt
  3. cebccb2d3908ddbfe06922cd571de656ff7d1db0d2f567e5718522d891033a3a – SHA256 hash von (1526543964195_0000000021_connectionId)

 

Beispiel für eine erfolgreiche Anfrage:

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX"
}

API Antwort:

HTTP Status Code: 200 (OK)

{
   "success": true,
   "user_states": [ 
      {
         "user": "michael2@test.com",
         "states": {
            "ready": {
               "value": "NOT_READY",
               "ts": "1643998017197_0000000000_d29b667b6cc6bf1e746845b8bad86a5b26148b5f3a6075738dbda864a18f96ad"
            },
            "in_call": {
               "value": "NOT_IN_CALL",
               "ts": "1643998017210_0000000000_75434915172af89b392fbed918f20554600e3d565adb4b4cd1397b20fcb7297a"
            },
            "wrap_up": {
               "value": "{from=1,to=1}",
               "ts": "1643998017213_0000000000_77b8406f16da083187e792d4b32f87206ead7f3fce9095e681f34bf620e44238"
            }
         }
      },
      {
         "user": "michael@test.com",
         "states": {
            "ready": {
               "value": "READY",
               "ts": "1642771485759_0000000001_9faed22b74c48e1dcf77718cd25c3044a5b305b5f316aac3cc4af5a61053b987"
            },
            "in_call": {
               "value": "IN_CALL",
               "ts": "1642771485779_0000000001_9faed22b74c48e1dcf77718cd25c3044a5b305b5f316aac3cc4af5a61053b987"
            },
            "wrap_up": {
               "value": "{from=1642696809682,to=1642697267192}",
               "ts": "1642771485769_0000000001_9faed22b74c48e1dcf77718cd25c3044a5b305b5f316aac3cc4af5a61053b987"
            }
         }
      }
   ]
}

 

Beispiele für fehlerhafte Anfragen:

BAD_CREDENTIALS
Dieser Fehler wird zurückgegeben, wenn ein ungültiger access_key angegeben wurde.
Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "BAD_CREDENTIALS",
   "error_message": "Bad credentials",
   "fields": [ ]
}
FIELD_IS_REQUIRED
Dieser Fehler wird zurückgegeben, wenn in der Anfrage ein erforderlicher Parameter nicht angegeben wurde.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "FIELD_IS_REQUIRED",
   "error_message": "Parameter"
}

Abrufen der Cloud-ACD-Details eines Cloudpbx-Benutzers:

Eine Methode zum Abrufen der Cloud-ACD-Details eines Cloudpbx-Benutzers. Verwendet die HTTP-POST-Methode.

POSThttps://api.tenios.com/acd/details/user/retrieve

 

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
email StringDie E-Mail des Agenten (Cloud PBX->USER DETAILS).

Antwortparameter:

success booleanHat den Wert true if the ready state was successfully set, otherwise false.

Beispiel für erfolgreiche Anfragen:

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "agent@test.com",
}

API Antwort:

HTTP Status Code: 200 (OK)

{
    "success": true,
    "cloud_acd_enabled": true,
    "sip_enabled": true,
    "external_number_enabled": true,
    "external_number": "+4922155400300",
    "state": "READY",
    "current_destination": "SIP",
    "user_skills": [ 
        {
            "name": "English",
            "has_skill": false
        },
        {
            "name": "German",
            "has_skill": true
        },
        {
            "name": "Sales",
            "has_skill": false
        },
        {
            "name": "Support",
            "has_skill": true
        },
        {
            "name": "Spanish",
            "has_skill": false
        },
        {
            "name": "Customer Service",
            "has_skill": true
        },
        {
            "name": "Accounting",
            "has_skill": false
        }
    ]
}

Beispiele für fehlerhafte Anfragen:

BAD_CREDENTIALS
This code is returned if an invalid access_key was provided.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "page": 1,
   "page_size": 10
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "BAD_CREDENTIALS",
   "error_message": "Bad credentials",
   "fields": []
}
FIELD_IS_REQUIRED
This error is returned if a mandatory parameter is not provided in the request .

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "unknown_parameter": "unknown"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "INVALID_JSON",
   "error_message": "An invalid JSON object was provided in the request body.",
   "fields": [ 
      "unknown_parameter"
   ]
}
AGENT_NOT_FOUND
This error code will be returned if an unknown email was specified in the request.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "unknownemail@test.com"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_NOT_FOUND",
   "error_message": "Agent not found.",
   "fields": []
}
AGENT_STATE_INVALID_EMAIL
Dieser Fehlercode wird zurückgegeben, wenn die in der Anfrage angegebene E-Mail  nicht gefunden wurde.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "invalidemail@@test.com"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_STATE_INVALID_EMAIL",
   "error_message": "Invalid email. You can use only valid email of agent which belongs to your account.",
   "fields": [ 
      "email"
   ]
}

Ändern der Cloud-ACD-Details eines Cloudpbx-Benutzers:

Eine Methode zum Aktualisieren der Cloud-ACD-Details eines Cloudpbx-Benutzers. Verwendet die HTTP-POST-Methode.

 

POSThttps://api.tenios.com/acd/details/user/change

Anfrageparameter:

access_key StringDer Zugriffsschlüssel (Access Key) für die API. Dieser kann im Kundenportal unter dem Menüpunkt MY ACCOUNT/ Allgemeine Einstellungen im Abschnitt API gefunden werden.
email StringThe Agent email (Cloud PBX->USER DETAILS).
cloud_acd_enabled Boolean
Flag, ob die cloud acd für den Cloud-Pbx-Benutzer aktiv ist
sip_enabled BooleanFlag, ob SIP bzw. externe SIP-Clients oder das integrierte BrowerPhone in der Cloud-Pbx aktiviert ist.
external_number_enabled BooleanFlag, ob eine externe Rufnummer aktiviert ist.
external_number StringDie externe Rufnummer unter der der Agent erreichbar ist.
state StringDer aktuelle Status des Agenten. Dieser kann READY oder NOT_READY sein.
user_skills ArrayEin array in dem alle Benutzer-Skills mit Namen und Wert abgegeben werden. 

Antwortparameter:

success booleanHat den Wert true if wenn die Werte erfolgreich gesetzt werden konnten, ansonsten false.
Beispiel für eine erfolgreiche Anfrage:

Anfrage:

{
    "access_key": "XXXXX-XXXX-XXXXXX",
    "email": "dhanks@test.com",
    "cloud_acd_enabled": true,
    "sip_enabled": true,
    "external_number_enabled": true,
    "external_number": "+491231244",
    "state": "READY",
    "user_skills": [ 
        {
            "name": "Support",
            "has_skill": true
        },
        {
            "name": "English",
            "has_skill": false
        },
        {
            "name": "German",
            "has_skill": true
        },
        {
            "name": "Sales",
            "has_skill": true
        },
        {
            "name": "Spanish",
            "has_skill": false
        },
        {
            "name": "Customer Service",
            "has_skill": true
        },
        {
            "name": "Accounting",
            "has_skill": true
        }
    ]
}

API Antwort:

HTTP Status Code: 200 (OK)

{
    "success": true
}

Beispiele für fehlerhafte Anfragen:

BAD_CREDENTIALS
This code is returned if an invalid access_key was provided.

Anfrage:

{
    "access_key": "XXXXX-XXXX-XXXXXX",
    "email": "dhanks@test.com",
    "cloud_acd_enabled": true,
    "sip_enabled": true,
    "external_number_enabled": true,
    "external_number": "+491231244",
    "state": "READY",
    "user_skills": [ 
        {
            "name": "Support",
            "has_skill": true
        } 
     ]
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
    "success": false,
    "error_code": "ACD_USER_DETAILS_ALL_SKILLS_REQUIRED_ERROR",
    "error_message": "Provide all user skills to use this API.",
    "fields": [ ]
}
FIELD_IS_REQUIRED
Dieser Fehler wird zurückgegeben, wenn in der Anfrage nicht alle Skills angegeben wurden. Es müssen immer alle Skills die konfiguriert sind angegeben werden.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "unknown_parameter": "unknown"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "INVALID_JSON",
   "error_message": "An invalid JSON object was provided in the request body.",
   "fields": [ 
      "unknown_parameter"
   ]
}
AGENT_NOT_FOUND
Dieser Fehler wird zurückgegeben wenn das JSON ungültig ist.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "unknownemail@test.com"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_NOT_FOUND",
   "error_message": "Agent not found.",
   "fields": [ ]
}
AGENT_STATE_INVALID_EMAIL
This error code will be returned if an invalid email (invalid syntax) was specified in the request.

Anfrage:

{
   "access_key": "XXXXX-XXXX-XXXXXX",
   "email": "invalidemail@@test.com"
}

API Antwort:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "AGENT_STATE_INVALID_EMAIL",
   "error_message": "Invalid email. You can use only valid email of agent which belongs to your account.",
   "fields": [ 
      "email"
   ]
}