Fragen? 0800 55400300
View Categories

ACD API

9 min read

The ACD API allows to integrate ACD functionality to your project. It has following URLs:

Querying an agent’s ready status:

A Method to query the current status of an agent. Uses the HTTP-POST method.

POST https://api.tenios.com/acd/agent-state/retrieve

Request Parameter:

access_key String The api access key. It can be found in the menu item General Settings, section API in the customer portal.
email String The Agent email (Cloud PBX->USER DETAILS).

Response Parameter:

state String The current ready status of the agent. Can be READY or NOT_READY haben.

Example of a successful request:

Request:

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

API Response:

HTTP Status Code: 200 (OK)

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

Change the status of an agent:

A method to change the status of an agent. Uses the HTTP-POST method.

POST https://api.tenios.com/acd/agent-state/change

 

Request Parameter:

access_key String The api access key. It can be found in the menu item General Settings, section API in the customer portal.
email String The Agent email (Cloud PBX->USER DETAILS).
state String The current ready status of the agent. Can be READY or NOT_READY.
nrr String Optional Acronym of a pre-configured Not-Ready Reason (NRR).

Response Parameter:

success boolean Is true if the ready state was successfully set, otherwise false.

Example of a successful request:

Request:

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

API Response:

HTTP Status Code: 200 (OK)

{
   "success": true
}

 

Examples of invalid requests:

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

Request:

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

API Response:

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 .

Request:

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

API Response:

HTTP Status Code: 400 (Bad Request)

{
   "error_code": "FIELD_IS_REQUIRED",
   "error_message": "Parameter 'page_size' is required",
   "fields": [
      "page_size"
   ]
}
INVALID_JSON
This error is returned if the provided JSON contains errors or is invalid in general.

Request:

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

API Response:

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.

Request:

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

API Response:

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.

Request:

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

API Response:

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
This error code will be returned if an invalid nrr is specified in the request.

Request:

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

 

API Response:

HTTP Status Code: 400 (Bad Request)

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

Retrieve the cloud acd details of a cloudpbx user:

A method to retrieve the cloud acd details of a cloudpbx user. Uses the HTTP-POST method.

POST https://api.tenios.com/acd/details/user/retrieve

 

Request Parameter:

access_key String The api access key. It can be found in the menu item General Settings, section API in the customer portal.
email String The Agent email (Cloud PBX->USER DETAILS).

Response Parameter:

success boolean Is true if the ready state was successfully set, otherwise false.

Example of a successful request:

Request:

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

API Response:

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
        }
    ]
}

Examples of invalid requests:

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

Request:

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

API Response:

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 .

Request:

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

API Response:

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.

Request:

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

API Response:

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.

Request:

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

API Response:

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"
   ]
}

Change the cloud acd details of a cloudpbx user:

A method to update the cloud acd details of a cloudpbx user. Uses the HTTP-POST method.

POST https://api.tenios.com/acd/details/user/change

 

Request Parameter:

access_key String The api access key. It can be found in the menu item General Settings, section API in the customer portal.
email String The Agent email (Cloud PBX->USER DETAILS).
cloud_acd_enabled Boolean
 Flag, if the cloud acd is enabled for the cloud pbx user
sip_enabled Boolean Flag, if SIP e.g. external SIP clients or the embedded BrowerPhone in the cloud pbx portal is enabled
external_number_enabled Boolean Flag, if the external number is enabled
external_number String The external phone number in where the agent can be called
state String The current ready status of the agent. Can be READY or NOT_READY.
user_skills Array An array of all user skills with the name and value.

Response Parameter:

success boolean Is true if the ready state was successfully set, otherwise false.

Example of a successful request:

Request:

{
    "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 Response:

HTTP Status Code: 200 (OK)

{
    "success": true
}

Examples of invalid requests:

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

Request:

{
    "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 Response:

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
This error is returned if a mandatory parameter is not provided in the request .

Request:

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

API Response:

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.

Request:

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

API Response:

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.

Request:

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

API Response:

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"
   ]
}

TOP