Introduction
This document describes EnreachAPI (formerly known as BeneAPI), a RESTful API that allows 3rd parties access Enreach systems to perform various functions. EnreachAPI serves data mapped as resources corresponding to URI paths. Client applications make HTTP requests to the API and handle the response. Request and response data can be serialized to either JSON or XML formats. The API is not dependent on any specific language or technology, so it can be used by any application capable of making HTTP requests and parsing the responses.
Note that Benemen was renamed to Enreach in 2022, and corresponding naming changes were applied to technical products and documentation as well. Some documentation and technical details (XML namespaces, domain names) may still contain Benemen references.
HTTPS requirements
HTTPS is required for all endpoints. Security configuration follows SSLabs SSL and TLS Deployment Best Practices.
All API integrations must meet following requirements for HTTPS.
TLS Protocol support
Supported TLS protocols are TLS v1.2 and TLS v1.3. As of January 20, 2022, older TLS 1.0 and 1.1 protocols are deprecated for all HTTPS services.
Secure Cipher Suites
Following cipher suites are supported. As of June 16, 2022, all older and insecure cipher suites are deprecated for all HTTPS services.
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES256-GCM-SHA384
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-CHACHA20-POLY1305
- ECDHE-RSA-CHACHA20-POLY1305
Service discovery
Example discovery using POST
POST https://discover.enreachvoice.com/api/user
Content-Type: application/json
{
"user": "user.name@example.com",
}
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
Date: Thu, 14 Jun 2018 13:25:14 GMT
[
{
"siloName": "Silo02",
"username": "user.name@example.com",
"apiEndpoint": "https://api-sedna.enreachvoice.com/",
"uiEndpoint": "https://sedna.enreachvoice.com/Account/LogOn/?un=user.name@example.com",
"authority": null,
"authorityIdPHint": null,
"basicAuthEndpoint": "https://sedna.enreachvoice.com/Account/BasicLogOn/?un=user.name@example.com",
"recoveryEndpoint": "https://sedna.enreachvoice.com/Account/RequestPassword/?un=user.name@example.com"
}
]
Example discovery using GET
curl -v https://discover.enreachvoice.com/api/user?user=user.name@example.com
> GET /api/user?user=test.user@domain.com HTTP/1.1
> Host: discover.enreachvoice.com
> User-Agent: curl/7.55.1
< HTTP/1.1 200 OK
< Transfer-Encoding: chunked
< Content-Type: application/json; charset=utf-8
< Date: Thu, 14 Jun 2018 13:25:14 GMT
<
[
{
"siloName": "Silo02",
"username": "user.name@example.com",
"apiEndpoint": "https://api-sedna.enreachvoice.com/",
"uiEndpoint": "https://sedna.enreachvoice.com/Account/LogOn/?un=user.name@example.com",
"authority": null,
"authorityIdPHint": null,
"basicAuthEndpoint": "https://sedna.enreachvoice.com/Account/BasicLogOn/?un=user.name@example.com",
"recoveryEndpoint": "https://sedna.enreachvoice.com/Account/RequestPassword/?un=user.name@example.com"
}
]
Enreach provides two-layer infrastructure, where different users may be served by different backends accessed via different API addresses.
For dynamic clients providing service to any user logging in, service discovery is an important part of the overall functionality. For static integrations, targeting a single, known endpoint is acceptable. However, implementing service discovery always makes the service more robust, as manual endpoint changes can be avoided in the future.
Discovery endpoint is always https://discover.enreachvoice.com/api/user/ for production use. Discovery application also provides a browser interface that the users can use to discover their default web interfaces. This is found at site root address https://discover.enreachvoice.com/, but is not relevant for integrations.
The discovery API requires a single parameter: username of the user logging in. This must be a full username, no partial matching is performed. The request can be made with either GET or POST method.
Result contains a list of endpoints where given username is found. Usually given username is found in a single endpoint only. However, if relevant for the use case, multiple endpoints should be supported so that if there are multiple results, a selection dialog is shown for the user.
If the username is not found at all, a 404 Not found response is returned.
Each individual endpoint result contains urls for both API and additionally other information for Enreach Client use, which are not relevant in API integraiton use cases. For integrations, the API endpoint is used as API root address for all actual API requests.
After endpoint result is discovered, it should be stored locally and cached for the duration of application runtime.
Request properties
When using GET, the username is passed as a query parameter.
When using POST, the username is passed in the request body as a JSON object.
Property | Sample value | Description |
---|---|---|
user | user.name@example.com | Username to be discovered |
Response properties
Property | Sample value | Description |
---|---|---|
siloName | Silo02 | Display name for the silo for any necessary user interaction |
username | test.user@example.com | Matched username (always the same that was queried) |
apiEndpoint | https://api-sedna.enreachvoice.com/ | Actual REST API endpoint |
uiEndpoint | https://sedna.enreachvoice.com/Account/LogOn/?un=test.user@example.com | Voice Center endpoint |
authority | Modern authentication Authority information | |
authorityIdPHint | Modern authentication External IdP | |
basicAuthEndpoint | https://sedna.enreachvoice.com/Account/BasicLogOn/?un=user.5@domain.fi | Endpoint for Basic authentication (Only classic authentication) |
recoveryEndpoint | https://sedna.enreachvoice.com/Account/RequestPassword/?un=user.5@domain.fi | Endpoint for Classic authentication password reset endpoint |
Key acquisition (Classic authentication)
EnreachAPI supports two authentication models: Modern authentication and Classic authentication.
Modern authentication via Enreach Identity is OpenId Connect/OAuth2 bearer token based authnetication method. It is currently supported only for Enreach Client applications.
Classic authentication is based on SecretKey
and HTTP Basic Authentication. Classic authentication is used for all external API integrations.
Each request to EnreachAPI must be authenticated (except operations where it is not possible, e.g. authentication and password recovery). The requests are authenticated with username and SecretKey
, a random string acquired from backend.
There are two ways to acquire the SecretKey
:
Password authentication
If there are no pre-configured credentials available, usually in cases where the actual end-user is expected to log in to the system
with their own credentials, the client can perform a direct password authentication against the API using the POST /authuser/{email}/
endpoint. First, the client should collect end-user credentials and authenticate to API with. SecretKey
property should be then extracted from the response and used in further communication. This is the usual way for end-user interfaces.
Off-band key delivery
Username and SecretKey can be delivered off-band directly. In this case, the related account does not have an actual password set and cannot perform the username+password authentication step described below. It is not needed either, as the SecretKey is used directly to authenticate the requests. This mechanism is mostly used for server-side integrations where a single static integration account is used.
Request authentication
Each request to EnreachAPI must be authenticated (except operations where it is not possible, e.g. authentication and password recovery). The requests are authenticated with username and SecretKey
(acquisition described in [key acquisition)(#key-acquisition)]).
There are two different mechanisms that can be used to authenticate the requests. Basic authentication should be used for new development, signature-based model is supported for backwards-compatibility.
Basic authentication
string GetBasicAuthorizationHeader(string user, string key)
{
var combined = user + ":" + key;
var bytes = System.Text.Encoding.UTF8.GetBytes(combined);
var base64 = System.Convert.ToBase64String(bytes);
var headerValue = "Basic " + base64;
var header = "Authorization: " + headerValue;
return header;
}
import base64
def get_header(user, key):
combined = user + u":" + key
bytes = bytes(combined, "utf-8")
b64string = base64.b64encode(bytes).decode("utf-8")
return "Authorization: Basic " + b64string
Basic authentication is the recommended mechanism for authentication. It relies on standard Basic authentication, using SecretKey
as password.
Note that due to backwards-compatibility requirements and multiple authentication mechanisms, standard WWW-Authenticate
header is not returned
for 401 Unauthorized responses.
Most client libraries support Basic authentication out of the box. It can be also implemented manually very simply. Example below uses username: test.user@test.com, Secretkey: badkey
- username and key are combined with a single colon
test.user@test.com:badkey
- result string is represented as a byte array (using UTF-8 encoding), which is then encoded as a base64 string
dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==
- The base64 string is prepended by "Basic "
Basic dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==
- The value is sent as request Authorization header
Authorization: Basic dGVzdC51c2VyQHRlc3QuY29tOmJhZGtleQ==
Signature-based (legacy)
import urllib2, hmac, hashlib, base64
# request is urllib2.Request
request = build_your_own_request()
# Your credentials
user = "user.name@test.com"
key = "badkey"
msgstring = "\n".join([
request.get_method(),
request.get_header("Content-md5", default=""),
request.get_header("Content-type", default=""),
request.get_header("Date", default=""),
request.get_selector()
])
hash = hmac.new(key, msgstring, hashlib.sha1)
encoded = base64.b64encode(hash.digest())
headerval = base64.b64encode("%s:%s" % (user, encoded))
header = "BeneAPI %s" % headerval
request.add_header("Authorization”, header)
using System.Convert;
using System.Text;
using System.Security.Cryptography;
using System.Collections.Specialized;
public static string CalculateRequestHash(
String httpMethod,
String requestUri,
NameValueCollection headers
)
{
string signature =
httpMethod + '\n' +
headers.Get("Content-MD5") + '\n' +
headers.Get("Content-Type") + '\n' +
headers.Get("Date") + '\n' +
requestUri;
HMACSHA1 hmac = new HMACSHA1(Encoding.UTF8.GetBytes("1234"));
byte[] bytes = Encoding.UTF8.GetBytes(signature);
byte[] hash = hmac.ComputeHash(bytes);
string b64hash = Convert.ToBase64String(hash);
return b64hash;
}
With legacy hash calculation mechanism, clients authenticate each request by signing it with their private key. This method is fully supported for backwards-compatibility with existing clients, but for new development Basic authentication is recommended for ease of use.
Note that despite the API being renamed from BeneAPI to EnreachAPI, the legacy BeneAPI
scheme is used here.
For each request, client computes a message hash with his private key. This hash is sent along with the request in Authorization
header. Each request must contain an Authorization HTTP Header of format:
Authorization: BeneAPI base64encode({Username}:{Signature})
Where username is the provided username and signature is a hash calculated for each request individually. For example:
Authorization: BeneAPI dXNlci5uYW1lQHRlc3QuY29tOmFiY2QxMjM0
Hash is calculated from selected parts of the request:
- HTTP method
Content-MD5
header valueContent-Type
header valueDate
header value- Request path and query
The exact values of these fields are joined together with a \n
(new line) character. If some header is not used in the request, an empty string is used instead in calculation. A HMAC-SHA1 hash is then calculated from the result string (UTF-8 encoded bytes) using the acquired secret key as the key.
Every request must have Date header containing current UTC time. It must be sufficiently close (a few minutes) to server time for request to be accepted. Date format should conform to RFC2616, e.g.:
Date: Wed, 11 Feb 2015 09:14:55 GMT
For convenience YYYY-MM-DD HH:MM:SS GMT is also accepted, e.g.:
Date: 2015-02-11 09:14:55 GMT
Detailed sample calculation
- A GET request is made to an endpoint:
https://beneapi30.beneservices.com/users/c24a0acb-8fd1-e511-874c-00155d000507/availability/active?PresenceTypeIds=0
- Request contains a Content-Type header but as no actual content is sent, Content-MD5 header is not present and empty string is used instead
GET\n\napplication/json\n2016-02-15 10:28:52 GMT\n/users/c24a0acb-8fd1-e511-874c-00155d000507/availability/active?PresenceTypeIds=0
- The constructed string is signed with the example key badkey
FothFWvu0L6xWAFJbFC6ku/Ss8Q=
- The hash is joined together with requesting username:
test.user@test.com:FothFWvu0L6xWAFJbFC6ku/Ss8Q=
- The joined string is base64 encoded again and string placed in request
Authorization
header:Authorization: BeneAPI dGVzdC51c2VyQHRlc3QuY29tOkZvdGhGV3Z1MEw2eFdBRkpiRkM2a3UvU3M4UT0=
Authorization
Access to resources is authorized in with permissions related to individual entities in the system: users, service pools, directories and callback lists. Permissions are semi-static, usually defined during the integration setup phase where access credentials are created. Usually minimum permissions for the specific need are configured, e.g. allow access to availability statuses of all users in given group for an integration that displays the statuses somewhere.
Permissions are defined as combinations of a string keyword and CRUD (Create, Read, Update, Delete) -flags. They can be specified as relations between users and/or user groups.
Responses
Example of a faulty request made without a Date header:
GET /calls HTTP/1.1
Accept: application/xml
Response received from server.
HTTP/1.1 400 Bad Request
Content-Length: 96
Content-Type: application/xml; charset=utf-8
<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Missing Date
header</string>
Standard HTTP/1.1 response codes are used to return operation status to client. The most commonly used ones are:
Code | Description |
---|---|
200 OK |
Returned when request completes successfully and returns data. |
400 Bad Request |
Returned when request is malformed and is not understood by the server. The client can usually fix this by altering input. |
401 Unauthorized |
Returned when request is unauthorized, meaning that either the request signature was invalid or an inaccessible resource was requested |
404 Not Found |
Returned when specified resource is not found |
500 Internal server error |
Unexpected issues |
Serialization
XML and JSON serializations are supported for both request and response serialization with application/xml
and application/json
as the values. Standard HTTP headers are used to specify formats: Accept
header requests specific response format, Content-Type
header must be used to specify data format when data is sent to the API.
For new development JSON is heavily recommended format. XML is supported for compatibility with existing clients, but will be deprecated and removed at some point.
Accept: application/json
Content-Type: application/json
Additionally, the API supports two JSON flavors. These are referred to as v1
("Legacy Microsoft") and v2
(modern cross-compatible) formats.
The client requests a specific JSON version by specifying HTTP header X-Json-Serializer: 2
. All new development should use the v2
format. v1
is supported for backwards-compatibility, but will be deprecated later.
The differences between the two versions relate to how different data types are handled. The differences are listed below.
Type | v1 | v2 |
---|---|---|
Datetime | ASP.NET JSON /Date(1422850592270)/ |
ISO8601 2022-06-06T12:13:14.567Z |
Dictionary<string, string> | List of Key-Value pairs [{ "Key":"Some key", "Value":"Some value" }] |
JSON object { "Some key": "Some value" } |
TimeSpan (for backwards-compatibility) | ISO8601 duration PT1M20.047S |
Time string "00:01:20.0470000" |
Migrating from v1
to v2
requires the following steps:
- Check the data types returned by endpoints you are using
- Alter the serialization/deserialization for the corresponding properties
Using v2
is supported by all tested serializers out-of-the box, whereas using v1
often required customization. Usually, the migration work is just removing that customization.
Existing clients using v1
that cannot be changed to v2
should send X-Json-Serializer: 1
header with their requests to indicate they need the legacy format. This ensures they remain working once the default behavior changes from v1
to v2
.
Query parameters
Objects are also serialized to query parameters in some use cases. For example when calling /calls/ with [CallFilterParameters
](#callfilterparameters. In these cases the parameter object is serialized as standard query parameters with url-encoded key=value pairs representing object properties. List-type properties are represented as semicolon separated values.
For example an object like:
{ "StartTime": "2018-01-01T00:00:00", "SomeIntValues": [1, 2] }
Would be serialized to query string as:
StartTime=2018-01-01T00:00:00&SomeIntValues=1;2
XML serialization notes
Node ordering
Deserializer expects input XML nodes to be ordered alphabetically ascending by tag name. Nodes in incorrect position are left unhandled.
Valid:
<Item><A>Value></A><B>ValueOfB</B></Item>
Invalid:
<Item><B>ValueOfB</B><A>Value></A></Item>
Lists
Serialized List<User>
<ArrayofUser>
<User />
<User />
</ArrayofUser>
When an operation returns a list, the root node is named ArrayofEntityName
.
Serialized list property inside a container
<SomeContainerEntity>
<Items xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a:guid>09C28FB6-71A1-4E27-AF0F-9F16536FCC77</a:guid>
</RecordingIds>
</SomeContainerEntity>
When a returned entity has list-valued property, it works differently. For example, if a SomeContainerEntity
has a property named Items with value type List>Guid<, it is serialized with property name as root node name and items as children.
For lists of serialized child types, namespace is serialized similarly
<Items xmlns:a="http://schemas.datacontract.org/2004/07/BeneAPI.Entities">
<a:ChildItemType>
<a:Name>Sample key</a:Name>
<a:Value>Sample value</a:Value>
</a:ChildItemType>
</Items>
XML serialization is performed with property name as tag name and content as its content. Lists of items are serialized inside
JSON serialization notes
There are some JSON serialization quirks in used .NET library. These are quite straightforward to work with, but possibly need some attention.
Datetimes
.NET-specific special DateTime format is used for serialization. Milliseconds since Unix epoch with an offset.
ASP.NET JSON date | ISO 8601 |
---|---|
/Date(1422850592270)/ |
2015-02-02T04:16:32.270Z |
/Date(1422850592270+0000)/ |
2015-02-02T04:16:32.270Z |
/Date(1422850592270+0300)/ |
2015-02-02T07:16:32.270Z |
Most deserialization implementations cannot deserialize this format to DateTime automatically, but requires manual offset handling. The format is unfortunate but maintained for backwards-compatibility.
// Sample parser using Newtonsoft Json.Net
using Newtonsoft.Json;
DateTime ParseDotNetJsonDate(string input)
{
DateTimeOffset dto = JsonConvert.DeserializeObject<DateTimeOffset>(input);
DateTime dt = dto.UtcDateTime + dto.Offset;
return dt;
}
// Sample parser using regex
DateTime ParseDotNetJsonDate2(string input)
{
var m = new Regex(@"\\\/Date\((\d+)(?:([+-])(\d\d)(\d\d))?\)")
.Match(input);
return
// From epoch
new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)
.AddMilliseconds(long.Parse(m.Groups[1].Value))
.AddMinutes(
// Offset sign found
m.Groups[2].Success ?
// Sign
int.Parse(m.Groups[2].Value + "1") *
// First 2 digits -> hours
int.Parse(m.Groups[3].Value) * 60 +
// Last 2 digits -> minutes
int.Parse(m.Groups[4].Value)
:
0
);
}
TimeSpans
TimeSpan types are serialized to JSON in ISO8601 duration format. For example, a TimeSpan of 2 minutes and 11 seconds is serialized as:
PT2M11S
Dictionaries
Dictionaries are not serialized as plain objects but as an array of objects with Key and Value.
[{"Key":"Key1","Value":"Value1"}]
Authentication and authorization
POST /authuser
Example log in with password
POST /authuser
Content-Type: application/json
Accept: application/json
{
"UserName":"test.user@test.com",
"Password":"Test123"
}
HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 13:55:39 GMT
{
"CanChangePassword":true,
"CanRecoverPassword":true,
"OrganizationalUnitId":"a5055f5a-51a1-e411-9536-00155d000507",
"Password":null,
"Permissions":null,
"SecretKey":"badkey",
"UserID":"c24a0acb-8fd00c01-e511-874c-00155d000507",
"UserName":"test.user@test.com"
}
Performs a password login for given username. This operation can be used to authenticate end-user clients when deploying SecretKey
via other channels is not practical, for example when creating a generic client that receives credentials as user input. "Log in" is done with password and received SecretKey
is securely stored in client and used to perform the other operations.
Validates credentials provided in body containing an AuthUser entity with UserName
and Password
properties set.
UserName(email) must be set in the content body.
Additional query parameter permissions=1 may be provided to request user permissions information to be included in response.
POST /authuser/{email}
Example log in with password
POST /authuser/test.user@test.com
Content-Type: application/json
Accept: application/json
{
"UserName":"test.user@test.com",
"Password":"Test123"
}
HTTP/1.1 200 OK
Content-Length: 250
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 13:55:39 GMT
{
"CanChangePassword":true,
"CanRecoverPassword":true,
"OrganizationalUnitId":"a5055f5a-51a1-e411-9536-00155d000507",
"Password":null,
"Permissions":null,
"SecretKey":"badkey",
"UserID":"c24a0acb-8fd00c01-e511-874c-00155d000507",
"UserName":"test.user@test.com"
}
This endpoint is deprecated. Use POST /authuser instead.
Performs a password login for given username. This operation can be used to authenticate end-user clients when deploying SecretKey
via other channels is not practical, for example when creating a generic client that receives credentials as user input. "Log in" is done with password and received SecretKey
is securely stored in client and used to perform the other operations.
Validates credentials provided in body containing an AuthUser entity with UserName
and Password
properties set.
UserName must correspond to the one in the URI.
Additional query parameter permissions=1 may be provided to request user permissions information to be included in response.
- Url parameters: {email} - username to authenticate
- Query parameters: none
- Request content: AuthUser
- Response content: AuthUser
PUT /authuser/password
Attempts to change password for a user. UserName(email) must be set in the content body.
- Url parameters: none
- Query parameters: none
- Request content: PasswordChange
- Response content: AuthUser
PUT /authuser/{email}/password
This endpoint is deprecated. Use PUT /authuser/password instead. Attempts to change password for a user.
- Url parameters: {email} - user to change password for
- Query parameters: none
- Request content: PasswordChange
- Response content: AuthUser
POST /authuser/passwordreset
Request a password reset for given user. UserName(email) must be set in the content body.
- Url parameters: none
- Query parameters: none
- Request content: List<PasswordResetVerification>
- Response content: bool - If request was success
Password reset flow
- User navigates to 'Forgot password page'
- Enters username (email)
- If the user has any phone number configured, enters it. Otherwise checks the "no number" box.
Submits
API checks the verification and queues the recovery email to be sent if they are correct
User waits for an email with a link that contains RecoveryToken in the url.
Opens the link in email
Enters username (email)
Enters a new password twice
Submits
PUT /authuser/password is used with RecoveryToken populated instead of the OldPassword
API checks the token and sets the password
POST /authuser/{email}/passwordreset
This endpoint is deprecated. Use POST /authuser/passwordreset instead. Request a password reset for given user.
- Url parameters: {email} - user to reset password for
- Query parameters: none
- Request content: List<PasswordResetVerification>
- Response content: bool - If request was success
GET /authuser/{userid}/permissions
Returns complete permission list for targeted user. Can be only called for current user, attempting to acquire permissions of another user always returns 403 Forbidden. Returns the exact same list that is included in AuthUser structure, but can be called separately and should be preferred over the ?permissions=1 mechanism described under POST /authuser.
AuthUser
Result of a successful "login" with permissions returned alongside the main entity
{
"OrganizationalUnitId": "6b98b72a-5b9c-45a4-9549-d549aad2bab5",
"UserID": "36729336-496c-4d65-99b1-8186f3cd2356",
"UserName": "current.user@test.com",
"SecretKey": "long random string",
"Password": null,
"CanChangePassword": false,
"CanRecoverPassword": false,
"Permissions": [
{
"TargetUser": {
"Id": "74b14bc1-2f08-464a-bd7c-7329ad007c08",
"UserName": "test.user@test.com",
"Email": "test.user@test.com",
"Name": "Test User",
"FirstName": "Test",
"LastName": "User",
"OrganizationID": "acc3ecfc-264a-4d30-a736-3d17797d5a37",
"Settings": null
},
"TargetDirectory": null,
"TargetQueue": null,
"TargetCallback": null,
"KeywordString": "Call",
"Status": {
"Create": null,
"Read": true,
"Update": null,
"Delete": null
}
}
]
}
AuthUser entities are returned when performing a password-based “login”. This can be used to acquire the secret key required for signing all requests, provided the requester knows users configured password. AuthUser entity then contains authentication and authorization related information about the user, like organization id, user id, username, and secret key. Optionally, a list of Permission entities related to the user may be included.
Property name | Data type | Description |
---|---|---|
OrganizationalUnitId | Guid | Organization id of user |
UserID | Guid | Id of User that this AuthUser relates to |
UserName | string | Username |
SecretKey | string | Secret API key for AuthUser, used to sign requests. |
Password | string | User password. Only populated when entity is POSTed for log in. |
CanChangePassword | bool | Whether users are allowed to change their password based on configuration |
CanRecoverPassword | bool | Whether password recovery is allowed based on configuration |
Permissions | List<Permission> | List of Permissions this AuthUser has. Populated if requested. |
PasswordChange
{
"UserName":"test.user@test.com",
"OldPassword":"MyPassword",
"NewPassword":"New, safe and secure password"
}
Password change entity is received by the API to perform a password change on given user.
Property name | Data type | Description |
---|---|---|
UserName | string | Targeted username |
OldPassword | string | Users current password |
RecoveryToken | string | Instead of an old password, provide a one-use recovery token sent off-band to user. Allows resetting the password without knowing the current password |
NewPassword | string | New password to set |
PasswordResetVerification
[
{
"Type":"Phonenumber",
"Value":"+358501234567"
}
]
Password reset entity is received by the API to perform a password reset on given user.
Property name | Data type | Description |
---|---|---|
Type | string | Verification type. Known values {Unknown, Phonenumber} |
Value | string | Verification value e.g +358501234567 |
Permission
Example of a single permission indicating that whoever has this permission can read call information of targeted user
{
"TargetUser": {
"Id": "9db12574-4320-4167-84e5-e37b7c4d5479",
"UserName": "test.user@test.com",
"Email": "test.user@test.com",
"Name": "Test User",
"FirstName": "Test",
"LastName": "User",
"OrganizationID": "8019cdfb-086b-4e48-9547-d80d9b6831b2",
"Settings": null
},
"TargetDirectory": null,
"TargetQueue": null,
"TargetCallback": null,
"KeywordString": "Call",
"Status": {
"Create": null,
"Read": true,
"Update": null,
"Delete": null
}
}
Permission entity represents a single Permission. Permissions are always resolved from acting user to target entity (User, Queue, Directory, CallbackList). It contains target entity, PermissionKeyword and PermissionStatus entity. Only one entity is present for each permission entity.
PermissionKeywords are related to specific resource permissioning and are optionally provided to allow client customization based on available functionality
Property name | Data type | Description |
---|---|---|
TargetUser | User | Targeted user |
TargetDirectory | DirectoryEntity | Targeted directory |
TargetQueue | Queue | Targeted queue |
TargetCallback | CallbackList | Targeted callback list |
KeywordString | string | Permission keyword, indicates what exactly the permission permits |
Status | PermissionStatus | CRUD flags for current entity |
PermissionStatus
{
"Create": null,
"Read": true,
"Update": null,
"Delete": null
}
PermissionStatus is a set of flags Create, Read, Update, Delete, representing the allowed operations relating to the permission.
Property name | Data type | Description |
---|---|---|
Create | bool? | Can create |
Read | bool? | Can read |
Update | bool? | Can update |
Delete | bool? | Can delete |
Impersonation
In some integration cases, it may be necessary a need to communicate with the API as a specific user without requiring the user to fill in their credentials. To enable such use, a high privilege account may be authorized to generate impersonation tokens for specific users. This enables a very simple SSO / IdP style approach in use cases where the integration side has authenticated the user, but that identity cannot be conveniently federated to the API.
The flow on the high level is: - Client connects to the integration side - Client authenticates in a suitable way - Integration side maps the authenticated user to a EnreachAPI user - Integration side acquires an impersonation token from EnreachAPI and passes that to the client - The client proceeds to communicate directly with the API
This behavior is similar to what could be approached using actual SSO with an IdP (such as Azure AD) and our own identity provider. This approach is simpler and does not support any of the finer details, such as refresh tokens, but may be easier to use in integration cases where a full IdP integration is infeasible.
Note that the generated impersonation token is relatively short-lived (in the order of minutes, not hours). Therefore, the integration side must be able to supply a fresh token for the client when appropriate. The actual expiry time can be determined from the expires_in
property in the API response. A fresh token can then be generated before the old one expires.
POST /token/{userid}/impersonate
Request a new impersonation token for given user
- Url parameters: {userid} - targeted user
- Query parameters: none
- Request content: none
- Response content: ImpersonationTokenResult
- Status codes:
- 200 OK - on success
- 403 Forbidden - token generation is not authorized
ImpersonationTokenResult
{
"access_token":"aaaa.bbbb.cccc",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type":"Bearer",
"expires_in":3600
}
Property name | Data type | Description |
---|---|---|
access_token | string | The token itself, should be passed to the client and then the API |
token_type | string | Type of token and the Authorization scheme that should be used with the API calls. This should be passed to the client alongside the token. |
issued_token_type | string | Technical detail related to OAuth compatibility |
expires_in | int | Expiration time in seconds. Can be used to acquire a fresh token before the previous one expires. |
Using the token
When making further API calls, the client may simply include the received token in Authorization header. Note that the token_type
from the incoming payload should be used as Authorization scheme.
GET /users/user-1234/availability
Authorization: Bearer aaaa.bbbb.cccc
When using Bearer token, API returns 401 Unauthorized in case the supplied token is invalid. Additionally, the response body contains string token_invalid
. The client can thus detect that a new token is needed.
User call information
These endpoints return information related to user calls, call recordings and call transcripts. There are two different types of user calls: Direct calls and Service calls (AgentCalls)
Direct calls
Direct calls are incoming calls dialed directly to a user, or outgoing calls made by the user. Direct calls have a special CallPublicity that further limits access. If Direct call is classified as 'private' or 'undefined', only that actual user can access the call information. If the call is classified as 'work', the call information is available to other users having read access to user direct calls.
Service calls (AgentCalls)
There are three types of servicecalls: Incoming QueueCalls, Outgoing QueueCalls and Outgoing CallbackCalls. This endpoint returns service call information from user (agent) perspective. Use /servicecall/, /outbound-servicecall/ and /outbound-callbackcall/ endpoints to retrieve service call information from broader perspective.
Incoming QueueCalls are calls that are allocated to the user from a service queue. Each allocation event creates a separate call event having Result=3 (Allocated). If the user accept the call, a separate call event is created having Result=0 (Answered)'. The same service call (i.e. same callId) can be allocated to user multiple times, each allocation creates a separate user call event.
Outgoing QueueCalls are calls that are made by user in the name of service queue.
Outgoing callback calls are calls that are made by the user for a call list.
Access control
User level calls have three levels of access:
- Call, main information. Shows call details with three last digits of phone numbers masked. Disables querying by phone number
- CallNumbers, number information. Returns unmasked phone numbers instead
- CallRecording, recording information. Allows separately fetching call recording data relating to the calls.
- CallTranscript, transcript information. Allows separately fetching call transcript data relating to the calls.
Permissions are configurable in user level. This means that it is possible to enable an integration account to fetch call information for any subset of all users.
Data update frequency
User call information is updated at roughly 10 second intervals. Calls are exposed over the API only after the call completes and disconnects. This is relevant especially if you acquire information about the existence of a call over another channel (RTE, webhooks) that exposes information about ongoing calls as well.
You can take this into account by delaying the loading of such calls for a short time or by having a mechanism to cover the case where the call is not yet accessible.
GET /calls
Returns a list of user related call events matching filter specified by query parameter.
- Query parameters: CallFilterParameters
- Request content: none
- Response content: List<CallEvent>
GET /calls/{eventId}
Returns a single event specified by call event id.
- Url parameter: {eventId} - id of a specific call event
- Query parameters: none
- Request content: none
- Response content: CallEvent
GET /calls/recordings/{recordingId}
Returns a single CallRecording metadata. Contains information about the recording and the url to actual recording stream. RecordingId corresponds to the ids returned in CallEvent
- Url parameter: {recordingId} - id of a specific recording
- Query parameters: none
- Request content: none
- Response content: CallRecording
GET /calls/transcripts/{transcriptId}
Returns a single CallTranscript. Contains the transcription content. TranscriptId corresponds to the ids returned in CallEvent
- Url parameter: {transcriptId} - id of a specific transcript
- Query parameters: none
- Request content: none
- Response content: CallTranscript
PUT /calls/{eventId}/publicity
Sets the publicity category for the given direct call event id. Agent calls cannot be changed. Call event publicity category can only be changed by the same user that owns the call event regardless of permissions. Can be changed if category is Undefined otherwise the call event timestamp needs to be less than two weeks from the date when change occurs.
- Url parameter: {eventId} - id of a specific call event
- Query parameters: none
- Request content: CallPublicityCategory
- Response content: CallEvent
CallEvent
Default JSON serialization of a CallEvent
[
{
"ANum": "+358123456789",
"BNum": "+358987654321",
"CallID": "2cf79da6-03b8-464d-9a1a-b783f539651c",
"CallTypeString": "DirectCall",
"CallbackListId": null,
"CallbackRequestId": null,
"CanChangeCallPublicityCategory": true,
"Direction": 0,
"Duration": 18,
"EndResult": 0,
"ID": "64f5b73e-6d92-ee11-9944-005056895f22",
"Modified": "\/Date(1701670840717+0000)\/",
"OrgID": "29f6e823-b484-e611-80c9-00505689257e",
"PublicityCategoryId": 0,
"QueueId": null,
"QueueName": null,
"RecordingIds": [
"e5d8d226-6d92-ee11-9944-005056895f22"
],
"Recordings": [
{
"CanRead": true,
"RecordingId": "e5d8d226-6d92-ee11-9944-005056895f22"
}
],
"Transcripts": [
{
"CanRead": true,
"TranscriptId": "e5d8d226-6d92-ee11-9944-005056895f22"
}
],
"TimeStamp": "\/Date(1701670773960+0000)\/",
"UserID": "aa9730c4-ce86-e611-80c9-00505689257e",
"UserName": "user.name@example.com"
}
]
Improved JSON seriialization of a CallEvent (X-Json-Serializer: 2)
[
{
"ID": "64f5b73e-6d92-ee11-9944-005056895f22",
"CallID": "2cf79da6-03b8-464d-9a1a-b783f539651c",
"OrgID": "29f6e823-b484-e611-80c9-00505689257e",
"UserID": "aa9730c4-ce86-e611-80c9-00505689257e",
"UserName": "user.name@example.com",
"TimeStamp": "2023-12-04T06:19:33.96Z",
"Modified": "2023-12-04T06:20:40.7179304Z",
"Direction": 0,
"EndResult": 0,
"Duration": 18,
"ANum": "+358123456789",
"BNum": "+358987654321",
"RecordingIds": [
"e5d8d226-6d92-ee11-9944-005056895f22"
],
"Recordings": [
{
"RecordingId": "e5d8d226-6d92-ee11-9944-005056895f22",
"CanRead": true
}
],
"Transcripts": [
{
"TranscriptId": "e5d8d226-6d92-ee11-9944-005056895f22",
"CanRead": true
}
],
"QueueName": null,
"QueueId": null,
"CallbackListId": null,
"CallbackRequestId": null,
"CallTypeString": "DirectCall",
"PublicityCategoryId": 0,
"CanChangeCallPublicityCategory": true
}
]
Represents a single call event relating to a user. Contains general information about the call, such as time, duration and phone numbers.
Property | Data type | Description |
---|---|---|
ID | Guid | Identifies the unique event |
CallID | Guid | Identifies logical call chain (single call can result in multiple CallEvents, for example if known user calls another known user) |
OrgID | Guid | Identifies organization event belongs to |
UserID | Guid | Identifies the user |
UserName | string | UserName for the UserID, populated automatically |
TimeStamp | DateTime | Call timestamp. Connection time for connected calls, arrival time to system for unanswered |
Modified | DateTime | When the event was created (or last modified, in case the publicity category changes). |
CallTypeString | CallType | Call main type |
Direction | Direction | Call direction |
EndResult | EndResult | Call result. |
PublicityCategoryId | CallPublicityCategory | Call publicity category. |
CanChangeCallPublicityCategory | bool | Defines if the publicity category can be changed. Can be changed if category is Undefined otherwise the call event timestamp needs to be less than two weeks from the date when change occurs. Agent calls cannot be changed. |
Duration | int | Call duration in seconds if answered, 0 if not answered. |
ANum | string | Caller number |
BNum | string | Target number |
Recordings | List<CallEventRecording> | Recording metadata for the call event |
Transcripts | List<CallEventTranscript> | Transcript metadata for the call event |
RecordingIds | List |
List of recording ids that relate to the call. These only include the recordings the user is authorized to access. Obsolete. Prefer Recordings for new development for better authorization support. |
QueueName | string | Allocating queue name for inbound servicecalls, Queue on behalf call was made for outboun queuecalls (only applies to ServiceCall type) |
CallbackListId | Guid? | Callback list id for outbound callbackcalls (only applies to outbound callbackcalls) |
CallbackRequestId | Guid? | Callback request id for outbound callbackcalls (only applies to outbound callbackcalls) |
CallEventRecording
Call recording metadata in relation to a specific call event.
The point of this type is that the existence of a recording related to a call event is considered to be metadata for the call event and not the recording itself. Thus, the presence of the recording should be known if the user is authorized to view the call metadata. This is not the case for the recording itself, which is authorized separately.
This enables exposing the presence of the recording to a user without having to grant the user access to the recording itself. This is useful in many integration cases, where the integration account needs to know that the recording exist but does not actually need to play it back - playback is done with user credentials separately.
Property | Data type | Description |
---|---|---|
RecordingId | Guid? | Id of the recording |
CanRead | bool? | If the current user is authorized to read the recording |
CallEventTranscript
Call transcript metadata in relation to a specific call event.
The point of this type is that the existence of a transcript related to a call event is considered to be metadata for the call event and not the transcript itself. Thus, the presence of the transcript should be known if the user is authorized to view the call metadata.
This enables exposing the presence of the transcript to a user without having to grant the user access to the transcript itself. This is useful in many integration cases, where the integration account needs to know that the transcript exist but does not actually need to fetch it.
Property | Data type | Description |
---|---|---|
TranscriptId | Guid? | Id of the transcript |
CanRead | bool? | If the current user is authorized to read the transcript |
CallRecording
{
"ID": "5f674a0e-9e07-ea11-ae70-645d86a0c4da",
"RecordingID": "5e674a0e-9e07-ea11-ae70-645d86a0c4da",
"CallID": "4e2c3dd5-65b5-40ec-a047-c461ded67425",
"OrgID": "67303a08-9e07-ea11-ae70-645d86a0c4da",
"OrgName": null,
"UserID": "90303a08-9e07-ea11-ae70-645d86a0c4da",
"UserName": null,
"CallbackListId": "05cd939f-d09c-4f6a-ac1b-fc5f63624274",
"ContentType": null,
"ContentLength": "0",
"URL": "recordingstream/5e674a0e-9e07-ea11-ae70-645d86a0c4da.mp3",
"ReasonCollected": "false",
"ReasonFreeTextEnabled" : "true",
"ReasonOptions": [
"Security check",
"Customer support",
"Troubleshooting",
"Just for fun"
],
"Expires": null
}
A single call recording (conversion). A single recording can have many conversions in different formats (mp3, wav, etc.), although in practice there usually exists only one in MP3 format. Contains url to the actual audio stream. Url includes token query string for authorization if token authorization can be made, othwerwise contains plain url. Token is valid for 10 minutes.
Property | Data type | Description |
---|---|---|
ID | Guid | Conversion id |
RecordingID | Guid | Recording ID |
CallID | Guid | Call id recording relates to |
OrgID | Guid | Identifies organization recording belongs to |
OrgName | string | Not in use. |
UserID | Guid? | UserID that owns the recording |
UserName | string | Not in use. |
QueueID | Guid? | Queue that recording relates to |
CallbackListId | Guid? | Callback list recording relates to |
ContentType | string | Not in use. |
ContentLength | long | Not in use. |
URL | string | URL where audio stream can be found |
ReasonCollected | bool? | Indicates if the recording listening reason should be collected. |
ReasonFreeTextEnabled | bool? | Indicates if the recording listening reason allows free text input. |
ReasonOptions | List |
List of the recording listening options that user can select. |
Expires | DateTime? | When recording will expire. If the value is null or DateTime.MaxValue, the recording never expires. |
CallTranscript
{
"ID": "5f674a0e-9e07-ea11-ae70-645d86a0c4da",
"RecordingID": "5e674a0e-9e07-ea11-ae70-645d86a0c4da",
"CallID": "4e2c3dd5-65b5-40ec-a047-c461ded67425",
"OrgID": "67303a08-9e07-ea11-ae70-645d86a0c4da",
"UserID": "90303a08-9e07-ea11-ae70-645d86a0c4da",
"CallbackListId": "05cd939f-d09c-4f6a-ac1b-fc5f63624274",
"DurationMillis": null,
"Expires": null,
"TranscriptStatus": "Completed",
"Phrases": [
{
"ChannelId": 0,
"DurationMillis": 1000,
"OffsetMillis": 1000,
"Confidence": 0.1,
"Text": "Hello",
"Locale": "en-GB"
},
{
"ChannelId": 1,
"DurationMillis": 1000,
"OffsetMillis": 1000,
"Confidence": 0.1,
"Text": "Hello",
"Locale": "en-GB"
}
]
}
A single call transcript that will contain many transcribed phrases.
Property | Data type | Description |
---|---|---|
ID | Guid | Transcript id |
RecordingID | Guid | Recording ID transcript relates to |
CallID | Guid | Call id transcript relates to |
OrgID | Guid | Identifies organization transcript belongs to |
UserID | Guid? | UserID that owns the transcript |
QueueID | Guid? | Queue that transcript relates to |
CallbackListId | Guid? | Callback list transcript relates to |
DurationMillis | int | Total duration in milliseconds. |
Expires | DateTime? | When transcript will expire. If the value is null the transcript never expires. |
TranscriptStatus | string | Transcription status. Possible values. Pending, Completed, Failed. |
Phrases | List<CallTranscriptPhrase | List of the transcript phrases. |
CallTranscriptPhrase
A single transcribed phrase
Property | Data type | Description |
---|---|---|
ChannelId | byte | Channel identifier of conversation. |
DurationMillis | int | Duration in milliseconds. |
OffsetMillis | int | Offset milliseconds. |
Confidence | decimal? | Transcription confidence. |
Text | string | Transcription content. |
Locale | string | Locale of the phrase. |
CallFilterParameters
Specifies allowed query parameters for call search.
Sample of CallFilterParameters serialized to query params (line breaks added for readability).
Requests calls connected between 1.1.2015 06:00 UTC and 1.1.2015 07:00 UTC that belong to user 471D995A-8F56-43FF-98B7-7D750514E9EA and were answered.
GET /calls/?StartTime=2015-01-01+06%3A00%3A00
&EndTime=2015-01-01+07%3A00%3A00
&UserIds=471D995A-8F56-43FF-98B7-7D750514E9EA
&Result=Handled
Requests calls modified between 1.1.2015 06:00 UTC and 1.1.2015 07:00 UTC that belong to user 471D995A-8F56-43FF-98B7-7D750514E9EA. Use ModifiedAfter and ModifiedBefore instead of StartTime and EndTime if you need to sync call records to external system.
GET /calls/?ModifiedAfter=2015-01-01+06%3A00%3A00
&ModifiedBefore=2015-01-01+07%3A00%3A00
&UserIds=471D995A-8F56-43FF-98B7-7D750514E9EA
Requests calls with specific callID. Note that multiple calls events can have the same callID
GET /calls/?CallId=471D995A-8F56-43FF-98B7-7D750514E9EA
Following changes were introduced in version 2023.7.0 (December 2023):
- Time range is limited to 31 days when using
StartTime+Endtime
orModifiedAfter+ModifiedBefore
from version 2023.7.0 (December 2023). - Lookup with
CallId
does not require time range anymore.
Property | Data type | Example query param | Description |
---|---|---|---|
StartTime | DateTime | 2015-01-01+06:00:00 | Start time for queried events. Required (or modified lookup) unless CallId is specified. StartTime+EndTime time range is limited to 31 days. |
EndTime | DateTime | 2015-01-01+07:00:00 | End time for queried events. Required (or modified lookup) unless CallId is specified. StartTime+EndTime time range is limited to 31 days. |
ModifiedAfter | DateTime | 2015-01-01+07:00:00 | Look up events modified after given time. Alternative to start/endtime lookup. ModifiedAfter+ModifiedBefore time range is limited to 31 days. |
ModifiedBefore | DateTime | 2015-01-01+07:00:00 | Look up events modified before given time. Alternative to start/endtime lookup. ModifiedAfter+ModifiedBefore time range is limited to 31 days. |
CallId | Guid | 471D995A-8F56-43FF-98B7-7D750514E9EA | CallId the events should relate to. Enables searching for events in cases where the overall CallId is known, but the exact events that occurred during that call are unknown. Time range is not limited when CallId is defined. |
MaxCount | int | 1000 | Max number of entries to returned. Capped at 50000. |
CallTypeString | CallType | DirectCall | Only specific call type |
Result | List<Result> | Handled | Only calls with specified results |
Direction | Direction | In | Only specified direction |
PublicityCategory | CallPublicityCategory | Private | Only private category calls. |
HasRecording | bool | true | Only calls that have related recording entries |
HasTranscript | bool | true | Only calls that have related transcript entries |
ExternalNumber | string | Calls that have the specified external number. The same parameter works for both incoming and outgoing calls in the same lookup. | |
ANumberMask | string | 35850123 | Anum mask. Deprecated, use ExternalNumber instead. |
BNumberMask | string | 35850456 | Bnum mask. Deprecated, use ExternalNumber instead. |
UserIDs | List |
471D995A-8F56-43FF-98B7-7D750514E9EA | List of semicolon-separated userids to get calls for. Limited to max 5 users from start of the list. |
Order | CallOrderBy | Descending | Sort order for call list |
CallType
Enumeration of call main types.
Name | Value | Description |
---|---|---|
DirectCall | 0 | A call made directly to/by a user. Call event is owned by the user |
ServiceCall | 1 | Calls allocated from service queue to a user or called out on behalf of a service queue or callback list. |
Direction
Enumeration of possible call directions.
Name | Value | Description |
---|---|---|
In | 0 | Incoming calls |
Out | 1 | Outgoing calls |
Result
Enumeration of call end results
Name | Value | Description |
---|---|---|
Handled | 0 | Answered call |
Abandoned | 1 | Unanswered call |
Transferred | 2 | Incoming call that was transferred elsewhere |
Allocated | 3 | Allocated service call from a service pool |
CallPublicityCategory
Enumeration of call publicity category.
Name | Value | Description |
---|---|---|
Undefined | 0 | Undefined category, only user themself can access the call |
Private | 1 | Call is categorized as private call, only user themself can access the call |
Work | 2 | Call is categorized as work call. All servicecalls are automatically categorized as work calls. |
CallOrderBy
Enum describes sort order.
Name | Value | Description |
---|---|---|
Ascending | 1 | Ascending sort order |
Descending | 2 | Descending sort order |
Service call information
Service calls are incoming calls made to service pools. Detailed information about call progress in the system is available via ServiceCallDetail events, while ServiceCall provides high-level information about the overall call.
Access control
Service level calls have three levels of access:
- ServiceCall, main information. Shows call details with three last digits of phone numbers masked. Disables querying by phone number
- ServiceCallNumbers, number information. Returns unmasked phone numbers instead
- ServiceCallDetail, detailed event information. Allows fetching list of ServiceCallDetail events for the call
Permissions are configurable in service pool level. This means that it is possible to enable an integration account to fetch call information for any subset of all service pools. As each service call entry is owned by the service pool the call first arrived to, it is often necessary to target all service pools that can have interaction between them to properly work with overflows, scheduled transfers etc.
Data update frequency
Service call information is updated at roughly 10 second intervals. The information is exposed even when the call is ongoing, but the information can change as long as the call is ongoing. New detail events may appear for the call as long as it remains ongoing, meaning it has Result == Ongoing (0)
.
Once the call completes and disconnects, there will be no further detail events. Also, once the call has been completed (Result != Ongoing (0)
), the result will not change again.
This is relevant if you load new calls frequently. In such case, you need to handle the ongoing calls by reloading them later after the call has completed. Also, if you acquire information about the existence of a call over another channel (RTE, webhooks) that exposes information about ongoing calls as well, handling ongoing calls separately may be necessary.
GET /servicecall
Get all inbound servicecalls in a time range
GET /servicecall/?StartTime=2015-02-01+00%3A00%3A00
&EndTime=2015-02-02+00%3A00%3A00
Returns a list of service call events matching filter specified by query parameter
- Query parameters: ServiceCallFilterParameters
- Request content: none
- Response content: List<ServiceCall>
GET /servicecall/{callId}
Returns information about a specific service call only
- Url parameter: {callId} - id of call
- Query parameters: none
- Request content: none
- Response content: ServiceCall
GET servicecall/{callId}/details
Returns a list of detailed events relating to a single call.
- Url parameter: {callId} - id of call
- Query parameters: none
- Request content: none
- Response content: List<ServiceCallDetail>
GET servivecall/{callId}/metrics
Returns metrics for a single call. Metrics are calculated from the detailed events of the call.
- Url parameter: {callId} - id of call
- Query parameters: none
- Request content: none
- Response content: ServiceCallMetrics
ServiceCall
Header information for a service call. Service calls are calls made to service pools and are represented in more detail than simple CallEvents.
{
"ANum": "+358501231234",
"AnswerQueueId": "C0A7E3FB-56D2-4079-AAE8-25B0630406FD",
"AnswerQueueName": "Support (FI)",
"AnswerTime": "2015-02-02T06:15:27Z",
"AnsweringUserId": "D716DC55-4C78-4CE9-933F-AA9B08E66940",
"AnsweringUserName": "User Name",
"BNum": "+358101231234",
"DisconnectTime": "2015-02-02T06:16:32Z",
"EntryQueueId": "FF2F680F-184F-470A-AF86-D50B8C5B3CC6",
"EntryQueueName": "Switchboard IVR",
"Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
"LastEventTime": "2015-02-02T06:16:32Z",
"LastQueueId": "C0A7E3FB-56D2-4079-AAE8-25B0630406FD",
"LastQueueName": "Support (FI)",
"OrganizationId": "d6838fc1-d649-e211-9c34-005056aa29fb",
"Result": 0,
"Timestamp": "2015-02-02T06:15:01Z",
"Modified": "2015-02-02T06:15:03Z",
"WaitTime": "00:00:25.847"
}
<ServiceCall>
<ANum>+358501231234</ANum>
<AnswerQueueId>C0A7E3FB-56D2-4079-AAE8-25B0630406FD</AnswerQueueId>
<AnswerQueueName>Support (FI)</AnswerQueueName>
<AnswerTime>2015-02-02T06:15:27.03</AnswerTime>
<AnsweringUserId>D716DC55-4C78-4CE9-933F-AA9B08E66940</AnsweringUserId>
<AnsweringUserName>User Name</AnsweringUserName>
<BNum>+358101231234</BNum>
<DisconnectTime>2015-02-02T06:16:32.27</DisconnectTime>
<EntryQueueId>FF2F680F-184F-470A-AF86-D50B8C5B3CC6</EntryQueueId>
<EntryQueueName>Switchboard IVR</EntryQueueName>
<Id>bec058a6-74da-4dc6-8402-74d6a1a02880</Id>
<LastEventTime>2015-02-02T06:16:32.27</LastEventTime>
<LastQueueId>C0A7E3FB-56D2-4079-AAE8-25B0630406FD</LastQueueId>
<LastQueueName>Support (FI)</LastQueueName>
<Modified>2015-02-02T06:15:03.311</Modified>
<OrganizationId>d6838fc1-d649-e211-9c34-005056aa29fb</OrganizationId>
<Result>Answered</Result>
<Timestamp>2015-02-02T06:15:01.183</Timestamp>
<WaitTime>PT25.847S</WaitTime>
</ServiceCall>
Property | Data type | Description |
---|---|---|
Id | Guid | Call identifier |
OrganizationId | Guid | Id of related organization |
Timestamp | DateTime | Call arrival time |
Modified | DateTime | When the entry was created or last modified |
EntryQueueId | Guid? | Id of queue call arrived to |
EntryQueueName | string | Name of queue call arrived to |
AnswerQueueId | Guid? | Id of queue call was last answered from |
AnswerQueueName | string | Name of queue call was last answered from |
LastQueueId | Guid? | Id of the last servicequeue call was allocable to agents |
LastQueueName | string | Name of the last servicequeue call was allocable to agents |
ANum | string | Caller number |
Bnum | string | Called number |
Result | ServiceCallResultType | Call result. |
AnsweringUserId | Guid? | Id user user that last answered the call |
AnsweringUserName | string | Name of user that last answered the call |
AnswerTime | DateTime? | Answering timestamp for the call |
DisconnectTime | DateTime? | Time when call disconnected |
WaitTime | TimeSpan? | Waiting time from connect to first answer for the call |
ServiceCallResultType
Enum describes possible call results.
Name | Value | Description |
---|---|---|
Answered | 0 | Call was answered |
Abandoned | 1 | Call was not answered |
Transferred | 2 | Call was transferred to an external target |
OffSchedule | 3 | Call arrived to a closed service pool and was not handled |
Callback | 4 | A callback request was created from the call |
Ongoing | 1000 | Type for calls that are still ongoing and do not have a defined result yet |
UserRoleInCall
Enum describes the roles a user can be in a single call. Used in ServiceCallFilterParameters.
Name | Value | Description |
---|---|---|
Allocated | 1 | Call was allocated to the specified user(s) at some point during its lifetime |
Answered | 2 | Call was answered by the specified user(s) at some point during its lifetime |
ServiceCallFilterParameters
Filter object used for searching ServiceCalls. Can contain relevant information such as arrival queue, agent role in call etc in addition to basic timestamp-like information. It is serialized as query parameter when making calls to service call resource.
Sample usage, find calls in time range answered by a specific user
?StartTime=2015-02-01+00%3A00%3A00
&EndTime=2015-02-02+00%3A00%3A00
&CallResult=Answered
&UserRole=Answered
&Users=D716DC55-4C78-4CE9-933F-AA9B08E66940
Property | Data type | Example query param | Description |
---|---|---|---|
StartTime | DateTime | 2015-01-01+06:00:00 | Search window start time. Required. StartTime+EndTime time range is limited to 31 days. |
EndTime | DateTime | 2015-01-01+07:00:00 | Search window end time. Required. StartTime+EndTime time range is limited to 31 days. |
ModifiedAfter | DateTime | 2015-01-01+07:00:00 | Look up events modified after given time. Alternative to start/endtime lookup. ModifiedAfter+ModifiedBefore time range is limited to 31 days. |
ModifiedBefore | DateTime | 2015-01-01+07:00:00 | Look up events modified before given time. Alternative to start/endtime lookup. ModifiedAfter+ModifiedBefore time range is limited to 31 days. |
MaxRows | int | 1000 | Max number of entries to returned. Capped at 5000. |
ANumberMask | string | 35850123 | Restrict by caller number mask |
CallResult | List<ServiceCallResultType> | Answered | Limit to specific results |
EntryQueue | List |
Limit to calls that entered to specified queues | |
AnswerQueue | List |
Limit to calls that were answered in specified queues | |
LastQueue | List |
Limit to calls that last entered specified queues | |
UserRole | UserRoleInCall | Allocated | Use in combination with Users to restrict to calls where specified user(s) are in specified role |
Users | List |
||
Order | ServiceCallOrderBy | Descending | Sort order for service call list |
ServiceCallDetail
Sample list of service call detail events for a single call
[
{
"Id": "8232c9d2-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:15.093Z",
"EventTypeId": 1,
"EventType": "CallConnect",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": null,
"userName": null,
"Reason": "ServiceQueue",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "8432c9d2-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:15.297Z",
"EventTypeId": 100,
"EventType": "QueueArrive",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": null,
"userName": null,
"Reason": "ServiceQueue",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "8532c9d2-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:15.343Z",
"EventTypeId": 200,
"EventType": "QueueAllocateUser",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"userName": "User Name",
"Reason": "ServiceQueue",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "8732c9d2-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:19.357Z",
"EventTypeId": 201,
"EventType": "UserAnswer",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"userName": "User Name",
"Reason": "ServiceQueue",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "266376db-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:29.653Z",
"EventTypeId": 410,
"EventType": "WrapUpStarted",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"userName": "User Name",
"Reason": null,
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "276376db-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:29.657Z",
"EventTypeId": 7,
"EventType": "Recording",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"userName": "User Name",
"Reason": "servicequeue",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [
{
"RecordingId": "2c6376db-9d58-ef11-9949-005056895f22",
"CanRead": false
}
],
"Transcripts": [
{
"TranscriptId": "ccefe498-51c1-4eed-dd6d-08dcba9cdc7d",
"CanRead": false
}
]
},
{
"Id": "286376db-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:29.66Z",
"EventTypeId": 2,
"EventType": "CallDisconnect",
"QueueId": null,
"QueueName": null,
"UserId": null,
"userName": null,
"Reason": "",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
},
{
"Id": "315165ed-9d58-ef11-9949-005056895f22",
"CallId": "c30cddf7-951a-4ded-973a-c785c8ac0b65",
"Timestamp": "2024-08-12T11:27:59.763Z",
"EventTypeId": 411,
"EventType": "WrapUpTerminated",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Queue Name",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"userName": "User Name",
"Reason": "timer",
"RecordingId": null,
"TranscriptId": null,
"Recordings": [],
"Transcripts": []
}
]
Detailed step information for a call. A number of these are nested under a single ServiceCall, representing individual steps a call takes inside the system (arrive, get allocated, answered etc.)
Property | Data type | Description |
---|---|---|
Id | Guid | Id of the detail event |
CallId | Guid | Id of the service call event relates to |
Timestamp | DateTime | Event timestamp |
EventTypeId | int? | Event type id. Corresponds to ServiceCallEventType. |
EventType | string | Event type description. Corresponds to ServiceCallEventType. |
QueueId | Guid? | Queue id for the event if applicable |
QueueName | string | Queue name for event if applicable |
UserId | Guid? | User id for the event if applicable |
userName | string | Username for event if applicable |
Reason | string | Reason field, contains technical info string |
RecordingId | Guid? | Id of related CallRecording. |
TranscriptId | Guid? | Id of related CallTranscript. |
Recordings | List<CallEventRecording> | Recording metadata for the call event |
Transcripts | List<CallEventTranscript> | Transcript metadata for the call event |
ServiceCallEventType
Enum describes different event types that ServiceCallDetail events can have. Each type has a Reason field that can contain additional information about the event. The content depends on the event type.
Name | Value | Description | Reason field content |
---|---|---|---|
CallConnect | 1 | Call first connects to the system | ServiceQueue if service queuePersonalWork if direct number of a user |
CallDisconnect | 2 | Call finally disconnects | Various reasonslocal if call was disconnected by call routing componentremote if call was disconnected by a participantsystem technical reason, service shutdown<empty> no specific reason available, e.g agent call count to zero while serving a call |
Recording | 7 | Call recording created | servicequeue if call recording was created for a service queue |
QueueArrive | 100 | Call arrives to queue | ServiceQueue if service queuePersonalWork if direct number of a user |
QueueReject | 101 | Call attempts to enter a queue but is refused | none |
QueueScheduleClosed | 102 | Call is rejected from queue because schedule is closed | ServiceClosed if call was rejected because of normal schedule,AdHoc_X if queue was closed because of AdHoc schedule |
QueueOverflow | 103 | Queue triggers an overflow and logically moves the call onwards | NoAvailableProviders if no agents were available,QueueTimeout if max waiting time elapsed,QueueFull if queue was full |
QueueAllocateUser | 200 | Queue allocates the call to an agent | ServiceQueue if service queuePersonalWork if direct number of a user |
UserAnswer | 201 | Agent answers the call | ServiceQueue if service queuePersonalWork if direct number of a user |
UserDisconnect | 202 | Agent answered call is disconnected | none |
UserReject | 203 | Agent rejects the allocated call | CallDisconnected if call was disconnected,OtherConnected if other agent answered,Timeout if allocation timeout elapsed,UserActivelyDeclined if agent declined incoming call,GenericUserRejected all other reasons |
UserTransfer | 204 | Agent actively transfers the call forward | Target number |
UserPark | 205 | Agent parks the call | none |
UserUnpark | 206 | Agent unparks the call | none |
UserOnHold | 207 | Agent puts the call on hold | none |
UserUnhold | 208 | Agent takes the call off hold | none |
ExtQuery | 250 | Query for external routing information was made | OK if query was successful and routing information was received,NOT_FOUND if query was succesfull, but no routing information received (caller not recognized),FAILED if query failed |
ExtTarget | 251 | External routing target info was received | Semicolon separated list of routing information: pr=<prio>;req=<required>;nbr=<number>; where prio = relative priority (lower is higher priority),required = target is required, i.e wait if target if busy (0/1),number = received target number |
ExtAuthentication | 252 | External authentication for the caller completed. | OK if authentication was successful; otherwise, an error message. |
QueueTransfer | 300 | Queue transfers the call | Target number |
QueueTransferConnect | 301 | Queue transfer connects | Target number |
QueueTransferCancel | 302 | Queue transfer is cancelled | CallDisconnected if call was disconnected before transfer connected,Timeout if timeout elapsed,UserActivelyDeclined if target declined incoming call, GenericUserRejected all other reasons |
SupervisionStatus | 320 | Status of supervision changed event | <status>:<supervisor name> where status is SilentlyListening , Whispering , Participating , Exited , Entered . Supervisor name is the name of the supervisor |
SLStarted | 350 | Queue level Service Level timer started (if the feature is enabled). | Time elapsed vs. the target time configured. Example: 0/60 . |
SLExceeded | 351 | Configured Service Level time exceeded; call is still in the queue. | Time elapsed vs. the target time configured. Example: 60/60 . |
SLAbandoned | 352 | Caller disconnected before the Service Level time was reached. | Time elapsed vs. the target time configured. Example: 35/60 . |
SLReached | 353 | Call answered by an agent before the Service Level time was reached. | Time elapsed vs. the target time configured. Example: 35/60 . |
SLInterrupted | 354 | Call overflowed from the queue to another target before Service Level time. | Time elapsed vs. the target time configured. Example: 35/60 . |
IvrSelection | 400 | Caller has made (DTMF) IVR menu selection or entered some longer collected input | <use case>,<input>,<type> where use case is IVR_MENU if selection was in IVR menu or ALLOC_MENU if selection was during during queueing in servicequeue, input is the DTMF input string, overflowtype is technical type of call control element |
StartBlockingPrompt | 401 | Prompt playing that prevents allocation to agents has been started | MandatoryEnter if queue has mandatory announcement before allocation,Overflow if queue has overflow message,ServiceClosed if queue has service closed message,AdHoc_X if queue has AdHoc message,ExtraService_X if queue has ExtraService message |
WrapUpStarted | 410 | Agent wrap-up time started | none |
WrapUpTerminated | 411 | Agent wrap-up time was terminated | timer if wrap-up time elapsed,manual if agent terminated wrap-up manually before time elapsed |
CallbackCreated | 500 | A callback request was created from the call | Id of the callback list |
ServiceCallOrderBy
Enum describes sort order.
Name | Value | Description |
---|---|---|
Ascending | 1 | Ascending sort order |
Descending | 2 | Descending sort order |
ServiceCallMetrics
Metrics for a single call. Metrics are calculated from the detailed events of the call.
{
"CallId": "71a63a11-287b-4ece-a5b1-0d3ede556234",
"Timestamp": "2024-12-09T12:18:17.47Z",
"TotalDurationMs": 98520,
"TotalWaitTimeFirstAnswerMs": 38957,
"QueueWaitTimeFirstAnswerMs": 28547,
"QueueWaitTimeTotalMs": 28547,
"TotalTalkTimeMs": 39446,
"TotalHoldTimeMs": 20117,
"Answered": true,
"Transferred": false,
"CallbackCreated": false,
"QueueEntries": [
{
"Id": "ac9237ad-27b6-ef11-994c-005056895f22",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"QueueName": "Sales",
"Timestamp": "2024-12-09T12:18:27.88Z",
"QueueWaitTimeMs": 28547,
"QueueTalkTimeMs": 39446,
"QueueHoldTimeMs": 20117,
"ServiceLevelEnabled": false,
"ServiceLevelReached": false
}
],
"UserAllocations": [
{
"Id": "ad9237ad-27b6-ef11-994c-005056895f22",
"UserId": "974bf56b-3811-ec11-9929-005056895f22",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"Timestamp": "2024-12-09T12:18:27.947Z",
"Answered": false,
"UserWaitTimeMs": 3130,
"UserCallTimeTotalMs": 0,
"UserTalkTimeMs": 0,
"UserHoldTimeMs": 0,
"UserWrapUpTimeMs": 0
},
{
"Id": "a5356ab9-27b6-ef11-994c-005056895f22",
"UserId": "aa9730c4-ce86-e611-80c9-00505689257e",
"QueueId": "77c4f037-3811-ec11-9929-005056895f22",
"Timestamp": "2024-12-09T12:18:50.373Z",
"Answered": true,
"UserWaitTimeMs": 6054,
"UserCallTimeTotalMs": 59563,
"UserTalkTimeMs": 39446,
"UserHoldTimeMs": 20117,
"UserWrapUpTimeMs": 0
}
]
}
Name | Data type | Description |
---|---|---|
CallId | Guid | Id of the call |
Timestamp | DateTime | Timestamp of the metrics |
TotalDurationMs | int | Total duration of the call in milliseconds. Time in IVR and mandartory announcements is included |
TotalWaitTimeFirstAnswerMs | int | Total wait time from connect to first answer in milliseconds. Time in IVR and mandatory announcements is included |
QueueWaitTimeFirstAnswerMs | int | Wait time in queue from connect to first answer in milliseconds. Time in IVR and mandatory announcements is not included |
QueueWaitTimeTotalMs | int | Total wait time in queue in milliseconds. Time in IVR and mandatory announcements is not included |
TotalTalkTimeMs | int | Total talk time in milliseconds |
TotalHoldTimeMs | int | Total hold time in milliseconds |
Answered | bool | True if call was answered |
Transferred | bool | True if call was transferred |
CallbackCreated | bool | True if a callback was created from the call |
QueueEntries | List<QueueEntryMetrics> | List of queue entries for the call |
UserAllocations | List<UserAllocationMetrics> | List of user allocations for the call |
QueueEntryMetrics
Metrics for a single queue entry.
Name | Data type | Description |
---|---|---|
Id | Guid | Id of the queue entry |
QueueId | Guid | Id of the queue |
QueueName | string | Name of the queue |
Timestamp | DateTime | Timestamp of the queue entry |
QueueWaitTimeMs | int | Wait time in queue in milliseconds. Time in mandatory announcement is not included |
QueueTalkTimeMs | int | Talk time in queue in milliseconds |
QueueHoldTimeMs | int | Hold time in queue in milliseconds |
ServiceLevelEnabled | bool | True if service level is enabled for the queue |
ServiceLevelReached | bool | True if service level was enabled for the queue and the call was answered before target answer time |
UserAllocationMetrics
Metrics for a single user allocation.
Name | Data type | Description |
---|---|---|
Id | Guid | Id of the user allocation |
UserId | Guid | Id of the user |
QueueId | Guid | Id of the queue |
Timestamp | DateTime | Timestamp of the user allocation |
Answered | bool | True if the user answered the call |
UserWaitTimeMs | int | Wait time for the user in milliseconds |
UserCallTimeTotalMs | int | Total call time from answer to disconnect for the user in milliseconds |
UserTalkTimeMs | int | Talk time for the user in milliseconds |
UserHoldTimeMs | int | Hold time for the user in milliseconds |
UserWrapUpTimeMs | int | Wrap-up time for the user in milliseconds |
Outbound service call information
When a user makes an outbound call, the call is by default considered a user call). In some cases, however, the call is signalled (usually before the call is initialized) to instead be an outbound service call.
There are two types of outbound service calls: Outbound queue calls and outbound callback calls
Outbound queue call
Outbound queue calls are initiated by the user, but are partially taken over by the service queue on behalf of which the call is made. Usually, the agent chooses to call on behalf of a queue, for example to contact customers without exposing their own identity. The process can be automatic as wel depending on configuration.
Outbound queue calls are recorded based on queue configuration, and the resulting call information as well as the recording belong primarily to the queue.
GET /outbound-servicecall
Looks up outbound service calls
- Query parameters: OutboundServiceCallFilter
- Request content: none
- Response content: List<OutboundServiceCall>
GET /outbound-servicecall/{id}
Returns a specific outbound service call by id
- Query parameters: none
- Request content: none
- Response content: OutboundServiceCall
OutboundServiceCall
Outbound service call made on behalf of a queue
{
"Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
"CallId": "85c0f45f-ddae-49bc-adab-023502b41688",
"DisplayNumber": "+4613129399232",
"DurationSeconds": 66,
"QueueId": "ca251a76-73e2-4c3c-96d2-2d61e49b2eaf",
"QueueName": "Support (FI)",
"RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
"TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
"Recordings": [
{
"CanRead": true,
"RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
}
],
"Transcripts": [
{
"CanRead": true,
"TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
}
],
"ResultType": "Answered",
"TargetNumber": "+35810110010",
"Timestamp": "2023-01-01T01:33:55Z",
"Modified": "2023-01-01T01:34:01Z",
"UserId": "66a62777-3785-4744-be15-4c9988457519",
"Username": "some.user@customer.com",
"WaitTimeSeconds": 12
}
Property name | Value type | Description |
---|---|---|
CallId | Guid? | Overall call context this call is part of (there may be multiple individual calls in a call chain) |
DisplayNumber | string | Source number shown when making the outbound call |
DurationSeconds | int? | Number of seconds the user spent talking. Null for unanswered. |
Id | Guid | Id for this individual call |
QueueId | Guid? | Id of the queue on behalf of which the call was made |
QueueName | string | Name of the queue on behalf of which the call was made |
RecordingId | Guid? | Recording id |
TranscriptId | Guid? | Transcript id |
Recordings | List<CallEventRecording> | Recording metadata for the call event |
Transcripts | List<CallEventTranscript> | Transcript metadata for the call event |
ResultType | string | Result type. Refers to OutboundServiceCallResult . |
TargetNumber | string | Number the call targeted |
Timestamp | DateTime? | Call start time |
Modified | DateTime | When the entry was created or last modified. |
UserId | Guid? | Id of the user that actually made the call |
Username | string | Username that actually made the call |
WaitTimeSeconds | int? | Wait time in seconds. Null for unanswered. |
OutboundServiceCallResult
Possible result types for the OutboundServiceCall
Name | Description |
---|---|
Undefined | Undefined result |
Answered | Call was answered |
Abandoned | Call was abandoned = not answered |
OutboundServiceCallFilter
Filter object to be used when looking up outbound service calls
Property name | Value type | Description |
---|---|---|
StartTime | DateTime? | Return calls after given time (inclusive) |
EndTime | DateTime? | Return calls before given time (inclusive). Maximum time window is 7 days |
ModifiedAfter | DateTime | Look up events modified after given time. Alternative to start/endtime lookup. |
ModifiedBefore | DateTime | Look up events modified before given time. Alternative to start/endtime lookup. |
MaxRows | int? | Max number of rows to return. Defaults to 250 if unspecified. Maximum allowed value is 5000 |
TargetNumberMask | String | Search by target number. |
QueueIds | List<Guid> | Return calls made on behalf of the specified queues. At most 10 queues can be specified at a time. |
Result | string | Return calls with specified result. Refers to OutboundServiceCallResult |
UserId | Guid? | Return calls made by the specified user. |
CallId | Guid? | Return calls made by the specified call id. |
Order | OutboundCallOrderBy | Sort order for call list |
Outbound callback call
Outbound callback calls are made to handle a pending callback request. The agent indicates they are calling to handle a specific request, and the call is taken over by the correspoding callback list and its configuration.
Outbound callback calls are recorded based on list configuration. The resulting call information as well as the recording belong primarily to the callback list.
GET /outbound-callbackcall
Searches outbound callback calls
- Query parameters: OutboundCallbackFilter
- Request content: none
- Response content: List<OutboundCallbackCall>
GET /outbound-callbackcall/{id}
Returns a single outbound callback call by id or 404
- Query parameters: none
- Request content: none
- Response content: OutboundCallbackCall
OutboundCallbackCall
{
"Id": "bec058a6-74da-4dc6-8402-74d6a1a02880",
"CallbackListId": "78c79e79-32c7-4a76-9513-6fc5ca0227d6",
"CallbackListName": "Back Office FI",
"CallbackRequestId": "a014b3ba-1569-4798-b699-98b9601fe291",
"CallId": "85c0f45f-ddae-49bc-adab-023502b41688",
"DisplayNumber": "+4613129399232",
"DurationSeconds": 66,
"RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
"TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695",
"Recordings": [
{
"CanRead": true,
"RecordingId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
}
],
"Transcripts": [
{
"CanRead": true,
"TranscriptId": "b21d4e74-c10b-407e-80ed-4eca43b69695"
}
],
"ResultType": "Answered",
"TargetNumber": "+35810110010",
"Timestamp": "2023-01-01T01:33:55Z",
"Modified": "2023-01-01T01:35:22Z",
"UserId": "66a62777-3785-4744-be15-4c9988457519",
"Username": "some.user@customer.com",
"WaitTimeSeconds": 12
}
Outbound call relating to a specific callback item
Property name | Value type | Description |
---|---|---|
CallbackListId | Guid? | Id of the callback list the call related to |
CallbackListName | string | Name of the callback list |
CallbackRequestId | Guid? | Id of the callback request the call related to |
CallId | Guid? | Overall call context this call is part of (there may be multiple individual calls in a call chain) |
DisplayNumber | string | Source number shown when making the outbound call |
DurationSeconds | int? | Number of seconds the user spent talking. Null for unanswered. |
Id | Guid | Id for this individual call |
RecordingId | Guid? | Recording id |
TranscriptId | Guid? | Transcript id |
Recordings | List<CallEventRecording> | Recording metadata for the call event |
Transcripts | List<CallEventTranscript> | Transcript metadata for the call event |
ResultType | string | Result type. Refers to OutboundCallbackCallResult |
TargetNumber | string | Number the call targeted |
Timestamp | DateTime? | Call start time |
Modified | DateTime | When the entry was created or last modified. |
UserId | Guid? | Id of the user that actually made the call |
Username | string | Username that actually made the call |
WaitTimeSeconds | int? | Wait time in seconds. Null for unanswered. |
OutboundCallbackCallResult
Possible result types for the OutboundCallbackCall
Name | Description |
---|---|
Undefined | Undefined result |
Answered | Call was answered |
Abandoned | Call was abandoned = not answered |
OutboundCallbackFilter
Filter object for looking up outbound callback calls
Property name | Value type | Description |
---|---|---|
StartTime | DateTime? | Return calls after given time (inclusive) |
EndTime | DateTime? | Return calls before given time (inclusive). Maximum time window is 7 days |
ModifiedAfter | DateTime | Look up events modified after given time. Alternative to start/endtime lookup. |
ModifiedBefore | DateTime | Look up events modified before given time. Alternative to start/endtime lookup. |
CallbackListIds | List<Guid> | Return calls made for specified callback lists. At most 10 lists can be specified at a time. |
MaxRows | int? | Max number of rows to return. Defaults to 250 if unspecified. Maximum allowed value is 5000 |
Result | string | Return calls with specified result. Refers to OutboundCallbackCallResult |
UserId | Guid? | Return calls made by the specified user |
CallbackListId | Guid? | Return calls made for specified callback list + callback request. Both CallbackListId and CallbackRequestId values are required. |
CallbackRequestId | Guid? | Return calls made for specified callback request + callback list. Both CallbackListId and CallbackRequestId values are required. |
TargetNumberMask | String | Search by target number. |
CallId | Guid? | Return calls made by the specified call id. |
Order | OutboundCallOrderBy | Sort order for call list |
Sample usage, find succesfull outbouncd callbackcalls in time range from specific list
?StartTime=2023-02-01+00%3A00%3A00
&EndTime=2023-02-02+00%3A00%3A00
&Result=Answered
&CallbackListIds=D716DC55-4C78-4CE9-933F-AA9B08E66940
OutboundCallOrderBy
Enum describes sort order.
Name | Value | Description |
---|---|---|
Ascending | 1 | Ascending sort order |
Descending | 2 | Descending sort order |
Queue information
Entities related to service pools/queues, agents attached to them and relevant statuses.
Authorization
Queue entities cannot currently be managed via API, they are read only.
QueueUser entities can be managed and require permissions on both targeted queue and user.
There are two related PermissionKeywords:
- Queue
- Read - View queue and its information
- Update - Update QueueUsers mapped to the queue, in combination with separate QueueUser permission
- Create and Delete are not used
- QueueUser
- Create and Delete are required on target user to add/remove relevant QueueUser entity completely in addition to having Queue Update on target queue
- Read allows reading the entities
- Update allows updating
Priority
andActivity
properties of QueueUser entity
GET /queues
- Url parameters: none
- Query parameters: QueueFilterParameters
- Request content: none
- Response content: List<Queue>
Returns a list of all authorized queues, meaning all queues user has Queue Read permission to.
If OnlyForUser
parameter is specified, requester must have QueueUser Read on target user. Otherwise 401 will be returned.
QueueUser property for Queue entity is not populated in this resource.
QueueFilterParameters
Filter object for queue listing resource.
Name | Type | Description |
---|---|---|
OnlyForUser | Guid? | Return only queues where given user is active |
IncludeUserInactive | bool? | Combined with OnlyForUser , return also queues where user is added but inactive |
IncludeQueueGroups | bool? | Include queue groups attached to the queue. |
GET /queues/{queueid}
- Url parameters: queueid - target queue
- Query parameters: none
- Request content: none
- Response content: Queue
Requires Queue Read permission on targeted queue.
Returns a single queue with QueueUser property populated.
POST /queues/{queueid}/queueusers
- Url parameters: queueid - target queue
- Query parameters: none
- Request content: List<QueueUserUpdate> - queue users to update
- Response content: List<QueueUser> - updated queue users
Updates a collection of QueueUsers received in body. Missing entities are created and existing ones updated.
Requires a Queue Update permission on target queue and QueueUser Create/Update on target users.
DELETE /queues/{queueid}/queueusers/{userid}
- Url parameters:
- queueid - targeted queue
- userid - targeted user
- Query parameters: none
- Request content: none
- Response content: QueueUser - deleted user
Completely removes targeted QueueUser entity.
Requires a Queue Update permission on target queue and QueueUser Delete on target user.
GET /users/{userid}/queues
- Url parameters: userid - targeted user
- Query parameters: UserQueueFilterParameters
- Request content: none
- Response content: List<QueueUser>
From users personal perspective, returns a list of all authorized QueueUser entities for the user.
Requires a QueueUser Read permission on targeted user.
UserQueueFilterParameters
Filter for endpoint returning QueueUser mappings
Name | Type | Description |
---|---|---|
IncludeQueueStatus | bool? | Request that queue status is loaded for returned queues |
IncludeQueueGroups | bool? | Request that queue groups are loaded for returned queues |
POST /users/{userid}/queues
Example updating single queue activity
POST /users/974ae113-5ea1-e411-9536-00155d000507/queues/ HTTP/1.1
Date: 2016-02-12 14:09:57 GMT
Content-type: application/json
Accept: application/json
[{"QueueId":"1F03A1C1-A3AB-E411-9536-00155D000507", "UserId":"974ae113-5ea1-e411
-9536-00155d000507", "Active":true}]
HTTP/1.1 200
Content-Length: 194
Content-Type: application/json; charset=utf-8
Date: Fri, 12 Feb 2016 14:09:38 GMT
[{"Active":true,"AvailabilityEvents":null,"Priority":100,"Queue":null,"QueueId":
"1f03a1c1-a3ab-e411-9536-00155d000507","Status":null,"User":null,"UserId":"974ae
113-5ea1-e411-9536-00155d000507"}]
- Url parameters: userid - targeted user
- Query parameters: none
- Request content: List<QueueUserUpdate>
- Response content: List<QueueUser>
Updates the entire collection of users personal QueueUser entities. Looks at received QueueUser collection, compares them to the existing ones and changes the matching ones. Ones missing from backend are not created, and existing ones missing from input are not deleted.
Requires a QueueUser Update permission on targeted user. No permission on target Queue is required. Does not allow changing Priority
property.
GET /queues/{queueid}/configuration
Returns the QueueConfiguration for given queue.
- Url parameters: queueid
- Query parameters: none
- Request content: none
- Response content: QueueConfiguration
- Response codes:
- 403 Forbidden - When user is not authorized to access the queue
PUT /queues/{queueid}/configuration
Updates the QueueConfiguration for given queue.
- Url parameters: queueid
- Query parameters: none
- Request content: QueueConfiguration - values to update (only non-null fields are updated)
- Response content: QueueConfiguration - updated values
- Response codes:
- 400 Bad Request - When some updated property is invalid
- 403 Forbidden - When user is not authorized to access the queue
GET /queuegroups
Returns list of queue qroups. Returns NotFound if no queue groups exist. If QueueIds is null or empty then no queues are attached to the group.
- Url parameters: none
- Request content: none
- Response content: List<QueueGroup>
[
{
"Name": "Group 1",
"Description": "Description 1",
"QueueIds": [
"9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
]
},
{
"Name": "Group 2",
"Description": "",
"QueueIds": null,
}
]
GET /queuegroups/{groupid}
Returns a queue qroup. Returns NotFound if no queue group exist. If QueueIds is null or empty then no queues are attached to the group.
- Url parameters: none
- Request content: none
- Response content: QueueGroup
{
"Name": "Group 1",
"Description": "Description 1",
"QueueIds": [
"9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
]
}
POST /queuegroups
Creates a new queue qroup. Can be used to create a single group or create a single group and also attach the queues to the group at the same time by giving the queue ids. Returns BadRequest if group cannot be created. Calling user has to have permission to create the group. Does not allow to create a group with existing group name.
- Url parameters: none
- Request content: QueueGroup
- Response content: QueueGroup
{
"Name": "Group 3",
"Description": "Description 3",
"QueueIds": [
"9f8ff7a2-b2c3-4cda-917a-b31815a47d78"
]
}
PUT /queuegroups/{groupid}
Updates a existing queue qroup. Can be used to update a single groups properties and attach the queues to the group by giving the queue ids. If QueueIds is null then no action is taken updating the queues. If QueueIds is empty then queue attachment is cleared. If QueueIds contains ids then queue attachments is cleared and replaced with the new ids. Returns BadRequest if group cannot be updated. Calling user has to have permission to update the group. Does not update a group name to a existing group name.
- Url parameters: none
- Request content: QueueGroup
- Response content: QueueGroup
{
"Name": "Renamed group",
"QueueIds": [
"9f8ff7a2-b2c3-4cda-917a-b31815a47d78",
"5623241e-624f-4b9a-a663-b24bd3735a24"
]
}
DELETE /queuegroups/{groupid}
Deletes a existing queue qroup. Returns BadRequest if group cannot be deleted. Calling user has to have permission to delete the group.
- Url parameters: none
- Request content: none
- Response content: QueueGroup
POST /queuegroups/{groupid}/activate/{userId}
Looks up all the queues in target group that the target user is a member of and activates the user in those queues.
QueueUser.Update permission on target user is required.
- Url parameters:
- groupId - Queue group id
- userId - User to activate
- Request content: none
- Response content: List<QueueUser>
POST /queuegroups/{groupid}/deactivate/{userId}
Looks up all the queues in target group that the target user is a member of and deactivates the user in those queues.
QueueUser.Update permission on target user is required.
- Url parameters:
- groupId - Queue group id
- userId - User to activate
- Request content: none
- Response content: List<QueueUser>
Queue
{
"Status": {
"QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"OngoingCalls": 0,
"QueueLength": 0,
"ActiveAgents": 1,
"FreeAgents": 1,
"MaxWaitTime": 0,
"ServingAgents": 1,
"OpenStatus": 5
},
"TypeId": 4,
"QueueUser": null,
"UsePriorities": true,
"CallAgeBonus": 100,
"Numbers": [
"+358100980900"
],
"OrganizationalUnitId": "7af5db69-d038-4723-9a0b-7db10878fb99",
"Id": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"Name": "Some queue",
"CanUpdate": true
}
Represents a single queue in the system. Contains id, name, numbers and other related information. Also possibly contains a list of attached agents, and a QueueStatus entity.
Property name | Value type | Description |
---|---|---|
Id | Guid | Queue id |
CanUpdate | bool | If current user is authorized to update the queue |
TypeId | int? | Queue type id, technical info. Refers to QueueTypes |
OrganizationalUnitId | Guid | Organization id queue belongs to |
Name | string | Queue name |
UsePriorities | bool | Whether agent priorities are used in the queue when allocating calls |
CallAgeBonus | int | Age bonus applied to incoming calls to the queue. This enables prioritizing calls to specific queues by making them appear "older" than they actually are. The value ranges from 0 to 10k |
Numbers | List<string> | Phone numbers attached to the queue |
Status | QueueStatus | Current queue status |
QueueUsers | List<QueueUser> | List of users attached to the queue |
QueueGroups | List<QueueGroup> | List of groups attached to the queue |
QueueConfiguration
{
"QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"QueueName": "Some queue",
"CanUpdate": true,
"CallAgeBonus": 100
}
DTO for configuring basic properties of a queue
Property name | Value type | Description |
---|---|---|
QueueId | Guid | Queue id. Read only. |
QueueName | string | Queue display name. Read only for now. |
CanUpdate | bool | If current user is authorized to update the entity values |
CallAgeBonus | int | Age bonus applied to incoming calls to the queue.This enables prioritizing calls to specific queues by making them appear "older" than they actually are. The value ranges from 0 to 10k. While reading, the value being null indicates an internal error while processing the priority. It also indicates that the value cannot be updated by clients. |
QueueTypes
Enumeration of possible queue types
Name | Value | Description |
---|---|---|
NA | -1 or null | Missing value |
UserDirect | 1 | Technical queue for handling incoming user calls |
PersonalWork | 2 | Technical queue for handling incoming work number calls |
ServiceQueue | 4 | Normal service queue available to the public |
IvrQueue | 5 | Queue that offers IVR menus, no direct service |
ShortNumber | 6 | Technical queue for short number handling |
Technical | 7 | Technical queue for other technical handling |
QueueStatus
{
"QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"OngoingCalls": 0,
"QueueLength": 0,
"ActiveAgents": 1,
"FreeAgents": 1,
"MaxWaitTime": 0,
"ServingAgents": 1,
"OpenStatus": 3,
"AgentsOnWrapUp" : 0
}
Represents current status of a queue. Displays number of active calls, agents, maximum wait time etc.
Property name | Value type | Description |
---|---|---|
QueueId | Guid | Queue status relates to |
ActiveAgents | int | Count of agents that are Active in the specific queue and are globally receiving service calls. Includes all agents regardless of their away status (=available, short-term way, long-term away) |
ServingAgents | int | Count of agents that are available to receive calls now or "soon". Includes agents that are in a call, in paperwork mode etc. short-term away. |
FreeAgents | int | Count of agents that are available to receive calls right now. Does not include agents that are short-term away (in a call, paperwork, etc.) |
OngoingCalls | int | Number of calls currently ongoing through the queue |
QueueLength | int | Number of queueing callers |
MaxWaitTime | int | Maximum wait time in seconds of calls in the queue |
OpenStatus | int | Queue open status estimation. Refers to QueueOpenStatus enum |
AgentsOnWrapUp | int | Count of agents on wrap-up in the specific queue. |
QueueOpenStatus
Enumeration for QueueStatus.OpenStatus. Status info is rather detailed, representing uncertainness when there is some around due to scripted interactions, dynamic lookups etc.
Name | Value | Description | Default display |
---|---|---|---|
NA | 0 | Unspecified default, information unavailable | None |
NoActiveHandler | 1 | Configuration issues etc, effectively closed | Closed |
NoActiveHandlerUncertain | 2 | Possible configuration issues etc, uncertain | Uncertain |
Closed | 3 | Basic case, queue closed | Closed |
ClosedUncertain | 4 | Advanced case. Queue seems to be closed but all calls are dynamically handled | Uncertain |
Open | 5 | Basic case, queue is open | Open |
OpenUncertain | 6 | Advanced case. Queue seems to be open but all calls are dynamically handled | Uncertain |
QueueUser
{
"Status": {
"Available": true,
"Serving": true,
"Schedule": true,
"Talking": false,
"ParkedCalls": 0,
"CanBeAllocatedTo": true,
"ServiceTerminals": 2
},
"Priority": 500,
"QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"UserId": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
"Queue": null,
"AvailabilityEvents": [
{
"Note": null,
"EndDate": null,
"StartDate": null,
"TransferNumber": null,
"Timestamp": "2016-02-12T07:03:55Z",
"UserID": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
"PresenceTypeID": 0,
"EventSourceCategory": null,
"EventSourceCategoryID": 0,
"EventSource": null,
"EventSourceID": 0,
"TransferTargetID": 0,
"EventTypeID": 0,
"Id": null
}
],
"User": {
"UserName": null,
"Name": "Test User",
"FirstName": null,
"Settings": null,
"OrganizationID": "00000000-0000-0000-0000-000000000000",
"LastName": null,
"Id": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
"Email": "test.user@test.com"
},
"Active": true
}
Represents a queue-user attachment, meaning a single user being attached to a single queue. Contains information related to the attachment, such as activity flag, priority and UserStatus entity.
Delivered containing either QueueId only or also Queue, depending on the point of view of the retrieval operation. When retriveving QueueUsers for a specific user, Queue is set but when retrieving them for a Queue, having full Queue here would be redundant
Property | Value type | Description |
---|---|---|
QueueId | Guid | Id of queue in relationship |
Queue | Queue | Extended queue entity |
UserId | Guid | Id of user in relationship |
User | User | Extended user entity |
Active | bool | If user is actively serving in given queue |
Priority | int? | If queue uses priorities (skill levels), skill level of the user |
Status | UserStatus | Users current status |
AvailabilityEvents | List<AvailabilityEvent> | List of active availability events for the user |
QueueUserUpdate
{
"Priority": 500,
"QueueId": "6f911c1d-7f26-43f5-99c7-d5b0d565a6d5",
"UserId": "d7fc439d-89a4-4df5-a26c-6e5c3b777c38",
"Active": true
}
Represents a queue-user update information.
Property | Value type | Description |
---|---|---|
QueueId | Guid | Id of queue in relationship |
UserId | Guid | Id of user in relationship |
Active | bool | If user is actively serving in given queue |
Priority | int? | If queue uses priorities (skill levels), skill level of the user |
UserStatus
{
"UserId": "82f46bf4-93c1-4336-85ee-3ff472fc2f58",
"Available": true,
"Serving": true,
"Schedule": true,
"Talking": false,
"TalkingStatusChanged": null,
"ParkedCalls": 0,
"CanBeAllocatedTo": true,
"ServiceTerminals": 2,
"WrapUpStart": null,
"WrapUpEnd": null,
"ServingCallback": null,
"ActiveQueueId": null
}
Represents users status from queue components view. Contains information about users serving status, such as talking, available and the ultimate “can receive calls” result.
Property | Value type | Description |
---|---|---|
UserId | Guid | UserId the status relates to |
CanBeAllocatedTo | bool? | Final decision if user can currently receive service calls |
Serving | bool? | If user is currently accepting queue calls at all (Setting Queues_Serving ) |
Talking | bool? | If user is currently in a call, either service or direct |
TalkingStatusChanged | DateTime? | Last time the "Talking" status changed |
Available | bool? | If user availability currently allows allocation |
Schedule | bool? | If user is not in OffWork state. obsolete |
ServiceTerminals | int? | Number of terminals user has available for service calls |
ParkedCalls | int? | Number of parked calls user currently has |
WrapUpStart | DateTime? | The start time for automatic wrap-up timer. Empty when there is no active wrap-up. |
WrapUpEnd | DateTime? | The end time for automatic wrap-up timer. Empty when there is no active wrap-up. |
ServingCallback | bool? | Is user on serving callback. |
QueueGroup
Represents a single queue group in the system. Contains id, name, description. Also possibly contains a list of attached queues.
Property name | Value type | Description |
---|---|---|
Id | Guid? | Queue group id. |
OrganizationalUnitId | Guid? | Organization id queue group belongs to. |
Name | string | Queue group name. |
Description | string | Optional description of the queue group. |
QueueIds | List<Guid> | Queues attached to the group. |
User information
Things related to user-specific functionality.
Authorization
Accessing users is authorized with User.READ
permission. Usually, users have this access to all other users in their organization.
GET /users
Returns a list of all authorized users, optionally filtered by query parameters.
- Url parameters: none
- Query parameters: UserFilterParameters
- Request content: none
- Response content: List<User>
GET /users/{userid}
Returns a single user by id.
- Url parameters: userid - target user
- Query parameters: none
- Request content: none
- Response content: User
User
{
"Id": "74b14bc1-2f08-464a-bd7c-7329ad007c08",
"UserName": "test.user@test.com",
"Email": "test.user@test.com",
"Name": "Test User",
"FirstName": "Test",
"LastName": "User",
"OrganizationID": "acc3ecfc-264a-4d30-a736-3d17797d5a37"
}
User entity represents a single system user. It contains general information about the user, like name, email and id.
Property name | Value type | Description |
---|---|---|
Id | Guid | User id |
Username | string | User login name |
string | User email address. Currently always the same as Username | |
Name | string | User display full name |
FirstName | string | User first name |
LastName | string | User last name |
OrganizationID | Guid | Organization user belongs to |
Settings | void | Unused |
UserFilterParameters
UserFilterParameters is passed as query parameters to user resource to allow searching for users based on given conditions, like emails or organization ids.
Property name | Value type | Description |
---|---|---|
UserEmails | List<string> | User emails to look up. If multiple are specified (max 10), users matching any of the supplied emails are returned |
MaxCount | int? | Max number of entries to return (max 2500). Results are ordered by email. |
Page | int? | The result page to return (0-indexed). Results are ordered by email. |
Availability information
Things related to user availability and terminal status.
- User availability: Is user available for communication or not. Calls does not affect user availability
- Terminal status: Is there ongoing call
Authorization
All resources operate on Availability permission. Operations require read, create, update, delete permissions on targeted user accordingly.
GET /users/{userid}/availability/current
Example result for a user who's currently having lunch
[{
"Note": "Lunch",
"EndDate": "/Date(1455522300000+0200)/",
"StartDate": "/Date(1455520500000+0200)/",
"TransferNumber": null,
"Timestamp": "/Date(1455519988447+0200)/",
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
"PresenceTypeID": 0,
"EventSourceCategory": "User",
"EventSourceCategoryID": 1,
"EventSource": "SomeUI",
"EventSourceID": 2,
"TransferTargetID": 1,
"EventTypeID": 3,
"Id": "59464b6f-c3d3-e511-874c-00155d000507",
"IsActive": true,
"IsUpcoming": false
}]
- Url parameters: userid - targeted user
- Query parameters: AvailabilityFilterParameters
- Request content: none
- Response content: List<AvailabilityEvent>
Returns currently active availability events, optionally filtered by parameters. This is the appropriate endpoint if you only need the user's current availability.
GET /users/{userid}/availability/active
Example result for a user who's currently having lunch and has a meeting later in the afternoon
[{
"Note": "Meeting",
"EndDate": "2016-02-15T12:00:00Z",
"StartDate": "2016-02-15T11:15:00Z",
"TransferNumber": null,
"Timestamp": "2016-02-15T09:23:50Z",
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
"PresenceTypeID": 0,
"EventSourceCategory": "User",
"EventSourceCategoryID": 1,
"EventSource": "SomeUI",
"EventSourceID": 2,
"TransferTargetID": 1,
"EventTypeID": 2,
"Id": "2cd78edc-c5d3-e511-874c-00155d000507",
"IsActive": false,
"IsUpcoming": true
},
{
"Note": "Lunch",
"EndDate": "2016-02-15T09:45:00Z",
"StartDate": "2016-02-15T09:15:00Z",
"TransferNumber": null,
"Timestamp": "2016-02-15T09:06:28Z",
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
"PresenceTypeID": 0,
"EventSourceCategory": "User",
"EventSourceCategoryID": 1,
"EventSource": "SomeUI",
"EventSourceID": 2,
"TransferTargetID": 1,
"EventTypeID": 3,
"Id": "59464b6f-c3d3-e511-874c-00155d000507",
"IsActive": true,
"IsUpcoming": false
}]
- Url parameters: userid - targeted user
- Query parameters: AvailabilityFilterParameters
- Request content: none
- Response content: List<AvailabilityEvent>
Returns currently active and upcoming availability events, optionally filtered by parameters. Use this endpoint only if you require information about the upcoming availabilities as well.
POST /users/{userid}/availability
Example POSTing a new continous OffWork event
POST /users/c24a0acb-8fd1-e511-874c-00155d000507/availability HTTP/1.1
Date: 2016-02-15 10:17:33 GMT
Content-type: application/json
Authorization: BeneAPI dGVzdC51c2VyQHRlc3QuY29tOmcwS01XYUlEZGRWcHZoRE82TFcrZUVNS
URjZz0=
Accept: application/json
{ "Note":"I am gone.", "EventTypeID":3, "EventSource":"Test application", "UserI
D":"c24a0acb-8fd1-e511-874c-00155d000507"}
HTTP/1.1 200 OK
Content-Length: 354
Content-Type: application/json; charset=utf-8
Date: Mon, 15 Feb 2016 10:17:14 GMT
{"EndDate":null,"EventSource":"Test application","EventSourceCategory":"User","E
ventSourceCategoryID":0,"EventSourceID":0,"EventTypeID":3,"Id":null,"Note":"I am
gone.","PresenceTypeID":0,"StartDate":"\/Date(1455531434789)\/","Timestamp":"\/
Date(1455531434805)\/","TransferNumber":null,"TransferTargetID":0,"UserID":"c24a
0acb-8fd1-e511-874c-00155d000507","IsActive":true,"IsUpcoming":false}
- Url parameters: userid - targeted user
- Query parameters: none
- Request content: AvailabilityEvent
- Response content: AvailabilityEvent - created event
Resource for creating new availability events.
EventSource property must specify integrating application's identifier, e.g. CustomCRMClient 0.1.3. This is a free string, but should be identifiable for possible troubleshooting needs.
If created event starts later, StartDate should be specified. If it's meant to begin right away, StartDate should be left null, making the server use current server time instead.
GET /users/{userid}/availability/{eventid}
- Url parameters:
- userid - targeted user
- eventid - target event
- Query parameters: none
- Request content: none
- Response content: AvailabilityEvent
Returns a single availability event by id.
PUT /users/{userid}/availability/{eventid}
- Url parameters:
- userid - targeted user
- eventid - target event
- Query parameters: none
- Request content: AvailabilityEvent - new info
- Response content: AvailabilityEvent - updated info
Updates target event with data from request body.
DELETE /users/{userid}/availability/{eventid}
- Url parameters:
- userid - targeted user
- eventid - target event
- Query parameters: none
- Request content: none
- Response content: AvailabilityEvent - deleted event
Completely deletes target availability event. Generally status should always be changed by POSTing a new availability, as simply deleting target availability can in some cases lead to unexpected resulting states for example with working hours handling.
GET /availability/
- Url parameters: none
- Query parameters: AvailabilityBulkFilterParameters
- Request content: none
- Response content: List<AvailabilityEvent>
Special resource for acquiring AvailabilityEvents for multiple users simultaneously. It can be used in cases where targeted users have been specified via some channel (for example directory synchronization) and live updating is only needed for availability information.
Requires that UserIds
parameter is specified in query parameters.
AvailabilityEvent
Example, implicit available when nothing else is specified
{
"Note": null,
"EndDate": null,
"StartDate": null,
"TransferNumber": null,
"Timestamp": "2016-02-15T09:06:34Z",
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
"PresenceTypeID": 0,
"EventSourceCategory": null,
"EventSourceCategoryID": 0,
"EventSource": null,
"EventSourceID": 0,
"TransferTargetID": 0,
"EventTypeID": 0,
"Id": null,
"IsActive": true,
"IsUpcoming": false
}
Example, 30-minute lunch OffWork availability
{
"Note": "Lunch",
"EndDate": "2016-02-15T09:45:00Z",
"StartDate": "2016-02-15T09:15:00Z",
"TransferNumber": null,
"Timestamp": "2016-02-15T09:06:28Z",
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507",
"PresenceTypeID": 0,
"EventSourceCategory": "User",
"EventSourceCategoryID": 1,
"EventSource": "SomeUI",
"EventSourceID": 2,
"TransferTargetID": 1,
"EventTypeID": 3,
"Id": "59464b6f-c3d3-e511-874c-00155d000507",
"IsActive": true,
"IsUpcoming": false
}
Example active call on a mobile terminal
{
"EndDate": null,
"EventSource": "AVA",
"EventSourceCategory": "Call",
"EventSourceCategoryID": 2,
"EventSourceID": 8,
"EventTypeID": 1,
"Id": "ff3c28d8-00ad-e811-982e-005056aa29fb",
"IsActive": true,
"IsUpcoming": false,
"Note": null,
"PresenceTypeID": 1,
"StartDate": "2018-08-31T09:33:01Z",
"Timestamp": "2018-08-31T09:33:01Z",
"TransferNumber": null,
"TransferTargetID": 1,
"UserID": "c24a0acb-8fd1-e511-874c-00155d000507"
}
Represents a single availability event for user. Contains information such as start and end time and event type (do not disturb, off work, ..). Also includes terminal statuses for user (ongoing call in mobile, MS Teams, etc. terminals).
Property | Value type | Description |
---|---|---|
Id | Guid? | Event identifier |
Timestamp | DateTime | When event was last changed |
UserID | Guid | User event relates to |
EventSourceCategoryID | int | Id of event source category. Refers to EventSourceCategory |
EventSourceCategory | string | Event source category name |
PresenceTypeID | int | PresenceTypeID |
EventSourceID | int | Identifier for a single event source. Technical information |
EventSource | string | Indicates which technical component created the availability. Must be populated when creating new availability events, but is not usually interesting when displaying them to the user. |
EventTypeID | int | Event main type, the most important property. Refers to EventTypeID. |
EventType | string | Event type display name |
StartDate | DateTime? | Event start date. Can be null for implicit events, e.g. an ongoing available status when no explicit availability is defined |
EndDate | DateTime? | Event specified end date. Null end date indicates an ongoing event that is active until explicitly ended. |
Note | string | User-defined event note |
IsActive | bool? | If event is currently active. Makes it easier to handle events when server and client times are not exactly in sync. New in v4.8.0 |
IsUpcoming | bool? | If event is scheduled for later. Makes it easier to handle events when server and client times are not exactly in sync. New in v4.8.0 |
TransferTargetID | int | Deprecated and unused |
TransferTarget | string | Deprecated and unused |
TransferNumber | string | Number incoming calls should be transferred to. Currently unused |
EventTypeID
Base types availability events can describe. These relate to displayed availability, call control etc.
Name | Value | Description | Direct calls offered | Service calls offered |
---|---|---|---|---|
Available | 0 | User is available. If no explicit availability is set, user is considered available | Yes | Yes |
Busy | 1 | Informational busy state, does not affect call control. | yes | yes |
DND | 2 | Do not disturb, blocks incomincg calls | no | no |
OffWork | 3 | User is not working | only calls to mobile number | no |
BRB | 4 | Be right back, does not affect call control. | yes | yes |
Away | 5 | Away, does not affect call control. | yes | yes |
PresenceTypeID
PresenceType tells if availability event is for user availability or terminal status.
Value | Description |
---|---|
0 | User availability, means that the availability is directly affecting the user |
1 | Describes MS Teams terminal state. Can describe that there is a call ongoing in MS Teams terminal in combination with EventSourceCategory Call, or that MS Teams sent an availability change request. |
2 | Mobile terminal state. Describes that there is an ongoing call in mobile terminal in combination with EventSourceCategory Call |
3 | Voip terminal state (Voice for Windows, Voice for Browser, generic hardphone, generic softphone) |
EventSourceCategory
Enumeration specifying valid event source categories.
Name | Value | Description |
---|---|---|
Undefined | 0 | Undefined |
User | 1 | User-created events that directly affect user availability |
Call | 2 | Call-based events, indicate that there is a call in a terminal in combination with PresenceTypeId |
Calendar | 3 | Calendar-based events. Currently unused. |
AvailabilityFilterParameters
?PresenceTypeIds=0
A set of parameters used to filter availability events. Can be passed as query parameter for example to fetch only user-specific status, no terminal statuses.
Property name | Value type | Description |
---|---|---|
PresenceTypeIds | List<int> | Only return events with given presence type ids. Usually used to restrict to type 0 only. |
AvailabilityBulkFilterParameters
?PresenceTypeIds=0,UserIds=11111111-abba-dada-eeff-111122223333
Parameters for querying multiple users availability with a single request
Property name | Value type | Description |
---|---|---|
PresenceTypeIds | List<int> | Only return events with given presence type ids. Usually used to restrict to type 0 only. |
UserIds | List<Guid> | Targeted user ids |
IncludeUpcoming | bool | If upcoming events should be included |
Sample use cases
Sample below describes the returned availability states alongside user actions.
- The user is first in basic Available status with nothing going on
- EventTypeId: 0 -> available
- PresenceTypeId: 0 -> user availability (as opposed to terminal-specific one)
- IsActive: true -> currently active (no need to look at Start/End timestamps)
- They then answer a call on a mobile terminal. User availability remains unchanged, and an additional device call status appears
- EventTypeId: 1 -> busy
- PresenceTypeId: 2 -> describes a mobile call
- EventSourceCategory: "Call" -> ongoing calls have this category
- When the call is ongoing, an integration component (or just as well the user themself) change the user availability to Do not disturb
- POST request returns the created availability only
- Complete availability set then contains an EventTypeId: 2 (Do not disturb) availability in place of the previous Available event
- Call status that appeared in previous step is still there
- After the call ends, call status disappears but Do not disturb status remains
User settings information
Authorization
Authenticated users need to have permission read and update settings on target user. Permissions can be configured to other users as well, so it is possible for a user to manage settings of a completely different user.
There are three levels of permissions required for settings. Each setting is mapped to a single level and read/update rights are enforced accordingly:
- SettingUser - Low level settings. These can usually be both read and updated.
- SettingAdministrator - Medium level settings. These can be both read and updated if authorized.
- SettingSystem - High level settings. These can only be read in any normal configuration.
GET /users/{userid}/settings
Returns a list of settings for a user, optionally filtered by query parameters.
- Url parameters: userid - targeted user
- Query parameters: SettingFilterParameters
- Request content: none
- Response content: List<Setting>
POST /users/{userid}/settings
Updates a collection of setting values for a user. User must have sufficient rights on target user.
- Url parameters: userid - targeted user
- Query parameters: none
- Request content: List<Setting> - desired values
- Response content: List<Setting> - updated values
GET /users/{userid}/settings/{keyword}
Returns a single setting by its keyword.
- Url parameters:
- userid - targeted user
- keyword - target setting keyword
- Query parameters: none
- Request content: none
- Response content: Setting
PUT /users/{userid}/settings/{keyword}
Updates a single setting by keyword.
- Url parameters:
- userid - targeted user
- keyword - target setting keyword
- Query parameters: none
- Request content: Setting - desired new value
- Response content: Setting - updated value
Setting
{
"Keyword": "General_Language",
"Value": "en-GB",
"Level": 1,
"Metadata": {
"AllowedValues": null,
"ValidationRegex": "^$|^[a-z]{2}(-[A-Z]{2})?$"
},
"UserID": "4db76201-946c-47dc-96f5-b0465decb9ae",
"Delete": false
}
Setting represents a single user setting. All user setting are represented as key-value pairs. Specific usage of each setting is described separately. Setting entity contains setting keyword, users configured value, permissioning related SettingLevel, helpful SettingMetadata entity and UserID setting relates to.
Property name | Value type | Description |
---|---|---|
Keyword | string | Setting keyword |
Value | string | Setting value. Null if 'Values' is set. |
Values | Dictionary |
Setting values for advanced setting. Null if 'Value' is set. |
Level | SettingLevel | Setting level for authorization |
Metadata | SettingMetadata | Setting metadata for validation |
UserID | Guid | User this setting instance relates to |
Delete | bool | Deletion request in bulk operations, unused |
SettingFilterParameters
?SettingKeywords=General_Language%3BGeneral_Region
Filter for fetching settings. Allows fetching multiple settings and their values with one request.
Property name | Value Type | Description |
---|---|---|
SettingKeyword | List<string> | List of keywords to return |
SettingMetadata
[{
"AllowedValues": null,
"ValidationRegex": "^$|^[a-z]{2}(-[A-Z]{2})?$"
},
{
"AllowedValues": {
"Switch_On": "1",
"Switch_Off": "0"
},
"ValidationRegex": null
}]
Provides metadata about settings intended value (if applicable), like a list of allowed values or a validation regular expression.
Property name | Value type | Description |
---|---|---|
AllowedValues | Dictionary<string, string> | Allowed values for setting. Key is the display key that can be used for localizations, value is the actual value |
ValidationRegex | string | A regex string used for validating input values |
SettingLevel
Enumeration for setting levels.
Name | Value | Description |
---|---|---|
Undefined | 0 | Undefined, for backwards compatibility |
User | 1 | User level setting |
Administrator | 50 | Administrator level setting |
System | 100 | System level setting |
Relevant settings for integrators
There are many settings used for different things. Integration components do not usually need to care about most of them, unless the integration deals with actually managing all the settings.
Table below describes some commonly usable setting keywords and their intended usage.
Setting | Description | Sample value |
---|---|---|
General_Language | User's preferred UI language and culture as either 2-char language only tag, or 5-char language-region tag | fi-FI |
General_Region | User's Olson timezone | Europe/Helsinki |
General_QuickAvailabilities | List of quick availabilities for user | See Quick availabilities |
Numbering_Number_VoiceMail | User's national voicemail number | +358409207000 |
Numbering_Number_Gsm | User's mobile number in E.164 format | +358501231234 |
Numbering_Number_Work | User's primary work number in E.164 format | +358101231234 |
Whether the language and region configuration should be used or not depends on the use case. For standalone clients or integrations, especially when the user can reasonably recognize that they are using their Enreach account, it usually makes sense to fetch the configuration and apply it. If the API is used as a transparent backend and the information displayed in some other UI, or simply handled in background completely, using them is obviously not necessary.
Quick availabilities
<avs>
<av txt="Free" code="0" dur="" note="" tnum="" />
<av txt="Very busy" code="2" dur="60" note="Do Not Disturb" tnum="+3581231234" />
<av txt="Lunch" code="3" dur="30" note="At lunch" tnum="" />
</avs>
Quick availabilities are pre-defined "one-click" availability activations. They are meant to give users a quick way to activate their most used use cases. Their configuration is provisioned behind the scenes and is read-only over the API.
The configuration is stored and returned as a setting value as XML (not affected by HTTP request's serialization). The XML is a list of individual availabilities. Each element describes the kind of availability event that should be sent by the client to the API when the element is activated.
See sample configuration for the exact format. Availability attributes are defined as follows:
Attribute name | Description |
---|---|
txt | Freetext display name for the selection. This should the text user sees, but should not be sent in the availability event. |
code | Availability code that the selection describes. Match EventTypeID values and goes to EventTypeID property in created event. This should affect the looks of the "button" |
dur | Availability duration in minutes. If empty or missing, the event is created as continuous. If > 0, EndTime should be calculated based on current time and this duration |
note | Freetext Note included in the created availability. This is visible to other's viewing the user |
tnum | TransferNumber , controls where incoming calls should transfer to when the availability is active |
Example quick availability, "go free"
<av txt="Free" code="0" dur="" note="" tnum="" />
Example activation
{
"EventSource":"Test application",
"EventSourceCategory":"User",
"EventTypeID":0,
"PresenceTypeID":0,
"UserID":"4798ebea-ee5f-40f0-b718-a411e8c9e262"
}
Example quick availability, "go free"
<av txt="Very busy" code="2" dur="60" note="Do Not Disturb" tnum="+3581231234" />
Example activation (with pseudo start and end times)
{
"EndDate":"DateTime.UtcNow.AddMinutes(60)",
"EventSource":"Test application",
"EventSourceCategory":"User",
"EventTypeID":2,
"Note":"Do Not Disturb",
"PresenceTypeID":0,
"TransferNumber":"+3581231234",
"UserID":"4798ebea-ee5f-40f0-b718-a411e8c9e262"
}
User status information
These endpoints directly expose UserStatus information.
GET /users/queue-status/{userId}
Returns the current UserStatus for the target user.
Authorized with QueueUser.READ
on the target user.
- Query parameters: none
- Request content: none
- Response content: UserStatus
GET /users/queue-status
Returns UserStatus for all users the requester is authorized to access (max 1000). The response may be further filtered by the UserStatusFilterParameters.
Authorized with QueueUser.READ
.
- Query parameters: UserStatusFilterParameters
- Request content: none
- Response content: List<UserStatus>
UserStatusFilterParameters
Query parameter definitions.
Property | Data type | Example query param | Description |
---|---|---|---|
InQueue | bool? | true | Return users that are attached to any queue |
External services
EnreachAPI has a mechanism to provide users access to other configured services via token-based login urls. Users service bindings are managed in administration interface. Public API provides resources that list available bindings for the user, and to request a login token to specified service.
Externality means that the service is external to EnreachAPI. Other Enreach products such as Reporting are accessed via this mechanism. It can also be used to access other systems that support token-based login.
Normal use case would be to fetch a list of configured services for user. These do not change frequently and should be cached. When a user wants to access one of the systems, the application requests a login link from EnreachAPI and redirects the user to the received address when complete.
GET /authuser/{userid}/services
Request service list:
GET /authuser/12345678-1234-1234-1234-1234567890AB/services
Returns a list of external services that have been configured for the user.
- Url parameter: {userid} - targeted user, must be the authenticated user
- Query parameters: none
- Request content: none
- Response content: List>UserExternalService<
POST /authuser/{userid}/services/{serviceid}/login
Request a login token for a service:
POST /authuser/12345678-1234-1234-1234-1234567890AB/services/47E828C7-9FB2-4FE0-B5D5-7CDA62AD1CCF/login
Generates a token-based login url to the targeted service. The contained url can be used to access the system.
Actual url lifetime and validity depends on the implementing application, but it should be considered rapidly expiring and single-use only unless explicitly noted otherwise.
- Url parameters:
- {userid} - targeted user, must be the authenticated user
- {serviceid} - id of service login is requested for
- Query parameters: none
- Request content: none
- Response content: UserExternalServiceLogin
UserExternalService
{
"ServiceType": 2,
"ServiceId": "47E828C7-9FB2-4FE0-B5D5-7CDA62AD1CCF",
"UserId": "12345678-1234-1234-1234-1234567890AB",
"ServiceUsername": "anything",
"ServiceName": "Reports",
"Information": {
"BrowsingMode": "Embed"
}
}
A single user-service binding entity.
Property | Data type | Description |
---|---|---|
ServiceId | Guid | Service identifier |
ServiceType | int | Service technical type. Determines the SSO mechanism used. UIs and integrations do not usually need to do anything with this. |
ServiceRole | int? | Service role in organization. Used for marking services implementing some default behavior of environment in an external system. Used to auto-manage the bindings when provisioning users as well as auto-generate UI features based on the services provided by specific services. When value is null, service is not used in any default product role. |
ServiceName | string | User-visible name for the service. |
ServiceUsername | string | Users username in target service. Normally not relevant. |
UserId | Guid | Id of user binding is configured for |
Information | ExternalServiceInformation | Extra information about user binding |
Values for ServiceType
are:
- 2 - Legacy Qlik mechanism
- 3 - Generic JWT signed by the API
- 4 - A generic plain link with no built-in SSO
- 5 - LADesk / HelpDesk mechanism
- 7 - Qlik Sense token-based mechanism
Value for ServiceRole
are:
- 1 - Reporting system
- 2 - External helpdesk
- 4 - External knowledge base
- 5 - Voice Monitor
- 6 - External Omnihub UI
- 7 - External management Portal
ExternalServiceInformation
Class providing extra usage information about UserExternalService.
Property | Data type | Description |
---|---|---|
BrowsingMode | BrowsingMode | Some external services need browser extensions, unsupported in embedded browser controls in client. This property indicates if services should be opened in embedded or external browser |
BrowsingMode
Enumeration for possible BrowsingMode values
Value | Description |
---|---|
Undefined | Undefined, default value. No preference. |
Embed | Should be embedded |
Browser | Should be opened in an actual browser |
UserExternalServiceLogin
{
"LoginUrl": "https://reports.enreach.com/login/?token=1234"
}
A single login url container.
Property | Data type | Example value | Description |
---|---|---|---|
LoginUrl | string | https://reports.enreach.com/ login/?token=1234 | Absolute login url that the user can open and get direct access to target service |
Directory information
Stuff related to directory information. An organization can have several directories for different use cases (internal users, external partners etc).
Authorization
Directories are permissioned with one permission, Directory. Read flag indicates that user has permission to read directory and its contents. Create/Update/Delete flags refer to directory entries, granting manipulation rights:
- Create - Can create new non-technical entries to directory
- Update - Can update existing entries
- Delete - Can delete non-technical entries from directory
Technical entries are entries that correspond to a user or a queue in the system. Some of the properties of these entries are automatically managed, and cannot be updated manually. Similarly these entries cannot be directly deleted.
Non-technical entries are informational entries created to the directory for convenient access.
GET /directory
Returns all authorized directories without their contents.
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: List<Directory>
GET /directory/{directoryid}
Returns a single directory including its contents. If no explicit filtering is applied, first 25 entries are returned.
- Url parameters: directoryid - targeted directory
- Query parameters: DirectoryFilterParameters - filter object to search with
- Request content: none
- Response content: Directory
GET /directory/{directoryid}/entries/{entryid}
Returns a single directory entry by id from given directory.
- Url parameters:
- directoryid - id of directory entry is in
- entryid - id of specific entry
- Query parameters: none
- Request content: none
- Response content: DirectoryEntry
POST /directory/personal
Creates presonal directory.
POST /directory/entries/search
Search entries from all/specified directories with given parameters.
- Url parameters: none
- Query parameters: none
- Request content: DirectoryFilterParameters - parameters to search with
- Response content: List<DirectoryEntry> - search results
POST /directory/{directoryid}/entries
Create a new entry to target directory
- Url parameters:
- directoryid - id of target directory
- Query parameters: none
- Request content: DirectoryEntry - new entry
- Response content: DirectoryEntry - created entry
PUT /directory/{directoryid}/entries/{entryid}
Updates targeted entity with provided content.
- Url parameters:
- directoryid - id of directory entry is in
- entryid - id of specific entry
- Query parameters: none
- Request content: DirectoryEntry - new data
- Response content: DirectoryEntry - updated data
DELETE /directory/{directoryid}
Deletes given directory. The directory must be owned by a user (personal directory).
- Url parameters: directoryid - target directory
- Query parameters: none
- Request content: none
- Response content: Directory - deleted directory
DELETE /directory/{directoryId}/entries/{directoryEntryId}
Deletes entry from a given directory.
- Url parameters:
- directoryid - target directory
- entryid - id of specific entry for deletion
- Query parameters: none
- Request content: none
- Response content: DirectoryEntry - deleted entry
DELETE /directory/{directoryId}/entries
Deletes all entries from given directory
- Url parameters:
- directoryid - target directory
- Query parameters: none
- Request content: none
- Response content: List<DirectoryEntry> - deleted entries
Directory
{
"SourceId": "Generated:DAL",
"Name": "Default",
"OrganizationalUnitId": "e9403282-18f3-4922-8b8f-1221b2f1e8fb",
"ID": "6a15ddb8-e272-4699-9e0c-fc4881dc83d3",
"Entries": null
}
Represents an entire directory, containing its id, name, source information and possibly a list of DirectoryEntries.
Property name | Value type | Description |
---|---|---|
ID | Guid | Id |
Name | string | Display name |
Default | bool | If the directory is a default system-generated directory or a custom one |
SourceId | string | Free-form source id, can be customized if full directories are imported from an external source |
OrganizationalUnitId | Guid | Organization directory belongs to |
Entries | List<DirectoryEntry> | Related entries |
DirectoryEntry
{
"MobileNumber": "+358501231234",
"Group": "Deployment",
"FirstName": "Test",
"City": "Helsinki",
"LastName": "User",
"Location": "HQ",
"Department": "Production",
"Id": "701da8d3-08a3-4b87-96a0-caf3d2fe73be",
"Email": "test.user@test.com",
"OtherNumber": "",
"Description": "Some test user",
"Subcompany": "Spinoff",
"Company": "Customer",
"Title": "Master",
"UserId": "01881619-fcf2-452c-a449-7d6474cf840f",
"ProfileImageUrl": null,
"Address": "",
"Superior": "",
"WorkNumber": "+358101231234",
"CustomFields": [
{
"Key": "Field 1",
"Value": "Value 1"
},
{
"Key": "Custom field 2",
"Value": "Value 2"
}
],
"Country": "Finland",
"Modified": "2015-12-10T09:22:21Z",
"ExternalId": null,
"Team": "",
"PostalCode": "",
"DirectoryId": "f24a6afe-f26e-45cf-9ded-60bf87e50cff",
"Availabilities": [],
"EntryType": 1,
"Substitute": ""
}
Represents a single entry in a directory. Contains many fields to store different kinds of user/service pool/other information, such as organization structure (company, subcompany, location etc.), title, substitute, phone numbers etc. Can also include current availability status if the entry is related to a system user.
Protected column indicates that the property cannot be updated for technical entries.
Searched column indicates if query is targeted when searching for entries. Always means that it is always searched always, req means that it is only searched when QueryAllFields parameter is set. Empty value means that it is not searched at all.
Property name | Value type | Max Length | Description | Protected | Search |
---|---|---|---|---|---|
Id | Guid | - | Entry id | Yes | |
DirectoryId | Guid | - | Directory entry belongs to | Yes | |
EntryType | int? | - | Entry type | Yes | |
UserId | Guid | - | Id of the technical entity, either Queue or User depending on EntryType | Yes | |
ExternalId | string | - | External correlation id for imported entries | ||
string | 100 | Email address | Yes | Always | |
FirstName | string | 100 | Yes | Always | |
LastName | string | 100 | Yes | Always | |
PhoneticName | string | 200 | Phonetic name | Req | |
Description | string | 1000 | Free description field | Req | |
Title | string | 100 | Always | ||
WorkNumber | string | 100 | Related work number | Yes | Always |
MobileNumber | string | 100 | Mobile number | Yes | Always |
OtherNumber | string | 100 | Other custom number | Req | |
Company | string | 100 | Company name | Req | |
Subcompany | string | 100 | Always | ||
Location | string | 100 | Always | ||
Department | string | 100 | Always | ||
Group | string | 100 | Req | ||
Team | string | 100 | Req | ||
Superior | string | 100 | Req | ||
Substitute | string | 100 | Req | ||
Address | string | 100 | Req | ||
PostalCode | string | 100 | Req | ||
City | string | 100 | Req | ||
Country | string | 100 | Req | ||
ProfileImageUrl | string | 100 | Url to users profile image, if set | Yes | |
Modified | DateTime | - | When the entry was last modified | ||
Availabilities | List<AvailabilityEvent> | - | List of current availability events for the entry, if it corresponds to a user | ||
CustomFields | Dictionary<string, string> | Key: 100, Value: 1000 | Extra CustomFields information. |
CustomFields special handling
There is some special treatment for following custom field keys
Key | Description |
---|---|
PersonStatus | Value is displayed in Voice for Windows directory listing instead of 'Title'. This can be used if there is need to show status of 3rd party system for a contact. |
Entry types
Type | Description |
---|---|
null | Treated the same as 3 |
1 | User entry, refers to a technical user in the system |
2 | Service pool, technical queue in the system |
3 | Other, user-created entry |
DirectoryFilterParameters
?AvailabilityTypes=0
&MaxCount=30
&Query=Test%3BUser
&QueryAllFields=True
A set of parameters used to filter fetched directory entities. Contains freeform string parameters matched against all available fields. It is also possible to fetch specific availability types for entries representing users, allowing bulk-retrieval of device and user availability. Also implements paging.
Property name | Value Type | Description |
---|---|---|
AvailabilityTypes | List<int> | Availability types to fetch. Refers to PresenceTypeIds (0, 1, 2) = terminals |
EntryTypes | List<int> | Return only specific entry types. Refers to DirectoryEntry.EntryType (1, 2, 3). |
MaxCount | int? | Maximum number of entries to return |
Page | int? | Requested page number |
Query | List<string> | Query terms to search with. Each term must match. |
UserId | Guid? | Searches entry for a specific user |
Number | string | Phone number to search with. Exact matches number fields |
QueryAllFields | bool? | If search should target all fields or only the default subset |
DirectoryIds | List<Guid> | Directory ids to search (when applicable) |
Unsplit, "User name" is used as search term
Query=User+name
Split, "User" and "name" are used as individual terms that must both match but individually.
Query=User%3Bname
Profile image handling
Resource provides access to managing user profile image. Profile image itself is stored in user’s personal directory entry in company main directory. This resource provides operations for adding a new image and deleting an existing one.
PUT /users/{userid}/profileimage
Accepts a binary stream of image data intended for use as user profile image. Supported formats are jpg, png and gif. Content length can be at most 2MB (by default, may vary).
- Url parameters: {userid} - targeted user, must be the authenticated user
- Query parameters: none
- Request content: Data stream
- Response content: UserProfileImage
DELETE /users/{userid}/profileimage
Deletes whatever image currently set for target user
- Url parameters: {userid} - targeted user, must be the authenticated user
- Query parameters: none
- Request content: none
- Response content: none
- Response code:
- 204 No content – User profile image was successfully deleted
- 401 Unauthorized – Not allowed to delete image for target user
- 404 Not found – No image found to delete
UserProfileImage
Property | Data type | Description |
---|---|---|
ImageUrl | string | Absolute url to profile image |
Communication
GET /users/{userid}/communication/sms/rights
Example SMS check
GET /users/974ae113-5ea1-e411-9536-00155d000507/communication/sms/rights
- Url parameter: {userid} - user input is related to
- Query parameters: none
- Request content: none
- Response content: SmsRights describing what is allowed.
A resource for checking if current user is generally allowed to send SMS.
Checks user configuration and returns a SmsRights with CanSend = true if sending is possible.
POST /users/{userid}/communication/sms
Example SMS sending
POST /users/974ae113-5ea1-e411-9536-00155d000507/communication/sms
{
"TargetNumber": "+358501231234",
"SourceNuber": "+358404004000",
"SmsText": "This is the message to send"
}
- Url parameter: {userid} - user input is related to
- Query parameters: none
- Request content: SmsInput
- Response content: SmsReply created based on input
- Response codes:
- 200 OK – Body was accepted and a send request created (this does not guarantee that the SMS was actually successfully sent)
- 400 Bad Request - Invalid data, or unauthorized target (international numbers can be prohibited etc)
- 403 Forbidden - Configuration does not allow sending messages
A resource for sending text messages via SMS gateway provider(s) used by Enreach infrastructure.
Receives SMS send request, verifies that user has rights to send the SMS generally, and specially to the target number’s country code, possibly rejecting messages to service numbers.
Sent SMS are billed from the specified SourceNumber
.
SmsInput
Example message object
{
"TargetNumber": "+358501231234",
"SourceNuber": "+358404004000",
"SmsText": "This is the message to send"
}
Describes the SMS message to be sent.
Property | Data type | Description |
---|---|---|
TargetNumber | string | Target number. Must be in normalized E.164 format, starting with + and country code. |
SourceNumber | string | Optional. Must match user’s mobile or work number. If not provided the mobile number is used, otherwise the work number. |
SmsText | string | Message text to send. Maximum total of resulting SMS messages (160 characters, special characters may take more than one space) must be 5 or less. |
SmsReply
Example response when sending was successful
{
"OK": true,
"ErrorDesc": null,
"Error": null
}
Result for sms sending request
Property | Data type | Description |
---|---|---|
OK | bool | If true the message was sent forward. |
Error | string | Freeform error reason. |
ErrorDesc | string | Possible extra information about the error. |
SmsRights
Example response when sending is allowed
{
"CanSend": true,
"NamedSourceNumbers": [
{
"key": "Numbering_Number_Gsm",
"value": "+44720337390"
},
{
"key": "Numbering_Number_Work",
"value": "+441946765512"
},
{
"key": "Internal Team (+599182366704262)",
"value": "+599182366704262"
}
],
"SourceNumbers": [
"+44720337390",
"+441946765512",
"+599182366704262"
]
}
Response object to sms rights request
Property | Data type | Description |
---|---|---|
CanSend | bool | If user can generally send sms |
NamedSourceNumbers | List<KeyValuePair<string, string>> | Valid numbers to be used as SourceNumber, with localizable friendly name for each. Keys are localizable names, values are the actual numbers. |
SourceNumbers | List<string> | Valid numbers to be used as SourceNumber. Kept for backwards-compatibility, NamedSourceNumbers property should be preferred. |
Callback information
Entities related to callback lists and individual callback requests.
Each customer can have a number of CallbackLists, which collect individual callback requests.
Each request can have a number of CallbackAttempts. These describe individual attempts to handle the request. Once an attempt with Close type is created, request is treated as closed and is not returned in default listings.
Authorization
There are three relevant permissions that can be applied per callback list.
- CallbackList
- Read - View the list
- CallbackRequest
- Read - View list contents
- Update - Update list content items
- Delete - Delete list content items
- CallbackRequestAttempt
- Create - Create new attempts
- Read - View attempts in list items
- Update - Update attempts in list
- Delete - Delete attempts
Permissions are usually applied in three "preset roles":
- Read only
- Read only access to target list
- CallbackList Read, CallbackRequest Read, CallbackAttempt Read
- User access
- Read CallbackList
- Read+Update CallbackRequest
- Allows updating request info, but cannot entirely delete it
- Read+Create CallbackAttempt
- Allows logging callback attempts, but cannot modify or delete existing ones
- Manager access
- Read CallbackList
- Read+Update+Delete CallbackRequest
- Like user, but can also delete requests if needed
- Create+Read+Update+Delete CallbackAttempt
- Like user, but can also edit logged attempts and delete them if necessary
GET /callbacks
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: List<CallbackList>
Get all authorized callback lists. Contained requests are not returned.
GET /callbacks/{listid}
- Url parameters: listid - target list
- Query parameters: CallbackFilterParameters
- Request content: none
- Response content: CallbackList
Gets a single list by id. Includes contained CallbackRequests that match given filter. Returns at most 250 requests.
GET /callbacks/{listid}/requests
- Url parameters: listid - target list
- Query parameters: CallbackFilterParameters
- Request content: none
- Response content: List<CallbackRequest>
Returns filtered requests from target list. Preferred way to fetch list content, when information about the list itself is not required.
POST /callbacks/{listId}/requests
- Url parameters: listid - target list
- Query parameters: none
- Request content: CallbackRequest - request to create
- Response content: CallbackRequest - created request
Create a new callback request.
POST /callbacks/{listId}/requests/batch
- Url parameters: listid - target list
- Query parameters: none
- Request content: List<CallbackRequest> - requests to create
- Response content: List<CallbackRequest> - created requests
Creates multiple requests with one call. At most 100 requests are accepted in one batch.
Batch is handled atomically - if any single request is invalid or fails for some reason, the entire batch is discarded and error message returned.
Sample mini-batch with possible input values
<ArrayOfCallbackRequest>
<CallbackRequest>
<AssignedUserId>7713b808-b45f-e611-80c9-00505689257e</AssignedUserId>
<ChannelIn>Channel name</ChannelIn>
<ContactMessage>Contact message</ContactMessage>
<ContactName>Contact name</ContactName>
<ContactNumber>+358501231234</ContactNumber>
<DueDate>2017-10-30T06:00:00</DueDate>
<ExtraInformation xmlns:a="http://schemas.datacontract.org/2004/07/BeneAPI.Entities">
<a:CallbackRequestExtra>
<a:Name>Sample key</a:Name>
<a:Value>Sample value</a:Value>
</a:CallbackRequestExtra>
</ExtraInformation>
<RequestTypeId>3</RequestTypeId>
</CallbackRequest>
</ArrayOfCallbackRequest>
GET /callbacks/{listid}/requests/{requestid}
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: none
- Response content: CallbackRequest
Gets a single request by id. Includes related CallbackAttempts.
PUT /callbacks/{listid}/requests/{requestid}
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: CallbackRequest
- Response content: CallbackRequest
Updates targeted callback request with content from request body.
DELETE callbacks/{listid}/requests/{requestid}
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: none
- Response content: CallbackRequest - deleted request
Deletes targeted callback request completely. This is unusual, intended way is to close the request by POSTing a new Close callback attempt.
POST /callbacks/{listId}/requests/{requestId}/auto-assign
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: none
- Response content: CallbackRequest - auto-assigned request with updated data
- Response codes:
- 200 OK - request assigned successfully
- 409 Conflict - request already assigned to another user, the client should not proceed
Executes configured behavior for assigning the request to the calling agent.
Always assigns the issue to the agent, unless it is assigned to someone already which returns 409 Conflict.
Depending on list configuration, may automatically create a nested CallbackAttempt of type InProgress. It is used to ensure that whenever a call is initiated for this request, it is transitioned correctly regardless of what the agent taps in the UI.
Depending on list configuration, the returned CallbackRequest item may also have the ClientAutoClose boolean set to true. If this is the case, the client should automatically close the item after the agent completes the initiated call.
GET /callbacks/{listid}/requests/{requestid}/attempts
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: none
- Response content: List<CallbackAttempt>
Returns all attempts relating to given request
POST /callbacks/{listid}/requests/{requestid}/attempts
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: CallbackAttempt - item to create
- Response content: CallbackAttempt - created attempt
Creates a new callback attempt under target request.
GET /callbacks/{listid}/requests/{requestid}/attempts/{attemptid}
- Url parameters:
- listid - target list
- requestid - target request
- attemptid - target attempt
- Query parameters: none
- Request content: none
- Response content: none
Returns a single specified callback attempt.
PUT /callbacks/{listid}/requests/{requestid}/attempts/{attemptid}
- Url parameters:
- listid - target list
- requestid - target request
- attemptid - target attempt
- Query parameters: none
- Request content: CallbackAttempt - item to create
- Response content: CallbackAttempt - created attempt
Updates a single attempt.
DELETE /callbacks/{listid}/requests/{requestid}/attempts/{attemptid}
- Url parameters:
- listid - target list
- requestid - target request
- attemptid - target attempt
- Query parameters: none
- Request content: none
- Response content: CallbackAttempt - deleted attempt
Completely deletes target callback attempt.
GET /callbacks/{listid}/users
- Url parameters:
- listid - target list
- Query parameters: none
- Request content: none
- Response content: List<CallListMember>
Returns all bindings relating to given callbacklist. Requires CallListManage READ permission for the given target list.
GET /callbacks/{listid}/users/{userid}
- Url parameters:
- listid - target list
- userid - target user
- Query parameters: none
- Request content: none
- Response content: CallListMember
Returns a binding relating to given callbacklist and user. Requires CallListManage READ permission for the given target list.
Example Example JSON serialization of a CallListMember
{
"ListId": "4ad13bbd-82e5-4f5f-a898-7a5af35684fd",
"ListName": "Test list",
"UserId": "e272c88b-febd-4136-86b8-34ac854bc0b9",
"UserName": "test.user@test1.org",
"Active": "false",
"Modified": "2019-08-15T13:34:45.9160524Z"
}
GET /callbacks/{listid}/users/available
- Url parameters:
- listid - target list
- Query parameters: none
- Request content: none
- Response content: List<CallListMember>
Returns all members that can be binded to given callbacklist. Requires CallListManage READ permission for the given target list.
PUT /callbacks/{listid}/users/{userid}
- Url parameters:
- listid - target list
- userid - target user
- CallListMember - updated list
- Query parameters: none
- Request content: none
- Response content: CallListMember
Creates or updates the binding relating to given callbacklist and user. Requires CallListManage UPDATE permission for the given target list.
Example usage with APIClient
CallListMember entity = new CallListMember()
{
UserId = AuthUser.UserID,
ListId = callbackList.Id,
Active = "true"
};
Client.PutCallbackListUser(entity);
DELETE /callbacks/{listid}/users/{userid}
- Url parameters:
- listid - target list
- userid - target user
- Query parameters: none
- Request content: none
- Response content: CallListMember
Deletes a binding relating to given callbacklist and user. Requires CallbackCallListManage UPDATE permission for the given target list.
GET /callbacks/status
- Url parameters: none
- Query parameters: CallbackListStatusFilterParameters
- Request content: none
- Response content: List<CallbackListStatus>
Get all authorized callback lists status. Does not populate list members.
If OnlyForUser
parameter is specified, requester must be the target user. Otherwise 401 will be returned.
GET /callbacks/{listid}/status
- Url parameters: listid - target list
- Query parameters: none
- Request content: none
- Response content: CallbackListStatus
Gets a single authorized list status by id. Populates list members.
POST /callbacks/auto-allocation-request
- Url parameters:none
- Query parameters: none
- Request content: none
- Response content: CallbackRequest - allocated request
- Response codes:
- 200 OK - request allocated successfully
- 404 NotFound - if no request to allocate
Returns and allocates next best callback request for the user. When client enables callbacklist serving user setting it should then request a callback using this endpoint for user to handle. If client receives 404 NotFound and user's callbacklist serving is enabled it should periodically check using this endpoint if request is found for handling. If user's availability changes to DND or OffWork client should skip the periodic checking until availability changes to other than DND or OffWork.
POST /callbacks/{listId}/requests/{requestId}/reject
- Url parameters:
- listid - target list
- requestid - target request
- Query parameters: none
- Request content: none
- Response content: CallbackRequest - rejected request with updated data
- Response codes:
- 200 OK - request rejected successfully
- 409 Conflict - request is not assigned to the calling agent
Executes for rejecting the request to the calling agent. If it is not assigned to the calling agent, returns 409 Conflict. When a callback request is allocated to the client then a user should have a possibility to reject the callback. If user rejects the callback then the client should also disable the callbacklist serving user setting as well.
GET /callbacks/me/requests
- Url parameters: none
- Query parameters: CallbackFilterParameters
- Request content: none
- Response content: List<CallbackRequest>
Returns all callback requests or empty list to calling agent from all allowed callbacklists where agent is attached. CallbackFilterParameters parameters is used for filtering.
CallbackList
{
"CallbackRequests": null,
"Id": "e272c88b-febd-4136-86b8-34ac854bc0b9",
"OrganizationID": "581cb1f7-c51b-44cd-8bfa-8197fdacae94",
"Name": "Callback list 1"
}
A single list containing callback requests. A customer can have any number of these for different use cases.
Property name | Value type | Description |
---|---|---|
Id | Guid? | List identifier |
OrganizationID | Guid? | Organization list belongs to |
Name | string | List display name |
CallbackRequests | List<CallbackRequest> | Relevant callback requests |
CallbackRequest
{
"CallbackAttempts": [
{
"UserName": "Test User",
"Timestamp": "2017-10-13T13:36:20Z",
"UserId": "11112234-4444-5555-6666-999988887777",
"Note": "",
"CallbackRequestId": "e934c1ee-4798-e711-80ce-00505689257e",
"CallbackAttemptType": 0,
"CallbackListId": null,
"Id": "7e74e87e-1bb0-e711-80ce-00505689257e"
},
{
"UserName": "Test User",
"Timestamp": "2017-10-13T13:35:35Z",
"UserId": "11112234-4444-5555-6666-999988887777",
"Note": "",
"CallbackRequestId": "e934c1ee-4798-e711-80ce-00505689257e",
"CallbackAttemptType": 3,
"CallbackListId": null,
"Id": "f791e963-1bb0-e711-80ce-00505689257e"
}
],
"Id": "379e0408-c18c-4707-8ba3-6d201d245c63",
"CallbackListId": "00000000-0000-0000-0000-000000000000",
"ContactName": "Sample user",
"ContactNumber": "+358501231234",
"ContactMessage": "Sample topic",
"Note": null,
"AssignedUserId": "11112234-4444-5555-6666-999988887777",
"ChannelIn": "Asiakasrekisteri",
"AssignedUserName": null,
"ClosingTime": "2017-10-13T13:36:20Z",
"CreationTime": "2017-09-13T05:53:56Z",
"CallbackAttempCount": 0,
"LastAttemptType": 3,
"LastAttemptDatetime": "2017-10-13T13:36:20Z",
"LastAttemptNote": "",
"RecordingId": null,
"TranscriptId": null,
"RequestTypeId": 1,
"DueDate": null,
"CallId": null,
"ClassificationId": "3373786f-7e98-e711-80ce-00505689257",
"CalculatedPriority": "000.0194831041.0194786461.0194831101",
"RelatedItems": [
{
"Id": "0916d9af-0ffb-e911-ae63-645d86a0c4da",
"ListId": "00000000-0000-0000-0000-000000000000",
"IsClosed": false,
"StatusId": null
}
]
"ExtraInformation": [
{
"Name": "Random extra info snippet 1",
"Value": "Foo"
},
{
"Name": "Additional extra info",
"Value": "Bar"
}
]
}
<CallbackRequest xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<AssignedUserId>11112234-4444-5555-6666-999988887777</AssignedUserId>
<CallbackAttempCount>2</CallbackAttempCount>
<CallbackAttempts>
<CallbackAttempt>
<CallbackAttemptType>0</CallbackAttemptType>
<CallbackRequestId>e934c1ee-4798-e711-80ce-00505689257e</CallbackRequestId>
<Id>7e74e87e-1bb0-e711-80ce-00505689257e</Id>
<Note/>
<Timestamp>2017-10-13T13:36:20.6790188</Timestamp>
<UserId>11112234-4444-5555-6666-999988887777</UserId>
<UserName>Test User</UserName>
</CallbackAttempt>
<CallbackAttempt>
<CallbackAttemptType>3</CallbackAttemptType>
<CallbackListId i:nil="true"/>
<CallbackRequestId>e934c1ee-4798-e711-80ce-00505689257e</CallbackRequestId>
<Id>f791e963-1bb0-e711-80ce-00505689257e</Id>
<Note/>
<Timestamp>2017-10-13T13:35:35.3283518</Timestamp>
<UserId>11112234-4444-5555-6666-999988887777</UserId>
<UserName>Test User</UserName>
</CallbackAttempt>
</CallbackAttempts>
<CallbackListId>e52923da-cf2b-e611-80c9-00505689257e</CallbackListId>
<ChannelIn>Customer registry</ChannelIn>
<ClassificationId>11112234-7e98-e711-80ce-00505689257e</ClassificationId>
<ClosingTime>2017-10-13T13:36:20.6790188</ClosingTime>
<ContactMessage>Sample topic</ContactMessage>
<ContactName>Sample user</ContactName>
<ContactNumber>+358501231234</ContactNumber>
<CreationTime>2017-09-13T05:53:56.583494</CreationTime>
<DueDate>2017-10-12T21:00:00</DueDate>
<ExtraInformation xmlns:a="http://schemas.datacontract.org/2004/07/BeneAPI.Entities">
<a:CallbackRequestExtra>
<a:Name>Random extra info snippet 1</a:Name>
<a:Value>Foo</a:Value>
</a:CallbackRequestExtra>
<a:CallbackRequestExtra>
<a:Name>Additional extra info</a:Name>
<a:Value>Bar</a:Value>
</a:CallbackRequestExtra>
</ExtraInformation>
<Id>11112234-4798-e711-80ce-00505689257e</Id>
<LastAttemptDatetime>2017-10-13T13:36:20.6790188</LastAttemptDatetime>
<LastAttemptNote/>
<LastAttemptType>CloseSuccessful</LastAttemptType>
<LastAttempUserId>11112234-4444-5555-6666-999988887777</LastAttemptType>
<LastModifiedUserId>11112234-4444-5555-6666-999988887777</LastModifiedUserId>
<Modified>2017-10-13T13:36:20.6849841</Modified>
<Note i:nil="true"/>
<RecordingId i:nil="true"/>
<TranscriptId i:nil="true"/>
<RequestTypeId>3</RequestTypeId>
<CalculatedPriority>000.0194831041.0194786461.0194831101</CalculatedPriority>
<RelatedItems xmlns:a="http://schemas.datacontract.org/2004/07/BeneAPI.Entities">
<a:CallbackRequestRelatedItem>
<a:Id>0916d9af-0ffb-e911-ae63-645d86a0c4da</a:Name>
<a:IsClosed>False</a:Value>
<a:StatusId>Null</a:Value>
</a:CallbackRequestRelatedItem>
</RelatedItems>
</CallbackRequest>
A single callback request. Contains information about the client that left the request, like name, email and phone number.
Property name | Value type | Description |
---|---|---|
Id | Guid? | Request identifier |
CallbackListId | Guid? | Callback list request belongs to |
RequestTypeId | byte? | Request type. Refers to CallbackRequestType |
ContactName | string | Name of related contact |
ContactNumber | string | Contact phone number |
ContactMessage | string | Contract freeform message |
Note | string | Internal note about the request |
AssignedUserId | Guid? | Assigned user id |
AssignedUserName | string | Username of assigned user. Deprecated, not populated automatically. |
DueDate | DateTime? | When request is due |
ExpiryDate | DateTime? | When request expires |
ChannelIn | string | Channel request came from (queue number dialled..) |
CreationTime | DateTime? | When the request was created |
Modified | DateTime? | When request was last modified |
NotBefore | DateTime? | Do not handle this before this time |
HandleAllocatedBefore | DateTime? | Start handling before this time. Only with "auto-allocation-request" endpoint. |
MaxAllocatedTimeSec | int? | Maximum seconds the autoallocated request may be unhandled (call out not started) before it may be alloceted to someone else. |
AllocationReferenceTime | DateTime? | Timestamp set by the server when the allocation was done. For helping synchronizing when the HandleAllocatedBefore elapses in client time (in case clocks do not match) |
ClosingTime | DateTime? | Calculated value when request was closed, based on container attempts |
CallbackAttemptCount | int? | Number of relevant callback attempts |
LastAttemptType | CallbackAttemptType? | Last attempt type |
LastAttempUserId | Guid? | Last attempt user id |
LastAttemptDateTime | DateTime? | Timestamp of last callback attempt |
RecordingId | Guid? | Id of related call recording |
TranscriptId | Guid? | Id of related call transcript |
CallId | Guid? | Call id request was generated from (if available) |
CallbackAttempts | List<CallbackAttempt> | Relevant callback attempts |
ExtraInformation | List<CallbackRequestExtra> | Extra information |
Unassign | bool? | Request that the request be unassigned. Used for partial PUT updates |
DueDateDelete | bool? | Request that due date should be cleared. Used for partial PUT updates. |
ExpiryDateDelete | bool? | Used in updates to clear expiry date |
TriggerNotifications | bool? | Used when creating (or manipulating) the request. Used to instruct that the operation should trigger any configured notifications (notify list owner, assigned user etc). Notification logic is configured separately for targeted call list. This flag only instructs that the checks should be done. If no notifications have been configured, none will be sent even if this flag is set. Do not assume that notifications are bundled - each modification with this trigger on will send a message to configured targets. Generally this should only be used when the item is created to avoid excess messaging. |
ClientAutoClose | bool? | Used when calling the auto-assign endpoint for a request. If set to true, the client should skip the "what happened to the call" phase after the agent completes a call regarding this request and automatically mark the item successfully closed instead. |
LastModifiedUserId | Guid? | Id of the user that made the last modification to the request. This value is null when system has made the modification. |
CalculatedPriority | string | Calculated priority string that can be used to sort the callback requests. When ordering by Ascending the lowest priority item will be first on the list and when ordering by Descending the highest priority item will be first on the list. |
RelatedItems | List<CallbackRequestRelatedItem> | All related callback requests. |
DefaultTagSchemaId | Guid? | Id of the tag schema that is binded for this request. Id is null if tag schema binding is not found. |
CallbackRequestExtra
{
"Name": "Sample key",
"Value": "Some value"
}
Custom extra data for callback. Simple key-value pairs with no semantic meaning.
Property name | Value type | Description |
---|---|---|
Name | string | Property name |
Value | string | Property value |
CallbackAttempt
{
"Id": "919b8447-b110-457c-a6d7-c8940040774e",
"CallbackListId": "00000000-0000-0000-0000-000000000000",
"CallbackRequestId": "00000000-0000-0000-0000-000000000000",
"UserId": "22870c14-f08e-4276-82d8-5e030bdc3617",
"UserName": "test.user2@test.com",
"Timestamp": "2016-02-15T13:34:45.9160524Z",
"CallbackAttemptType": 3,
"Note": "Did not answer"
}
An attempt to fulfill the callback request. Contains information about whether the attempt was succesfull, and if not, why it failed (call went to voicemail etc).
Property name | Value type | Description |
---|---|---|
Id | Guid? | Attempt id |
CallbackListId | Guid? | List related request belongs to |
CallbackRequestId | Guid? | Request attempt belongs to |
UserId | Guid? | User that created the attempt |
Timestamp | DateTime? | Attempt timestamp |
CallbackAttemptType | CallbackAttemptType | Attempt type |
Note | string | User-provided note |
CallbackFilterParameters
?SelectedCallbackRequestStatusString=Opened
&LastAttemptTypesString=Busy
Filter object used to search for callback requests with varied criteria.
Property name | Value type | Description |
---|---|---|
MaxCount | int? | Maximum number of events to return. Max 250 requests. |
PageNumber | int? | Page number for paging |
ContactNameOrNumber | string | Contact name/number search string |
ContactMessage | string | Search string for contact message |
ChannelIn | string | Search string for ChannelIn |
StartDate | DateTime? | Created after given time |
EndDate | DateTime? | Created before given time |
DueDateBefore | DateTime? | Where due date is set and is before given value |
DueDateAfter | DateTime? | Where due date is set and is after given value |
DueDateMissing | bool? | Where due date is not set |
ExpiryBefore | DateTime? | Where expiry date is before given date |
ExpiryAfter | DateTime? Where expiry date is after given date | |
ExpiryMissing | bool? | Where expiry date is not set |
ModifiedBefore | DateTime? | Where item was modified before given value |
ModifiedAfter | DateTime? | Where item was modified after given value |
RequestTypes | List<byte> | If set, return only requests of given types. Correspond to CallbackRequestType |
AssignedTo | Guid? | Filter requests assigned to specific user by id |
AssignedToUsername | string | Filter requests assigned to specific user by username |
Order | string | Order requests by 'creationtime' (default), 'calculatedpriority' |
SelectedAssignmentStatusString | string | Events in selected status only. Multiple assigment statuses can be given by using comma separation for status strings e.g Unassigned,AssignedToMe |
SelectedCallbackRequestStatusString | string | Events in selected statuses only |
LastAttemptTypesString | List<string> | Requests with specified types as last type |
CallbackAttemptType
Types of attempts that can be created. Different meanings for reporting/informational use, two main logical types (closing and not closing).
Name | Value | Description |
---|---|---|
Unknown | -1 | Unknown value |
CloseSuccessful | 0 | Closes request, handled successfully |
CloseUnsuccessful | 1 | Closes request, was not handled |
Busy | 2 | Contact was busy |
NoAnswer | 3 | Contact did not answer |
OtherAnswered | 4 | Voicemail, switchboard or some other target answered |
Other | 5 | Other unspecified |
Noattempts | 6 | No attempts have been made. Used for filtering requests. |
CloseExpired | 7 | Closes request, expired |
CallbackRequestType
Different types for callback requests
Name | Value | Description |
---|---|---|
Unknown | 0 | Unknown value. Provided for backwards compatibility, should be disregarded |
Callback | 1 | Callback item |
Overflow | 2 | Overflow item |
CallList | 3 | Call list item |
Any | 50 | Symbolic "any". Requests cannot actually be this type, used for filtering |
CallbackRequestStatus
Possible statuses callback request can be in. Used for searching.
Name | Value | Description |
---|---|---|
Unknown | -1 | Unknown value |
Opened | 0 | Request is open, waiting to be handled |
SuccessfullyClosed | 1 | Request was closed as successful |
UnsuccessfullyClosed | 2 | Request was closed as unsuccessful |
ExpiredClosed | 3 | Closed as expired |
CallbackRequestRelatedItem
{
"Id": "0916d9af-0ffb-e911-ae63-645d86a0c4da",
"IsClosed": "false"
"StatusId": "null"
}
Single callback request relation.
Name | Value | Description |
---|---|---|
Id | Guid? | Related request id. |
ListId | Guid? | Related request list id. |
IsClosed | bool? | If the related request is already closed. |
StatusId | int? | Last attempts raw status id. Null if no last attempt. |
AssignmentStatus
Name | Value | Description |
---|---|---|
Unknown | -1 | Unknown value |
Unassigned | 0 | Unassigned |
AssignedToSomebody | 1 | Assigned to someone |
AssignedToMe | 2 | Assigned to calling user |
CallListMember
{
"ListId": "4ad13bbd-82e5-4f5f-a898-7a5af35684fd",
"ListName": "Test list",
"UserId": "e272c88b-febd-4136-86b8-34ac854bc0b9",
"UserName": "test.user@test1.org",
"UserFullName": "Test User",
"Active": "true",
"Status": null,
"Modified": "2019-08-15T13:34:45.9160524Z"
}
A single entry containing callback list user.
Property name | Value type | Description |
---|---|---|
ListId | Guid? | CallbackList identifier |
ListName | string | CallbackList name. Display only. |
UserId | Guid? | User identifier |
UserName | string | Username (email). Display only. |
UserFullName | string | Users full name. Display only. |
Active | bool? | Indicates if user is active in the callback list. |
Status | UserStatus | Users current status. |
Modified | DateTime? | Read-only information when entry is last modified. |
CallbackListStatusFilterParameters
?OnlyForUser=e272c88b-febd-4136-86b8-34ac854bc0b9
Filter object used to search for callback lists status with varied criteria.
Property name | Value type | Description |
---|---|---|
OnlyForUser | Guid? | Return only lists status where given user is serving. |
CallbackListStatus
{
"ListId": "4ad13bbd-82e5-4f5f-a898-7a5af35684fd",
"OrganizationId": "e4ffa825-cbb7-4386-a178-ffee5eba48da",
"ListName": "Test list",
"IsAutoAllocate": "true",
"TotalOpenRequests": "1",
"TotalFreeForAllocation": "2",
"TotalAssigned": "0",
"TotalHidingNotBefore": "0",
"NextHourRevealedNotBefore": "0",
"TotalOverDueDate": "0",
"NextHourOverDueDate": "0",
"TotalActiveAgents": "0",
"TotalAutoAllocateAgents": "0",
"TotalServingAgents": "1",
"TotalServingAutoAllocateAgents": "0",
"ExpiresIn24h": "0"
}
A single entry containing callback list status.
Property name | Value type | Description |
---|---|---|
ListId | Guid? | CallbackList identifier |
OrganizationId | Guid? | Organization list belongs to |
ListName | string | CallbackList name. Display only. |
Members | List<CallListMember> | Call list members. |
IsAutoAllocate | int | If the CallbackList is AutoAllocate list |
TotalOpenRequests | int | Total number open unhandled requests |
TotalFreeForAllocation | int | Total number of requests that can be allocated |
TotalAssigned | int | Total number of requests that are currently assigned to an agent |
TotalHidingNotBefore | int | Total number of requests that are not allocable due NotBefore has not elapsed |
NextHourRevealedNotBefore | int | Total number of requests that will be allocable during next hour |
TotalOverDueDate | int | Total number of requests that are already over DueDate |
NextHourOverDueDate | int | Total number of requests that will be past DueDate during next hour |
TotalActiveAgents | int | Total "Active" ("checked" in the list, not necessary serving) agents in the queue. |
TotalAutoAllocateAgents | int | Total number of Agents "Active" and "Serving_CallbackLists" |
TotalServingAgents | int | Total number of agents having "Serving_CallbackLists" = 1 |
TotalServingAutoAllocateAgents | int | Total immediately AutoAllocable agents. Agent must be "Active" and "Serving_CallbackLists", and the list must be "IsAutoAllocate" |
ExpiresIn24h | int | Number of requests that will expire today |
Classification
This part describes schemas and operations for collecting classification data about various entities, such as calls and call list items.
Basic idea is that TagSchema
s describe "templates" for classification. It is
a simple description of a UI that the user must traverse and input necessary
information. The schemas can be managed over the API, but are usually read-only
for integration cases and used as-is.
Basic integration would read available schemas for the active user, cache them for a time and render classification forms when needed.
Individual classification instances are created and managed in separate endpoints.
Various things can be classified. Usually they relate to calls or call list items, but it's not a technical requirement. For call classification, however, the client should be aware of Core CallId for the call. This can be acquired in various ways (SIP signalling, GET /callmanagement/legs) and then included in ClassificationInstance.
Another important bit of information is QueueId, when the intention is to classify service calls (as is usually the case). This can be acquired similarly to CallId. It is used for deciding which tag schema to use for each call. TagSchemas have QueueUsage entries, which define ids of the actual queues that should have their allocated calls classified.
Example UI
Below is an example rendering of the same schema that is described in JSON below. The example is captured from Enreach Voice web view. Shown things:
- From group Topic a single tag Billing is selected
- As tag Billing is selected, a second group hidden by default Billing (
Hidden: true
) is shown. This is configured by tag Billing havingShowGroup: 4
. If no tag showing a hidden group is selected, then the group should remain hidden. - Additional group Customer status is shown as second. It is configured to only
allow a single selection (
MaxSelections: 1
), so Customer is selected and Prospect greyed out.
The data collected here would be sent as a ClassificationInstance described further down in the document.
Other remarkable things not shown in the example are:
TagGroup
being collapsed (Collapsed: true
). This means that it's name should be displayed in the UI but contained tags are hidden by default. Tags are shown by "tapping" the group name (or other mechanism applicable in the implemented UI)TagGroup
requiring a selection (MinSelections > 0
). This means that the form should not be submittable before there at least the required number of selections made from among the group's tags.- Min/max selections should not be enforced for
Hidden: true
groups that have not been made visible. When they are visible, restrictions must be applied. - Min/max selections must be applied for
Collapsed: true
groups even if they have not yet been expanded. UI must indicate that the user is expected to expand the group and make a selection, if the configuration requires.
GET /classification/schemas
Example request for all schemas with children (groups and tags) included. Useful for getting full configuration in one call and caching it.
GET /classification/schemas?IncludeChildren=true
[{
"CallbackListUsages": [
{
"ListId": "34cff92f-be52-4ec5-8d5a-2103630d152b",
"RequestTypeId": 50
}
],
"Name": "Sample classification",
"Modified": "2017-06-02T06:21:15Z",
"ManualUsage": false,
"Groups": [
{
"Name": "Topic",
"MaxSelections": 0,
"Tags": [
{
"Name": "Billing",
"Style": 3,
"ShowGroup": 4,
"Id": 19
},
{
"Style": 1,
"Id": 20,
"Name": "Feedback"
},
{
"Style": 1,
"Id": 21,
"Name": "Inquiry"
},
{
"Style": 1,
"Id": 22,
"Name": "Support request"
}
],
"Collapsed": false,
"MinSelections": 0,
"Order": 0,
"Hidden": false,
"Id": 5
},
{
"Name": "Customer status",
"MaxSelections": 1,
"Tags": [
{
"Style": 1,
"Id": 23,
"Name": "Customer"
},
{
"Style": 1,
"Id": 24,
"Name": "Prospect"
}
],
"Collapsed": false,
"MinSelections": 1,
"Order": 1,
"Hidden": false,
"Id": 6
},
{
"Name": "Billing",
"MaxSelections": 0,
"Tags": [
{
"Style": 5,
"Id": 18,
"Name": "No"
},
{
"Style": 3,
"Id": 17,
"Name": "Yes"
}
],
"Collapsed": false,
"MinSelections": 0,
"Order": 2,
"Hidden": true,
"Id": 4
}
],
"QueueUsages": [
{ "QueueId": "1ad83114-c543-4640-be74-1617ac4939ad" }
],
"Id": "2b2b9f78-4e01-4486-ab11-710c6be701c4"
}]
- Url parameters: none
- Query parameters: TagSchemaFilterParameters
- Request content: none
- Response content: List<TagSchema>
Returns all available schemas for requesting user, optionally limited by the filter.
GET /classification/schemas/{schemaId}
- Url parameters: schemaid - id of target schema
- Query parameters: TagSchemaFilterParameters
- Request content: none
- Response content: TagSchema;
Return a single schema by id
POST /classification/schemas/{schemaId}/batch
- Url parameters: schemaid - id of target schema
- Query parameters: none
- Request content: TagSchema - input schema
- Response content: TagSchema - result
Batch set operation for given schema. Executes a mass update operation, updating both the schema and any children where provided.
Unreferenced children and null properties are not touched, so this endpoint fully supports both partial and complete updates.
POST /classification/schemas
- Url parameters: none
- Query parameters: none
- Request content: TagSchema - create source
- Response content: TagSchema - result
Create a new schema based on input.
PUT /classification/schemas/{schemaId}
- Url parameters: schemaId - id of target schema
- Query parameters: none
- Request content: TagSchema - update source
- Response content: TagSchema - result
Update existing schema based on input.
DELETE /classification/schemas/{schemaId}
- Url parameters: schemaId - id of target schema
- Query parameters: none
- Request content: none
- Response content: none
Deletes target schema completely. Returns HTTP 204 No content on success.
GET /classification/calllistschemas
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: List<CallbackListSchema> - Found schemas
Gets all callbacklist-schema bindings for current user.
Intended for binding management.
POST /classification/calllistschemas/batch
- Url parameters: none
- Query parameters: none
- Request content: List<CallbackListSchema> - Update source
- Response content: List<CallbackListSchema> - Update result
Batch updates given collection of bindings.
Intended for binding management.
GET /classification/queueschemas
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: List<QueueSchema> - Found schemas
Gets all queue-schema bindings for current user.
Intended for binding management.
POST /classification/queueschemas/batch
- Url parameters: none
- Query parameters: none
- Request content: List<QueueSchema> - Update source
- Response content: List<QueueSchema> - Update result
Batch updates given collection of bindings.
Intended for binding management.
GET /classification/instance
- Url parameters: none
- Query parameters: ClassificationFilterParameters
- Request content: none
- Response content: List<ClassificationInstance> - Matching instances
Find classifications. Extracts search filter from query string.
GET /classification/instance/{instanceId}
- Url parameters: instanceId - target instance id
- Query parameters: none
- Request content: none
- Response content: ClassificationInstance - Matching instances
Get single instance by id
POST /classification/instance
Example data for a new service call classification (with the same schema as before)
{
"TagSchemaId": "2b2b9f78-4e01-4486-ab11-710c6be701c4",
"Note": "Classifying user's custom note",
"TagSelections": [
{ "TagId": 19 },
{ "TagId": 23 },
{ "TagId": 17 }
],
"ClassifiedTypeId": 3,
"CallId": "4b415288-8604-4b6c-b604-e4eaeb90c938"
}
- Url parameters: none
- Query parameters: none
- Request content: ClassificationInstance - Input
- Response content: ClassificationInstance - Result
Create a new classification instance.
TagSchema
A tagging schema, consisting of a number of tag groups.
Property name | Value type | Description |
---|---|---|
Id | Guid | Schema id |
Name | string | Schema name |
Groups | List<TagGroup> | Groups |
QueueUsages | List<QueueSchema> | Usages in queues. Read only. |
CallbackListUsages | List<CallbackListSchema> | Usage in callback lists. Read only. |
Modified | DateTime? | When schema was last modified |
Archived | bool? | If schema has been archived for reporting/viewing purposes. Indicates that new classifications should not be created based on it. |
Deleted | bool? | If schema has been deleted. This means that it should not be used. Deleted schemas are only returned if specifically requested |
ManualUsage | bool? | If schema can be used for manual classification |
TagGroup
A single group of tags
Property name | Value type | Description |
---|---|---|
Id | int? | Tag group identifier |
Name | string | Tag group name |
Order | byte? | Relative ordering in schema |
Hidden | bool? | If group should be hidden by default |
Collapsed | bool? | If group should be collapsed by default |
Tags | List<Tag> | Tags in group |
MinSelections | int? | Minimum number of tags that must be selected |
MaxSelections | int? | Maximum number of tags that can be selected |
Archived | bool? | If group has been archived |
Deleted | bool? | If group has been deleted |
Tag
A single tag
Property name | Value type | Description |
---|---|---|
Id | int? | Tag identifier |
Name | string | Tag name |
Style | byte? | Tag symbolic style. Integer values used for transport, value must map to TagStyle to be useful |
StyleEnum | TagStyle | Enum-wrapped Style value |
ShowGroup | int? | Show another group in class when selected |
Archived | bool? | If tag has been marked as archived |
Deleted | bool? | If tag has been marked as deleted |
TagStyle
Tag style enumeration. Should be implemented in clients with suitable colors and other visual hints.
Name | Value | Description |
---|---|---|
Undefined | 0 | Missing/invalid style for backwards-compatibility. Should generally behave like TagStyle.Default |
Default | 1 | No special styling. "Like a button". |
Primary | 2 | Primary styling, something the user would select often. "Primary brand color" |
Positive | 3 | Positive styling, something with positive impact. "Green" |
Warning | 4 | Style warning about something. "Yellow" |
Negative | 5 | Negative styling, something with negative impact. "Red" |
ClassificationInstance
Single classification instance, e.g. classification info for a single call or call list item.
Property name | Value type | Description |
---|---|---|
Id | Guid? | Instance id |
TagSchemaId | Guid? | Id of tagging class classification was based on |
TagSchemaName | string | Name of class classification was based on. Read only. |
Modified | DateTime? | Last modify date. Read only. |
CreatedBy | Guid? | User that created the instance. Auto-populated, read only. |
ModifiedBy | Guid? | User that last modified the instance. Auto-populated, read only |
Note | string | Free text note. Intended for human-readable extra info, should not be used for purposes requiring formality (e.g. reporting) |
TagSelections | List<TagSelection> | Selected tags |
CallId | Guid? | If instance classifies a call, reference to that |
CallListItemId | Guid? | If instance classifies a CallListItem, reference |
ExternalId | string | If instance classifies another external entity |
ClassifiedTypeId | byte? | Type of target instance classifies. Must correspond to ClassifiedTypeEnum |
ClassifiedType | ClassifiedTypeEnum |
TagSelection
A single selected tag.
Main information is the combination of TagGroupId
and TagId
.
These exactly identify the selection and enable matching selections to changed
schema in cases where the tag or group remains but name has been changed.
Additionally TagGroupName
and TagName
are stored so
the exact selection is persisted in cases where tag schema changes. In these cases
the name info can still be used for display purposes and limited editing (=removal).
Property name | Value type | Description |
---|---|---|
TagGroupId | int? | Tag group id. Read only. |
TagGroupName | string | Tag group name. Read only. |
TagId | int? | Selected tag id |
TagName | string | Selected tag name. Read only. |
ClassifiedTypeEnum
Describes possible types in
Name | Value | Description |
---|---|---|
Undefined | 0 | Undefined, fallback |
None | 1 | No specific type, generic classification entry |
DirectCall | 2 | Classifies a direct call. ClassificationInstance.CallId refers to the actual call. |
ServiceCall | 3 | Classifies a service call. ClassificationInstance.CallId refers to the actual call. |
4 | Classifies an email | |
CallListItem | 5 | Classifies a call list item. ClassificationInstance.CallListItemId refers to the actual item |
ClassificationFilterParameters
Search criteria for finding classification instances
Property name | Value type | Description |
---|---|---|
CallId | Guid? | Related to given call id |
CallListItemId | Guid? | Related to given call list item |
QueueSchema
Represents a binding between a service queue and tagging schema. Means that calls from given queue should be classified with given schema
Property name | Value type | Description |
---|---|---|
QueueName | string | Name of relevant queue. Read only. |
QueueId | Guid? | Id of relevant queue. |
SchemaId | Guid? | Id of relevant schema. |
Deleted | bool? | If entry should be deleted. Relevant for sending batch requests to API |
CallbackListSchema
Represents a binding between callback list and tagging schema. Indicates that items in given list should be classified with the specified schema.
Property name | Value type | Description |
---|---|---|
ListName | string | Name of relevant list. Read only. |
ListId | Guid? | Id of relevant call list |
SchemaId | Guid? | Schema id |
RequestTypeId | byte? | Type of CallbackRequestType schema applies to. If null, all. |
RequestType | CallbackRequestType | Request type enum for convenience |
Deleted | bool? | If entry should be deleted. Relevant when sending batch requests to API |
TagSchemaFilterParameters
Filtering options for acquiring TagSchema
s
Property name | Value type | Description |
---|---|---|
IncludeChildren | bool? | Whether to include child items in result. Allows acquiring the entire configuration in one call, if necessary. |
ModifiedAfter | DateTime? | Return only items modified after given timestamp. Enables clients to periodically request updated info. |
IncludeArchived | bool? | Include archived items in response. Enables clients to detect that item was archived since last check and should act accordingly |
IncludeDeleted | bool? | Include deleted items in response. Enables clients to detect that item was deleted since last check and should stop using it. |
TagGroupFilterParameters
Filtering options for acquiring TagGroup
s
Property name | Value type | Description |
---|---|---|
ModifiedAfter | DateTime? | Return only items modified after given timestamp. Enables clients to periodically request updated info. |
IncludeArchived | bool? | Include archived items in response. Enables clients to detect that item was archived since last check and should act accordingly |
IncludeDeleted | bool? | Include deleted items in response. Enables clients to detect that item was deleted since last check and should stop using it. |
TagFilterParameters
Filtering options for acquiring Tag
s
Property name | Value type | Description |
---|---|---|
ModifiedAfter | DateTime? | Return only items modified after given timestamp. Enables clients to periodically request updated info. |
IncludeArchived | bool? | Include archived items in response. Enables clients to detect that item was archived since last check and should act accordingly |
IncludeDeleted | bool? | Include deleted items in response. Enables clients to detect that item was deleted since last check and should stop using it. |
QoS
THIS ENDPOINT IS DEPRECATED. QoS data should be sent to telemetry service as GELF content.
Endpoints for submitting quality of service data.
POST /users/{userid}/qos
- Url parameters: userid - targeted user
- Query parameters: none
- Request content: json
- Response content: none
Receives freeform JSON object containing suitable QoS data.
Returns 202 Accepted always.
Call management
Endpoints for getting information about ongoing calls and controlling them.
The two core concepts are CallLegs and ActionRequests. CallLeg describes a call that is found in the system. In basic use case, it is a call being allocated or already connected to a user. CallLegs are controller with ActionRequests, that describe the action system should perform on the active leg.
Basic scenario is:
- Get ongoing CallLegs for user with GET /callmanagement/legs
- Do something on the legs over POST /callmanagement/actions
GET /callmanagement/legs
- Url parameters: none
- Query parameters: CallLegFilterParameters
- Request content: none
- Response content: List<CallLeg>
Return call legs filtered by CallLegFilterParameters object passed in request query string.
Example call getting active legs for a user
GET /callmanagement/legs?UserIds=ccbbbaaa-1122-3344-5555-001152293344
GET /callmanagement/legs/{legid}
- Url parameters: legid: Target leg id
- Query parameters: none
- Request content: none
- Response content: CallLeg
Returns a single call leg with specified id.
GET /callmanagement/actions
- Url parameters: none
- Query parameters: ActionRequestFilterParameters
- Request content: none
- Response content: List<ActionRequest>
Return filtered action requests.
GET /callmanagement/actions/{actionid}
- Url parameters: actionid: target action id
- Query parameters: none
- Request content: none
- Response content: ActionRequest
POST /callmanagement/actions
- Url parameters: none
- Query parameters: none
- Request content: ActionRequest
- Response content: true on success, error code otherwise
CallLeg
Sample response describing a call leg connected to a user
{
"TargetNumber": "+8881231234",
"QueueId": "c208848c-c86e-4ecc-bdc3-c3ca4f277018",
"CallLegStatusId": 3,
"Created": "2017-03-15T08:25:56Z",
"CallId": "e55f2add-5b66-4bb9-a186-05d70fe03646",
"ActionRequests": [],
"UserId": "ccbbbaaa-1122-3344-5555-001152293344",
"LastHandlerId": null,
"SourceNumber": "+358404893501",
"Id": "33f29402-5909-e711-80c9-00505689257e"
}
Property name | Value type | Description |
---|---|---|
Id | Guid | Call leg id |
CallId | Guid | Call id. Multiple legs with same CallId can exist |
Created | DateTime | When leg was created |
UserId | Guid? | Relevant user |
QueueId | Guid | Relevant queue |
SourceNumber | String | Original source number of the call |
TargetNumber | String | Original target number of the call |
CallLegStatusId | int | Leg status data member, used for carrying CallLegStatus enum for backward compatibility |
LastHandlerId | Guid? | Id of last handler. Often null, when has not been handled yet. |
ActionRequests | List |
Related action requests |
CallLegFilterParameters
Filter object for fetching call legs
Property name | Value type | Description |
---|---|---|
UserIds | List |
User ids |
QueueIds | List |
Queue ids |
ModifiedAfter | DateTime? | Only legs that appeared since given time |
IncludeActionRequests | bool? | Whether to include related ActionRequests for each leg |
CallLegStatus
Statuses call leg can be include
Name | Value | Description |
---|---|---|
Unknown | 0 | Unknown type for backwards compatibility, can usually be ignored |
InQueue | 1 | Call in queue, not necessarily allocated to user |
Allocated | 2 | Call being allocated to user |
Connected | 3 | Call connected to user |
Parked | 10 | Call is parked |
ActionRequest
Example transfer request
{
"LegId": "33f29402-5909-e711-80c9-00505689257e",
"RequestTypeId": 1,
"UserId": "ccbbbaaa-1122-3344-5555-001152293344",
"UserParameters": "+358501231234"
}
Single action request made to call routing components
CallId, UserId, RequestType is the essential information, signalling who wants to do what to which call
Property name | Value type | Description |
---|---|---|
Id | Guid? | Action request id |
LegId | Guid? | Leg request refers to |
CallId | Guid | Call id request refers to |
Modified | DateTime | When the request was last modified |
UserId | Guid | Userid request relates to |
RequestTypeId | int | ActionRequestType transport layer for backwards compatilibity |
UserParameters | String | Parameters, usage depends on ActionRequestType. Currently used for ActionRequestType Transfer to provide number to transfer to |
ActionRequestFilterParameters
Property name | Value type | Description |
---|---|---|
UserIds | List |
UserIds to fetch action requests for |
CallIds | List |
CallIds to fetch ActionRequests for |
ActionRequestStatus
Enum for possible ActionRequestStatuses.
Name | Value | Description |
---|---|---|
Unknown | -1 | Unknown member for backwards compatibility |
New | 1 | New, unprocessed request |
Done | 2 | Request processed successfully |
Rejected | 3 | Request processing was rejected, see ReasonCode |
Failed | 4 | Processing was attempted but failed, see ReasonCode |
ActionRequestType
Types of requests that can be made.
Name | Value | Description |
---|---|---|
Unknown | 0 | Unknown type, used for backwards compatibility. Can be ignored. |
Transfer | 1 | Transfer call to number specified in ActionRequest param |
Reject | 2 | Reject allocated call |
Disconnect | 3 | Disconnect the call |
Park | 10 | Park the call |
Unpark | 11 | Unpark the call |
Call extra data
Endpoints for getting extra data for ongoing calls.
GET /callextradata/{callId}/
- Url parameters: callId
- Query parameters: CallExtraDataFilterParameters
- Request content: none
- Response content: List<CallExtraData>
Return codes:
- 200 OK
Returns call extra data filtered by CallExtraDataFilterParameters object passed in request query string or empty list. The endpoint returns only the extra data for a call in which the authenticated user is an active participant. This means the call is either allocated to the user or connected to the user. There may be a brief delay before extra data becomes available for a call.
Example call getting extra data for a callid.
GET /callextradata/ccbbbaaa-1122-3344-5555-001152293344?DataProtectionType=1
GET /callextradata/
- Url parameters: none
- Query parameters: CallExtraDataTokenFilterParameters
- Request content: none
- Response content: List<CallExtraData>
Return codes:
- 200 OK
- 400 JWT token is invalid.
Returns call extra data filtered by CallExtraDataTokenFilterParameters object passed in request query string or empty list. The endpoint returns only the extra data for a call that the jwt token is scoped for. There may be a brief delay before extra data becomes available for a call.
Example call getting extra data with jwt token.
GET /callextradata?Token=jwttokenstring
CallExtraData
Sample response describing a call extra data
{
"CallId": "ccbbbaaa-1122-3344-5555-001152293344",
"ExtraDataType": "1",
"Keyword": "Any",
"Value": "Value",
}
Property name | Value type | Description |
---|---|---|
CallId | Guid | Call id where extra data relates to. |
ExtraDataType | CallExtraDataType? | Call extra data type. Null value is unknown data type. |
Keyword | String | Call extra data keyword. |
Value | String | Call extra data value. |
CallExtraDataFilterParameters
Filter object for fetching call legs
Property name | Value type | Description |
---|---|---|
ExtraDataType | CallExtraDataType? | Extra data type. Missing parameter returns all types of extra data for the callid. |
DataProtectionType | CallExtraDataProtectionType? | Type of data protection. All extra data values will be protected. Missing parameter will use default protection type. |
CallExtraDataTokenFilterParameters
Filter object for fetching call legs
Property name | Value type | Description |
---|---|---|
Token | String | Mandatory JWT token to access the call extra data. |
DataProtectionType | CallExtraDataProtectionType? | Type of data protection. All extra data values will be protected. Missing parameter will use default protection type. |
CallExtraDataType
Possible extra data types.
Name | Value | Description |
---|---|---|
StrongAuth | 1 | Strong authentication data |
CallExtraDataProtectionType
Possible data protection types.
Name | Value | Description |
---|---|---|
None | 1 | Values returned in plain text (default) |
Base64 | 2 | Values returned in base64 encoded text from utf8 string. |
Returned keywords for StrongAuth type
Keyword | Description |
---|---|
AUTH.Surname | Surname of the authenticated caller |
AUTH.GivenName | Given name |
AUTH.CallerId | Identification of the user, e.g. social security number (hetu) |
Notification
Things related to push notification tokens.
POST /users/{userid}/notification
Adds new token for user if token does not exist. Returns 200 OK if token already exists.
- Url parameters: userid - targeted user
- Request content: UserNotificationTokenCreate
- Response content: UserNotificationToken
Requires that Token
TokenTypeId
Options
properties are specified in the UserNotificationTokenCreate.
Provide the Token
in UserNotificationTokenCreate as it is received from the push service. Do not encode, truncate or add additional characters.
Example JSON serialization of a UserNotificationTokenCreate
{
"Token": "dSNqJvfZHhc:APA91bHHZCZLtBvkojlwm2HZasLBVmNDDtzttQBLULEHjfnPRTs9hGWOUtq59dMMP3-valh9FgYMIKh7iBO-J2Loz84NN",
"TokenTypeId": 1,
"DeviceId": "4200a30ed4197413",
"DeviceName": "SM-J330F",
"Options":
{
"TokenOptionId": 1,
"Value": 1
},
"ExpiresIn": 604799
}
Example usage with APIClient
UserNotificationToken token = new UserNotificationToken()
{
Token = "dSNqJvfZHhc:APA91bHHZCZLtBvkojlwm2HZasLBVmNDDtzttQBLULEHjfnPRTs9hGWOUtq59dMMP3-valh9FgYMIKh7iBO-J2Loz84NN",
TokenTypeId = 1,
DeviceId = "4200a30ed4197413",
DeviceName = "SM-J330F",
Options = new List<UserNotificationTokenOption>()
{
new UserNotificationTokenOption
{
TokenOptionId = 1,
Value = 1
}
},
"ExpiresIn": 604799
};
Client.CreateNotification(UserID, token);
GET /users/{userid}/notification
Returns all UserNotificationToken objects for the user.
- Url parameters: userid - targeted user
- Request content: None
- Response content: List<UserNotificationToken>
Example JSON serialization of a UserNotificationToken list
[
{
"Token": "dSNqJvfZHhc:APA91bHHZCZLtBvkojlwm2HZasLBVmNDDtzttQBLULEHjfnPRTs9hGWOUtq59dMMP3-valh9FgYMIKh7iBO-J2Loz84NN",
"TokenTypeId": 1,
"DeviceId": "4200a30ed4197413",
"DeviceName": "SM-J330F",
"Options":
{
"TokenOptionId": 1,
"Value": 1
},
"Expires": "/Date(1455530400000+0200)/",
"Expired": false
},
]
GET /users/{userid}/notification/{token}
Returns the UserNotificationToken object for the push notification token.
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
- Url parameters: userid - targeted user, token - token string that was aquired from the device push service
- Request content: None
- Response content: UserNotificationToken
Example JSON serialization of a UserNotificationToken
{
"Token": "dSNqJvfZHhc:APA91bHHZCZLtBvkojlwm2HZasLBVmNDDtzttQBLULEHjfnPRTs9hGWOUtq59dMMP3-valh9FgYMIKh7iBO-J2Loz84NN",
"TokenTypeId": 1,
"DeviceId": "4200a30ed4197413",
"DeviceName": "SM-J330F",
"Options":
{
"TokenOptionId": 1,
"Value": 1
},
"Expires": null,
"Expired": false
}
PATCH /users/{userid}/notification/{token}
Updates the existing push notification token.
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
- Url parameters: userid - targeted user, token - token string that was aquired from the device push service
- Request content: UserNotificationTokenUpdate
- Response content: UserNotificationToken
Example JSON serialization of a UserNotificationTokenUpdate
{
"ExpiresIn": 604799
}
GET /users/{userid}/notification/{token}/options
Returns the UserNotificationTokenOption objects for the push notification token.
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
- Url parameters: userid - targeted user, token - token string that was aquired from the device push service
- Request content: None
- Response content: List<UserNotificationTokenOption>
Example JSON serialization of a UserNotificationTokenOption list
[
{
"TokenId": e7a0f241-29de-485d-978c-ce8a4eda902c,
"Name": "Availability"
"TokenOptionId": 1,
"Value": 1
},
]
PUT /users/{userid}/notification/{token}/options
Updates the UserNotificationTokenOption objects for the push notification token.
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
- Url parameters: userid - targeted user, token - token string that was aquired from the device push service
- Request content: List<UserNotificationTokenOption>
- Response content: List<UserNotificationTokenOption>
Example JSON serialization of a UserNotificationTokenOption list
[
{
"TokenOptionId": 1,
"Value": 1
},
]
DELETE /users/{userid}/notification/{token}
Deletes push notification token. Sent tokens are automatically deleted from db if the push service indicates that used token has become invalid.
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
- Url parameters: userid - targeted user, token - token string that was aquired from the device push service
- Request content: None
- Response content: UserNotificationToken
UserNotificationToken
Represents a UserNotificationToken.
Property | Value type | Description |
---|---|---|
Id | Guid? | Token identifier |
UserId | Guid? | User token relates to |
Token | string | Token string that was aquired from the device push service. |
TokenTypeId | byte? | Push service type that the token uses. Refers to TokenTypeId |
DeviceId | string | Id that is aquired from the device. Informational only. |
DeviceName | string | Device name that is aquired from the device. Informational only. |
Options | List<UserNotificationTokenOption> | Options for the token. |
Expires | DateTime? | Token expiration date. If value is null then token will never expire. |
Expired | bool | Is token expired. |
UserNotificationTokenCreate
Represents a UserNotificationTokenCreate.
Property | Value type | Description |
---|---|---|
Token | string | Token string that was aquired from the device push service. |
TokenTypeId | byte? | Push service type that the token uses. Refers to TokenTypeId |
DeviceId | string | Id that is aquired from the device. Informational only. |
DeviceName | string | Device name that is aquired from the device. Informational only. |
Options | List<UserNotificationTokenOption> | Options for the token. |
ExpiresIn | int? | Token expiration value. Value is seconds from now. If value is null or negative then token will never expire. Notification token will be marked as deleted when expiration occurs. |
UserNotificationTokenUpdate
Represents a UserNotificationTokenUpdate.
Property | Value type | Description |
---|---|---|
ExpiresIn | int? | Token expiration value. Value is seconds from now. If value is null or negative then token will never expire. Notification token will be marked as deleted when expiration occurs. |
TokenTypeId
Name | Value | Description |
---|---|---|
Firebase | 1 | Firebase push service. |
APNS | 2 | Apple push service. |
UserNotificationTokenOption
Represents a UserNotificationTokenOption.
Property | Value type | Description |
---|---|---|
TokenId | Guid? | Token identifier |
TokenOptionId | byte? | Option id. Refers to TokenOptionId |
Value | int? | Refers to UserNotificationTokenOptionValue |
Name | string | Option name |
Deleted | bool? | Indicates if this option is deleted. |
TokenOptionId
Name | Value | Description |
---|---|---|
Availability | 1 | Availability option type. |
UserQueueAlert | 2 | UserQueueAlert option type. |
UserActionMobileCall | 3 | UserActionMobileCall option type. |
CallbackChanges | 4 | CallbackChanges option type. |
UserAssistedCallback | 5 | UserAssistedCallback option type. |
CallSuperviseStatus | 6 | CallSuperviseStatus option type. |
CallSuperviseAvailable | 7 | CallSuperviseAvailable option type. |
UserNotificationTokenOptionValue
Name | Value | Description |
---|---|---|
Disabled | 0 | Option is disabled and will not be handeled by the push service. |
Enabled | 1 | Option is enabled and will be handeled by the push service. |
Token URL encoding
Push notification Token
string can contain invalid characters to be used in the url so it is recommended
that the {token}
string is encoded before using it in the url.
Use Base64 encoding for the string and trim "=" charaters from the end. Then replace character "+" with "-" and "/" with "_"
Example encoding using csharp
string encoded = System.Convert
.ToBase64String(arg)
.TrimEnd(new char[] { '=' })
.Replace('+', '-')
.Replace('/', '_');
Automated calling
POST /users/{userid}/callrobot/call
Initiates an outbound call with given properties. The call impersonates the user making the API call. The call is a one-way call from the server to the target with no connection to any of the user's actual terminals. It is not possible to join the user to the outbound call, so this endpoint cannot be used to predictively dial outbound calls that the calling user would then join.
The call will ring in target number for the duration specified in the request and then disconnect. If the target answers the call, they will hear a generic "this is an automated call" prompt and the call will disconnect.
This can be used to notify users about "anything". Communicate off-band what a call from this number means and how they should react.
Example use case:
- Have a multi-channel agent with a basic (non-smart) phone
- Want to notify the agent about a task in their email channel
- Have the agent doing other work away from their desk
- Have a special user with a dedicated number for "Back to your desk" notifications
- Have agents add this number to their phone
- When a task appears, use this API to trigger a call to the agent
- The agent sees the call from "Back to your desk" and knows what to do
Endpoint information
- Url parameters: none
- Query parameters: none
- Request content: OutboundCallRequest - details of the call
- Response content: none
- Response codes:
- 200 - Request accepted
- 403 - Missing user configuration or invalid user target
- 400 - Invalid parameters
- 500 - Internal configuration error
OutboundCallRequest
{
"TargetNumber": "+358501231234",
"Timeout": 25
}
Data model for initiating outbound automatic calls
Property name | Value type | Description |
---|---|---|
TargetNumber | string | Target number to call in E.164 format |
TimeoutSeconds | int? | Timeout for the outgoing phone call (between 5 and 60 seconds) |
User alerts
Things related to user alerts.
POST /users/{userid}/alerts/queue/{queueid}
Adds new alert for a queue. Does QueueAlertValidation for QueueAlertCondition.
- Url parameters: userid - targeted user, queueid - targeted queue
- Request content: QueueAlertCondition
- Response content: QueueAlert
- Returns 200 OK if success.
- Returns 400 Bad Request if validation fails.
- Returns 404 Not Found if user does not exist in queue.
Example JSON serialization of a QueueAlertCondition
{
"ActiveAgents":
{
"Value": "1",
"Expression": ">"
},
"MaxWaitTime":
{
"Value": "2",
"Expression": ""
},
"QueueLength":,
{
"Value": "3",
"Expression": "<"
},
}
Example usage with APIClient
QueueAlertCondition condition = new QueueAlertCondition()
{
ActiveAgents = new AlertCondition()
{
Value = "1",
Expression = ">",
},
MaxWaitTime = new AlertCondition()
{
Value = "2",
Expression = "",
},
QueueLength = new AlertCondition()
{
Value = "3",
Expression = "<",
}
};
Client.CreateQueueAlert(UserID, QueueID, condition);
GET /users/{userid}/alerts/queue
Returns all QueueAlert objects for the user.
- Url parameters: userid - targeted user
- Request content: None
- Response content: List<QueueAlert>
- Returns 200 OK if success.
- Returns 404 Not Found if alerts does not exist.
Example JSON serialization of a QueueAlert list
[
{
"Id": "63cd7be2-c227-4da9-be8a-29c1796fd0e8",
"UserId": "e9a66283-ab56-4dc4-9d2a-4f87fd420506",
"QueueId": "05dd1655-5ff2-4612-93fa-2a2d1b19c925",
"Modified": "2009-02-15T00:00:00Z",
"Condition":
{
ActiveAgents
{
Value = "1",
Expression = ">",
},
MaxWaitTime
{
Value = "2",
Expression = "",
},
QueueLength
{
Value = "3",
Expression = "<",
}
}
},
]
GET /users/{userid}/alerts/queue/{queueid}
Returns all the QueueAlert objects for the queue.
- Url parameters: userid - targeted user, queueid - targeted queue
- Request content: None
- Response content: List<QueueAlert>
- Returns 200 OK if success.
- Returns 404 Not Found if alert does not exist in queue or user does not exist in queue.
Example JSON serialization of a QueueAlert
[
{
"Id": "63cd7be2-c227-4da9-be8a-29c1796fd0e8",
"UserId": "e9a66283-ab56-4dc4-9d2a-4f87fd420506",
"QueueId": "05dd1655-5ff2-4612-93fa-2a2d1b19c925",
"Modified": "2009-02-15T00:00:00Z",
"Condition":
{
ActiveAgents
{
Value = "1",
Expression = ">",
},
MaxWaitTime
{
Value = "2",
Expression = "",
},
QueueLength
{
Value = "3",
Expression = "<",
}
}
},
]
PUT /users/{userid}/alerts/queue/{alertid}
Updates the QueueAlertCondition in QueueAlert. Does QueueAlertValidation for QueueAlertCondition.
- Url parameters: userid - targeted user, alertid - targeted alert
- Request content: QueueAlertCondition
- Response content: QueueAlert
- Returns 200 OK if success.
- Returns 400 Bad Request if validation fails.
- Returns 404 Not Found if alert does not exist or user does not exist in queue.
Example JSON serialization of a QueueAlertCondition
{
"ActiveAgents":
{
"Value": "3",
"Expression": "<"
},
"MaxWaitTime":
{
"Value": "4",
"Expression": ">"
},
"QueueLength":,
{
"Value": "2",
"Expression": ">"
}
}
DELETE /users/{userid}/alerts/queue
Deletes QueueAlert from all users queues.
- Url parameters: userid - targeted user
- Request content: None
- Response content: List<QueueAlert>
- Returns 200 OK if success.
- Returns 404 Not Found if alerts does not exist.
DELETE /users/{userid}/alerts/queue/{alertid}
Deletes specified QueueAlert.
- Url parameters: userid - targeted user, alertid - targeted queue
- Request content: None
- Response content: QueueAlert
- Returns 200 OK if success.
- Returns 404 Not Found if alert does not exist or user does not exist in queue.
QueueAlert
Represents a QueueAlert.
Property | Value type | Description |
---|---|---|
Id | Guid | Id of the alert. |
UserId | Guid | User that alert relates to. |
QueueId | Guid | Queue that alert relates to. |
Modified | DateTime | DateTime when the alert was last modified. |
Condition | QueueAlertCondition | Conditions for the alert. Refers to QueueAlertCondition |
QueueAlertCondition
Represents a QueueAlertCondition.
QueueAlertValidation
- Condition Value should be convertable to positive Int32 value or validation will fail.
- Condition Expression should be ">" or "<" or validation will fail.
- Condition Expression can be empty but then ">" is used by default.
Name | Value | Description |
---|---|---|
ActiveAgents | AlertCondition | Condition for ActiveAgents that will be validated. Value in seconds. |
MaxWaitTime | AlertCondition | Condition for MaxWaitTime that will be validated. Value in seconds. |
QueueLength | AlertCondition | Condition for QueueLength that will be validated. Value in seconds. |
AlertCondition
Name | Value | Description |
---|---|---|
Value | string | Value for the condition. |
Expression | string | Expression for the condition. |
Push Service Data
The push message is sent from the push server as a data message that is a JSON serialized data.
Message data example using Android Firebase
public void onMessageReceived(RemoteMessage remoteMessage) {
JSONObject jObj = new JSONObject(remoteMessage.getData().get("Data"));
String message = jObj.getString("Message");
String MessageType = jObj.getString("MessageType");
Float pushOrder = jObj.getFloat("PushOrder");
}
UserQueueAlert message data example using Android Firebase
private void showNotification(String message) {
JSONObject mainObject = new JSONObject(message);
String queueId = mainObject.optString("QueueId");
String queueName = mainObject.optString("QueueName");
String conditionName = mainObject.optString("ConditionName");
String value = mainObject.optString("Value");
...
}
Push message data
Name | Value | Description |
---|---|---|
ServiceId | string | GUID value. Indicates if the notification service has been restarted. Mostly just informational. |
PushOrder | long | DateTime.UtcNow.Ticks value. Indicates the push order of the message. This should be handled so that every time a push message is received client should compare that the received order number is higher than previous messages and discard the received if it is not higher. This ensures that if client does not receive the push messages in order then it should not handle some old messages, only the highest order number is valid. |
MessageType | string | Possible values are "UserAvailability", "UserQueueAlert" |
Message | string | JSON serialized string. This content will depend on the MessageType. |
UserQueueAlert message data
Name | Value | Description |
---|---|---|
UserId | Guid | Id of target user. |
OrganizationId | Guid | Id of related organization. |
QueueId | Guid | Id of related Queue. |
QueueName | string | Name of the related Queue. |
ConditionName | string | Name of the triggered condition. Possible values are QueueAlertCondition property names. |
ConditionValue | string | Value of the triggered condition. Value from AlertCondition |
ConditionExpression | string | Expression of the triggered condition. Expression from AlertCondition |
Value | string | Actual value for the triggered condition. |
User actions
Things related to user actions.
POST /users/{userid}/action/mobile/call
Invokes an outgoing phone call in users mobile app. Requires that the user has the app installed, logged in and running. Can be used to integrate outbound calling with a 3rd party system.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the targeted user's terminal to actually start making the call.
Targeted phone number is validated and must be in E.164 format.
If target user is the authenticated user, no additional authorization is required.
If target user is other than the authenticated user, permission ClickToCall.Create is required.
- Url parameters: userid - targeted user
- Request content: UserActionPhoneCall
- Response content: UserActionPhoneCall
- Returns 200 OK if success.
- Returns 400 Bad Request if validation fails.
- Return 403 Forbidden if target user is not authorized
Example JSON serialization of a UserActionPhoneCall
{
"PhoneNumber": "+35840123456"
}
UserActionPhoneCall
Represents a UserActionPhoneCall.
Property | Value type | Description |
---|---|---|
PhoneNumber | string | Phone number to call. Must be in E.164 format |
Push Service Data
The push message is sent from the push server as a data message that is a JSON serialized data.
Message data example using Android Firebase
public void onMessageReceived(RemoteMessage remoteMessage) {
JSONObject jObj = new JSONObject(remoteMessage.getData().get("Data"));
String message = jObj.getString("Message");
String MessageType = jObj.getString("MessageType");
Float pushOrder = jObj.getFloat("PushOrder");
}
UserActionMobileCall message data example using Android Firebase
private void handleNotification(String message) {
JSONObject mainObject = new JSONObject(message);
String value = mainObject.optString("PhoneNumber");
...
}
Push message data
Name | Value | Description |
---|---|---|
ServiceId | string | GUID value. Indicates if the notification service has been restarted. Mostly just informational. |
PushOrder | long | DateTime.UtcNow.Ticks value. Indicates the push order of the message. This should be handled so that every time a push message is received client should compare that the received order number is higher than previous messages and discard the received if it is not higher. This ensures that if client does not receive the push messages in order then it should not handle some old messages, only the highest order number is valid. |
MessageType | string | Possible values are the action class names e.g "UserActionMobileCall" |
Message | string | JSON serialized string. This content will depend on the MessageType. |
UserActionMobileCall message data
Name | Value | Description |
---|---|---|
UserId | Guid | Id of target user. |
OrganizationId | Guid | Id of related organization. |
PhoneNumber | string | PhoneNumber to call. |
User features
Things related to user features.
POST /users/{userid}/features/callout/activate
The next outbound call to the number
+123456789
will be made as a service call on behalf of a queue.
POST /users/me/features/callout/activate
{
"TargetNumber": "+123456789",
"QueueId": "11111111-1111-1111-1111-111111111111"
}
The next outbound call to the number
+123456789
will be made as a service call on behalf of a callback request.
POST /users/me/features/callout/activate
{
"TargetNumber": "+123456789",
"CallbackListId": "22222222-2222-2222-2222-222222222222",
"CallbackRequestId": "33333333-3333-3333-3333-333333333333"
}
Notifies the call control backend that the next outbound call the user will make is an outbound-queue call or an outbound-callback call instead of a direct call. This affects the following:
- Call type will be "service call" instead of "direct call."
- CLI and call recording configuration used come from the queue or callback list.
- Ownership of the call information and call recording will be from the queue or callback list.
The actual phone call must be initiated within 10 seconds after this API call. If the delay between the API call and the actual phone call arriving at the backend is more than 10 seconds, the phone call will be treated as a direct call.
To make calls on behalf of a queue, the user must be a member of the queue (active or inactive).
To make calls on behalf of a callback list, the user must be authorized to handle callback requests.
The user can only make callout/activate requests as themselves.
- Url parameters: userid - targeted user
- Request content: OutboundServiceCallActivationRequest
- Response content: OutboundServiceCallActivationResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if the target user is not authorized to make calls on behalf of a queue/callback list.
GET /users/{userid}/features/callout/configuration
Returns outbound call configuration
GET /users/me/features/callout/configuration
{
"Queues": [
{
"QueueId": "11111111-1111-1111-1111-111111111111",
"Name": "Queue 1",
"Numbers": [
{
"Default": "true",
"DisplayNumber": "+123456789",
"DisplayName": "+123456789"
},
{
"Default": "false",
"DisplayNumber": "+987654321",
"DisplayName": "IVR"
}
],
"Recorded": "true"
},
{
"QueueId": "22222222-2222-2222-2222-222222222222",
"Name": "Queue 2",
"Numbers": [
{
"Default": "true",
"DisplayNumber": "+1234567899",
"DisplayName": "+1234567899"
}
],
"Recorded": "false"
}
}
Get configuration for outbound call.
- Url parameters: userid - targeted user
- Response content: OutboundQueueConfigurations
Return codes:
- 200 OK if success.
- 403 Forbidden if the target user is not authorized to get configuration.
POST /users/{userid}/features/calls/allocate-next
Example request, to wait max 5 seconds for inbound servicecall to be allocated
POST /users/me/features/calls/allocate-next
{
"TTLSeconds": 5
}
Response, if there is inbound servicecall to be allocated
Response:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"AllocationType": "allocated",
"Success": true
}
Response, if there are no inbound servicecalls to allocate:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"AllocationType": "nocalls",
"Success": true
}
Invokes to allocate next inbound servicecall to the user. Requires that user is in fetch-allocation mode (user setting Queues_AllocationMode
= "fetch")
Endpoint will wait for a period of time, defined by TTLSeconds in request if there are no servicecalls to be allocated. If there are, endpoint responds immediately, and call is allocated to the user.
- Url parameters: userid - targeted user
- Request content: CallAllocationRequest
- Response content: CallAllocationResponse
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 503 ServiceUnavailable if not success. Occurs when backend services are not operational.
POST /users/{userid}/features/calls/strong-authentication
Example request
POST /users/me/features/calls/strong-authentication
{
"CallId": "22222222-2222-2222-2222-222222222222",
"CallerNumber": "+3581234567"
}
Response.
Response:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"Token": "JWT",
"Success": true
}
Invokes strong authentication to a call. The authentication result can be fetched from the call extra data endpoint using the JWT token as query parameter.
- Url parameters: userid - targeted user
- Request content: CallStrongAutheticationRequest
- Response content: CallStrongAutheticationResponse
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized to initiate strong authentication for call.
- 503 ServiceUnavailable if not success. Occurs when backend services are not operational.
GET /users/{userid}/features/cli
Calling Line Identification (CLI) is the phone number displayed on the called phone.
Returns the current active CLI value for a user.
- Url parameters: userid - targeted user
- Response content: CLIStatus
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
GET /users/{userid}/features/cli/configuration
Returns list of available values for a user to be used as CLI.
- Url parameters: userid - targeted user
- Response content: CLIConfiguration
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
POST /users/{userid}/features/cli/activate
Invokes to activate cli.
Endpoint call will wait for a short period of time to allow the event message to be delivered. After the return a call can be made.
If target user is the authenticated user and has read permission to settings. Validates that the given phonenumber is contained in the authorized numbers list.
- Url parameters: userid - targeted user
- Request content: CLIActivationRequest
- Response content: CLIActivationResponse
Return codes:
- 202 Accepted if success.
- 400 BadRequest if validation fails.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
POST /users/{userid}/features/wrapup/terminate
Invokes to terminate wrap-up manually.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If target user is the authenticated user, no additional authorization is required.
If the target user is someone else, authorize with QueueUser.UPDATE
- Url parameters: userid - targeted user
- Content-Length: 0
- Request content: none
- Response content: WrapUpTerminateResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if target user is not authorized
POST /users/{userid}/features/supervision/monitorcall
Invokes supervisor to monitor a call.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionMonitorCallRequest
- Response content: SupervisionResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if not authorized
POST /users/{userid}/features/supervision/assistancerequest
Invokes user to ask supervisor assistans.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If user is self and target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionAssistanceRequest
- Response content: SupervisionResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if not authorized
POST /users/{userid}/features/supervision/subscriptions
Creates supervision subscription.
If user is self and target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionSubscription
- Response content: SupervisionSubscription
Return codes:
- 200 Success.
- 400 BadRequest if invalid target user
- 403 Forbidden if not authorized
PUT /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Updates the supervision subscription. This can be used to update the subscription active status.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionSubscription
- Response content: SupervisionSubscription
Return codes:
- 200 If success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
GET /users/{userid}/features/supervision/subscriptions
Gets supervision subscriptions for given user.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: List<SupervisionSubscription>
Return codes:
- 200 Success.
- 403 Forbidden if not authorized
GET /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Get the supervision subscription for given user.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: SupervisionSubscription
Return codes:
- 200 Success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
DELETE /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Deletes the supervision subscription.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: SupervisionSubscription
Return codes:
- 200 If success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
OutboundServiceCallActivationRequest
This class represents a request for call out activation. There mast be either QueueId or CallbackListId and CallbackRequestId set.
Property name | Value type | Description |
---|---|---|
TargetNumber | string | Required. Target number of the next call out by the user. Helps to verify that correct call will be processed. Note that the number is expected to be provided in E.164 format (+358101231234) |
CallbackRequestId | Guid | Optional: If the call out is related to handling a specific callback request, then (and only then) this must be provided. |
CallbackListId | Guid | Optional: If the call out is related to handling a specific callback request, then (and only then) this must be provided. |
QueueId | Guid | Optional: If the call out is an outbound service call on behalf of a service queue, then (and only then) this must be provided. |
CLI | string | Optional. CLI to use for the call out. If not set, the default CLI of the queue or callback list is used. Setting CLI can be disabled for a queue or callback list, in which case CLI given in request is ignored. |
TimeToLive | int | Optional: How many seconds this request is valid. If no call is received after the specified timeout, the request is dropped as expired Actual usage depends on the use case. If you know that the call will be coming in soon, this should be set to a low value (seconds). If this is a "pre-reservation" of a call that may happen after a while, for example if the user needs to dial manually, then a higher value can be provided. |
OutboundServiceCallActivationResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | Guid | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
CLI | string | Caller number. |
IsRecorded | bool | Indicates if the call is recorded. |
PrePrompt | bool | Indicates if there will be pre-prompt played before connecting the agent and customer. |
OutboundQueueConfigurations
Property name | Value type | Description |
---|---|---|
Queues | List |
Queues user can use. OutboundQueueConfiguration |
OutboundQueueConfiguration
Property name | Value type | Description |
---|---|---|
QueueId | Guid? | QueueId |
Name | string | Queue name |
Numbers | List |
Queue numbers OutboundQueueNumber |
Recorded | bool? | Will the call be recorded. |
OutboundQueueNumber
Property name | Value type | Description |
---|---|---|
Default | bool? | Default number. |
DisplayNumber | string | Display number. |
DisplayName | string | Display name for the number. Used to help the user choose the right number. |
CallAllocationRequest
This class represents a request for call allocation
Property name | Value type | Description |
---|---|---|
TTLSeconds | int | The time-to-live (TTL) for the call allocation request, in seconds. Must be between 0 and 60. |
CallAllocationResponse
Property name | Value type | Description |
---|---|---|
RequestId | Guid | Request id used for the event publish. |
AllocationType | String | Allocation type: allocated = Call allocated, nocalls = No calls to allocate for the agent, agentunavailable = Call could not be allocated following the normal allocation rules(agent was DND, afterwork etc). |
Success | bool | Indicates if the request was success. |
CallStrongAutheticationRequest
This class represents a request for call strong authentication
Property name | Value type | Description |
---|---|---|
CallId | Guid | Id of the call for which the strong authentication is made. Mandatory. |
CallerNumber | String | E.164 format caller number where the strong authetication SMS request is sent. Mandatory. |
QueueId | Guid? | Optional queue id related to requesting the authorization. |
CallListId | Guid? | Optional related call list id when requesting the authorization. |
CallStrongAutheticationResponse
Property name | Value type | Description |
---|---|---|
RequestId | Guid | Request id used for the event publish. |
Token | String | JWT token that is used to fetch the authentication result from the call extra data endpoint. Token is valid for 15 minutes. |
Success | bool | Indicates if the request was success. |
CLIStatus
Property name | Value type | Description |
---|---|---|
ActiveCLI | CLINumber | Currently active value. CLINumber |
CLINumber
Property name | Value type | Description |
---|---|---|
DisplayName | String | Display text for the number |
Value | String | Actual number |
CLIConfiguration
Property name | Value type | Description |
---|---|---|
AvailableNumbers | List |
List of available numbers. CLINumber |
CLIActivationRequest
Property name | Value type | Description |
---|---|---|
Phonenumber | String | Requested number. Must be contained in the authorized numbers list. |
Permanent | bool? | If the activation should be permanent instead of time-scoped. |
CLIActivationResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
WrapUpTerminateResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
SupervisionMonitorCallRequest
Property name | Value type | Description |
---|---|---|
CallId | Guid | Call id to monitor. |
LegId | Guid | LegId id to monitor. |
SupervisorLegId | string | Supervisor LegId id for monitoring. Only if known by the supervisor UI. |
State | int : SupervisionCommand | Set the state of the supervision, see below. |
SupervisionCommand enum
Key | Value | Description |
---|---|---|
NA | -1 | Not set, unknown |
Join | 1 | Join the call |
UnJoin | 2 | Leave the call supervision |
Listen | 3 | |
Whisper | 4 | |
Participate | 5 | |
Select | 6 | Supervisor selects call for supervision |
SupervisionAssistanceRequest
Property name | Value type | Description |
---|---|---|
SupervisorUserId | Guid? | Supervisor user id to request. If null then request any supervisor. |
CallId | Guid | Call id to monitor. |
SupervisionResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
SupervisionSubscription
Property name | Value type | Description |
---|---|---|
Id | Guid | Subscription id. |
TargetUserId | Guid | User id to supervise. |
SupervisorUserId | Guid | Supervisor user id. |
Active | bool? | Is subscription active. |
Once | bool? | Specifies if the subscription is for the current call only. Will not be stored in DB but sent through message queue. |
User call lists
Things related to user call lists.
GET /users/{userid}/calllists/status
- Url parameters:
- userid - target user
- Query parameters: none
- Request content: none
- Response content: List<CallListMember>
Returns all call lists bindings with user status relating to this user.
GET /users/{userid}/calllists
- Url parameters:
- userid - target user
- Query parameters: none
- Request content: none
- Response content: List<CallListMember>
Returns all call list bindings relating to this user. Does not return user status.
GET /users/{userid}/calllists/{listid}
- Url parameters:
- userid - target user
- listid - target callbacklist
- Query parameters: none
- Request content: none
- Response content: CallListMember
Returns a call list binding relating to this user and given callbacklist. Does not return user status.
Example Example JSON serialization of a CallListUser
{
"ListId": "4ad13bbd-82e5-4f5f-a898-7a5af35684fd",
"UserId": "e272c88b-febd-4136-86b8-34ac854bc0b9",
"Active": "false",
"Modified": "2019-08-15T13:34:45.9160524Z"
}
PUT /users/{userid}/calllists/{listid}
- Url parameters:
- userid - target user
- listid - target callbacklist
- CallListMember - updated list
- Query parameters: none
- Request content: none
- Response content: CallListMember
Creates or updates the call list binding relating to this user and given callbacklist.
Example usage with APIClient
CallListMember entity = new CallListMember()
{
UserId = AuthUser.UserID,
ListId = callbackList.Id,
Active = "true"
};
Client.UpdateUserCallList(entity);
DELETE /users/{userid}/calllists/{listid}
- Url parameters:
- userid - target user
- listid - target callbacklist
- Query parameters: none
- Request content: none
- Response content: CallListMember
Deletes a binding relating to this user and given callbacklist.
User features
Things related to user features.
POST /users/{userid}/features/callout/activate
The next outbound call to the number
+123456789
will be made as a service call on behalf of a queue.
POST /users/me/features/callout/activate
{
"TargetNumber": "+123456789",
"QueueId": "11111111-1111-1111-1111-111111111111"
}
The next outbound call to the number
+123456789
will be made as a service call on behalf of a callback request.
POST /users/me/features/callout/activate
{
"TargetNumber": "+123456789",
"CallbackListId": "22222222-2222-2222-2222-222222222222",
"CallbackRequestId": "33333333-3333-3333-3333-333333333333"
}
Notifies the call control backend that the next outbound call the user will make is an outbound-queue call or an outbound-callback call instead of a direct call. This affects the following:
- Call type will be "service call" instead of "direct call."
- CLI and call recording configuration used come from the queue or callback list.
- Ownership of the call information and call recording will be from the queue or callback list.
The actual phone call must be initiated within 10 seconds after this API call. If the delay between the API call and the actual phone call arriving at the backend is more than 10 seconds, the phone call will be treated as a direct call.
To make calls on behalf of a queue, the user must be a member of the queue (active or inactive).
To make calls on behalf of a callback list, the user must be authorized to handle callback requests.
The user can only make callout/activate requests as themselves.
- Url parameters: userid - targeted user
- Request content: OutboundServiceCallActivationRequest
- Response content: OutboundServiceCallActivationResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if the target user is not authorized to make calls on behalf of a queue/callback list.
GET /users/{userid}/features/callout/configuration
Returns outbound call configuration
GET /users/me/features/callout/configuration
{
"Queues": [
{
"QueueId": "11111111-1111-1111-1111-111111111111",
"Name": "Queue 1",
"Numbers": [
{
"Default": "true",
"DisplayNumber": "+123456789",
"DisplayName": "+123456789"
},
{
"Default": "false",
"DisplayNumber": "+987654321",
"DisplayName": "IVR"
}
],
"Recorded": "true"
},
{
"QueueId": "22222222-2222-2222-2222-222222222222",
"Name": "Queue 2",
"Numbers": [
{
"Default": "true",
"DisplayNumber": "+1234567899",
"DisplayName": "+1234567899"
}
],
"Recorded": "false"
}
}
Get configuration for outbound call.
- Url parameters: userid - targeted user
- Response content: OutboundQueueConfigurations
Return codes:
- 200 OK if success.
- 403 Forbidden if the target user is not authorized to get configuration.
POST /users/{userid}/features/calls/allocate-next
Example request, to wait max 5 seconds for inbound servicecall to be allocated
POST /users/me/features/calls/allocate-next
{
"TTLSeconds": 5
}
Response, if there is inbound servicecall to be allocated
Response:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"AllocationType": "allocated",
"Success": true
}
Response, if there are no inbound servicecalls to allocate:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"AllocationType": "nocalls",
"Success": true
}
Invokes to allocate next inbound servicecall to the user. Requires that user is in fetch-allocation mode (user setting Queues_AllocationMode
= "fetch")
Endpoint will wait for a period of time, defined by TTLSeconds in request if there are no servicecalls to be allocated. If there are, endpoint responds immediately, and call is allocated to the user.
- Url parameters: userid - targeted user
- Request content: CallAllocationRequest
- Response content: CallAllocationResponse
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 503 ServiceUnavailable if not success. Occurs when backend services are not operational.
POST /users/{userid}/features/calls/strong-authentication
Example request
POST /users/me/features/calls/strong-authentication
{
"CallId": "22222222-2222-2222-2222-222222222222",
"CallerNumber": "+3581234567"
}
Response.
Response:
{
"RequestId": "00000000-0000-0000-0000-000000000000",
"Token": "JWT",
"Success": true
}
Invokes strong authentication to a call. The authentication result can be fetched from the call extra data endpoint using the JWT token as query parameter.
- Url parameters: userid - targeted user
- Request content: CallStrongAutheticationRequest
- Response content: CallStrongAutheticationResponse
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized to initiate strong authentication for call.
- 503 ServiceUnavailable if not success. Occurs when backend services are not operational.
GET /users/{userid}/features/cli
Calling Line Identification (CLI) is the phone number displayed on the called phone.
Returns the current active CLI value for a user.
- Url parameters: userid - targeted user
- Response content: CLIStatus
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
GET /users/{userid}/features/cli/configuration
Returns list of available values for a user to be used as CLI.
- Url parameters: userid - targeted user
- Response content: CLIConfiguration
Return codes:
- 200 OK if success.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
POST /users/{userid}/features/cli/activate
Invokes to activate cli.
Endpoint call will wait for a short period of time to allow the event message to be delivered. After the return a call can be made.
If target user is the authenticated user and has read permission to settings. Validates that the given phonenumber is contained in the authorized numbers list.
- Url parameters: userid - targeted user
- Request content: CLIActivationRequest
- Response content: CLIActivationResponse
Return codes:
- 202 Accepted if success.
- 400 BadRequest if validation fails.
- 403 Forbidden if target user is not authorized.
- 404 NotFound if user has no CallAsSetting.
POST /users/{userid}/features/wrapup/terminate
Invokes to terminate wrap-up manually.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If target user is the authenticated user, no additional authorization is required.
If the target user is someone else, authorize with QueueUser.UPDATE
- Url parameters: userid - targeted user
- Content-Length: 0
- Request content: none
- Response content: WrapUpTerminateResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if target user is not authorized
POST /users/{userid}/features/supervision/monitorcall
Invokes supervisor to monitor a call.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionMonitorCallRequest
- Response content: SupervisionResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if not authorized
POST /users/{userid}/features/supervision/assistancerequest
Invokes user to ask supervisor assistans.
This is a fire-and-forget call, meaning that the API returns immediately after successfully receiving the message without waiting for the status to be processed.
If user is self and target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionAssistanceRequest
- Response content: SupervisionResponse
Return codes:
- 202 Accepted if success.
- 403 Forbidden if not authorized
POST /users/{userid}/features/supervision/subscriptions
Creates supervision subscription.
If user is self and target user has CallSupervise.READ permission then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionSubscription
- Response content: SupervisionSubscription
Return codes:
- 200 Success.
- 400 BadRequest if invalid target user
- 403 Forbidden if not authorized
PUT /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Updates the supervision subscription. This can be used to update the subscription active status.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Request content: SupervisionSubscription
- Response content: SupervisionSubscription
Return codes:
- 200 If success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
GET /users/{userid}/features/supervision/subscriptions
Gets supervision subscriptions for given user.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: List<SupervisionSubscription>
Return codes:
- 200 Success.
- 403 Forbidden if not authorized
GET /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Get the supervision subscription for given user.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: SupervisionSubscription
Return codes:
- 200 Success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
DELETE /users/{userid}/features/supervision/subscriptions/{subscriptionid}
Deletes the supervision subscription.
If user is self then call is authorized.
- Url parameters: userid - targeted user
- Response content: SupervisionSubscription
Return codes:
- 200 If success.
- 403 Forbidden if not authorized
- 404 NotFound if user has no Subscription.
OutboundServiceCallActivationRequest
This class represents a request for call out activation. There mast be either QueueId or CallbackListId and CallbackRequestId set.
Property name | Value type | Description |
---|---|---|
TargetNumber | string | Required. Target number of the next call out by the user. Helps to verify that correct call will be processed. Note that the number is expected to be provided in E.164 format (+358101231234) |
CallbackRequestId | Guid | Optional: If the call out is related to handling a specific callback request, then (and only then) this must be provided. |
CallbackListId | Guid | Optional: If the call out is related to handling a specific callback request, then (and only then) this must be provided. |
QueueId | Guid | Optional: If the call out is an outbound service call on behalf of a service queue, then (and only then) this must be provided. |
CLI | string | Optional. CLI to use for the call out. If not set, the default CLI of the queue or callback list is used. Setting CLI can be disabled for a queue or callback list, in which case CLI given in request is ignored. |
TimeToLive | int | Optional: How many seconds this request is valid. If no call is received after the specified timeout, the request is dropped as expired Actual usage depends on the use case. If you know that the call will be coming in soon, this should be set to a low value (seconds). If this is a "pre-reservation" of a call that may happen after a while, for example if the user needs to dial manually, then a higher value can be provided. |
OutboundServiceCallActivationResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | Guid | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
CLI | string | Caller number. |
IsRecorded | bool | Indicates if the call is recorded. |
PrePrompt | bool | Indicates if there will be pre-prompt played before connecting the agent and customer. |
OutboundQueueConfigurations
Property name | Value type | Description |
---|---|---|
Queues | List |
Queues user can use. OutboundQueueConfiguration |
OutboundQueueConfiguration
Property name | Value type | Description |
---|---|---|
QueueId | Guid? | QueueId |
Name | string | Queue name |
Numbers | List |
Queue numbers OutboundQueueNumber |
Recorded | bool? | Will the call be recorded. |
OutboundQueueNumber
Property name | Value type | Description |
---|---|---|
Default | bool? | Default number. |
DisplayNumber | string | Display number. |
DisplayName | string | Display name for the number. Used to help the user choose the right number. |
CallAllocationRequest
This class represents a request for call allocation
Property name | Value type | Description |
---|---|---|
TTLSeconds | int | The time-to-live (TTL) for the call allocation request, in seconds. Must be between 0 and 60. |
CallAllocationResponse
Property name | Value type | Description |
---|---|---|
RequestId | Guid | Request id used for the event publish. |
AllocationType | String | Allocation type: allocated = Call allocated, nocalls = No calls to allocate for the agent, agentunavailable = Call could not be allocated following the normal allocation rules(agent was DND, afterwork etc). |
Success | bool | Indicates if the request was success. |
CallStrongAutheticationRequest
This class represents a request for call strong authentication
Property name | Value type | Description |
---|---|---|
CallId | Guid | Id of the call for which the strong authentication is made. Mandatory. |
CallerNumber | String | E.164 format caller number where the strong authetication SMS request is sent. Mandatory. |
QueueId | Guid? | Optional queue id related to requesting the authorization. |
CallListId | Guid? | Optional related call list id when requesting the authorization. |
CallStrongAutheticationResponse
Property name | Value type | Description |
---|---|---|
RequestId | Guid | Request id used for the event publish. |
Token | String | JWT token that is used to fetch the authentication result from the call extra data endpoint. Token is valid for 15 minutes. |
Success | bool | Indicates if the request was success. |
CLIStatus
Property name | Value type | Description |
---|---|---|
ActiveCLI | CLINumber | Currently active value. CLINumber |
CLINumber
Property name | Value type | Description |
---|---|---|
DisplayName | String | Display text for the number |
Value | String | Actual number |
CLIConfiguration
Property name | Value type | Description |
---|---|---|
AvailableNumbers | List |
List of available numbers. CLINumber |
CLIActivationRequest
Property name | Value type | Description |
---|---|---|
Phonenumber | String | Requested number. Must be contained in the authorized numbers list. |
Permanent | bool? | If the activation should be permanent instead of time-scoped. |
CLIActivationResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
WrapUpTerminateResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
SupervisionMonitorCallRequest
Property name | Value type | Description |
---|---|---|
CallId | Guid | Call id to monitor. |
LegId | Guid | LegId id to monitor. |
SupervisorLegId | string | Supervisor LegId id for monitoring. Only if known by the supervisor UI. |
State | int : SupervisionCommand | Set the state of the supervision, see below. |
SupervisionCommand enum
Key | Value | Description |
---|---|---|
NA | -1 | Not set, unknown |
Join | 1 | Join the call |
UnJoin | 2 | Leave the call supervision |
Listen | 3 | |
Whisper | 4 | |
Participate | 5 | |
Select | 6 | Supervisor selects call for supervision |
SupervisionAssistanceRequest
Property name | Value type | Description |
---|---|---|
SupervisorUserId | Guid? | Supervisor user id to request. If null then request any supervisor. |
CallId | Guid | Call id to monitor. |
SupervisionResponse
Property name | Value type | Description |
---|---|---|
CorrelationId | String | Correlation id used for the event publish. |
Success | bool | Indicates if the request was success. |
SupervisionSubscription
Property name | Value type | Description |
---|---|---|
Id | Guid | Subscription id. |
TargetUserId | Guid | User id to supervise. |
SupervisorUserId | Guid | Supervisor user id. |
Active | bool? | Is subscription active. |
Once | bool? | Specifies if the subscription is for the current call only. Will not be stored in DB but sent through message queue. |
WebRTC
Endpoints and data descriptions for implementing WebRTC phone functionality.
GET /users/{userid}/webrtcsettings
- Url parameters: userid - Target user
- Query parameters: none
- Request content: none
- Response content: WebRTCUserConfiguration
Get WebRTC settings for the user.
Authorized with SettingAdministrator.Read on target user.
Return codes:
- 403 if unauthorized
- 404 if user has no WebRTC support
- 500 if backend configuration is missing
GET /token/{userid}/webrtc
- Url parameters: userid - User to generate token for
- Query parameters: none
- Request content: none
- Response content: JWT
Generates access tokens to access WebRTC backend.
Requires SettingAdministrator.Read authorization on the target user. If available, access tokens can be created on behalf of others too.
Return codes:
- 403 if access is prohibited
- 404 if user has no WebRTC support
- 500 if backend configuration is missing
WebRTCUserConfiguration
DTO returned to end-user clients
{
"SipUriDomain": "beneservices.com",
"Sipusername": "+3581231234",
"SipPassword": "pass",
"Servers": [
{
"SipUri": "fs-webrtc-srv1.beneservices.com:443",
"TurnServerUri": "fs-webrtc-srv1.beneservices.com:30111",
"TurnServerUserName": "user",
"TurnServerUserPassword": "password"
},
{
"SipUri": "fs-webrtc-srv2.beneservices.com:443",
"TurnServerUri": "fs-webrtc-srv2.beneservices.com:30111",
"TurnServerUserName": "user",
"TurnServerUserPassword": "password"
}
],
"JWTAuthEndpoint": "https://beneapi.beneservices.com/token/aaa-bbbb/webrtc",
"JWTValidityPeriod": 60
}
Property name | Value type | Description |
---|---|---|
SipUriDomain | string | SIP URI domain name associated to the User Agent |
SipUsername | string | User's SIP user name used for registering |
SipPassword | string | Global password (for technical needs) |
Servers | List<WebRTCServerInfo> | Actual list of servers |
JWTAuthEndpoint | string | Relative path to the API endpoint to get the JWT |
JWTValidityPeriod | int | JWT validity period (in seconds) |
WebRTCServerInfo
DTO describing an individual WebRTC server a client can connect to.
Includes TURN server information.
Property name | Value type | Description |
---|---|---|
SipUri | string | WebSocket server URL without the (wss://). Used to send and receive SIP traffic. Example value: fs-webrtc-srv2.beneservices.com:443 |
TurnServerUri | string | TURN server URL (without the turn://). Example value: fs-webrtc-srv2.beneservices.com:30111 |
TurnServerUserName | string | TURN server username. Example value: user |
TurnServerUserPassword | string | TURN server password. Example value: password |
JWT
{
"Token":"abc1234"
}
Object returned from token endpoint.
Property name | Value type | Description |
---|---|---|
Token | String | Generated access token |
RTE
Token retrieval for WebSocket API (RTE). See more details in RTE documentation.
GET /token/{userid}/rte
- Url parameters: userid - User to generate token for
- Query parameters: none
- Request content: none
- Response content: RTE token response
Generates access tokens to access RTE.
Note that the token can only be generated for the authenticated user. Generating tokens administratively for other users is not supported.
Return codes:
- 200 if token is generated successfully
RTE token response
{
"Token": "abcd1234",
"WSSEndpoint": "https://rte-silox.enreachvoice.com"
}
Property name | Value type | Description |
---|---|---|
Token | string | Base64 encoded JWT token |
WSSEndpoint | string | RTE server endpoint |
RTE JWT token structure
JWT token structure for RTE access token.
Example decoded JWT token:
{
"b.oid": "1111111-1111-1111-1111-111111111111",
"b.uid": "2222222-2222-2222-2222-222222222222",
"jti": "33333333-3333-3333-3333-333333333333",
"nbf": 1697201042,
"exp": 1697204702,
"iat": 1697201102,
"iss": "api-silox.enreachvoice.com",
"aud": "https://rte-silox.enreachvoice.com"
}
Property name | Value type | Description |
---|---|---|
b.oid | string | OrganizationId of the user, for whom token is generated |
b.uid | string | UserId of the user, for whom the token is generated |
jti | string | JWT ID, unique identifier for the token |
nbf | int | Not Before Time as Unix timestamp |
exp | int | Expiration Time as Unix timestamp |
iat | int | Issued Time as Unix timestamp |
iss | string | Issuer, i.e. REST API issued the token |
aud | string | Audience, i.e. rte-endpoint for the user |
Token validation
The API exposes configuration that the relying parties must use for validating the JWTs generated by the API.
GET /token/configuration
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: PublicJWTConfiguration
Returns the token configuration the client can use to validate tokens generated by the API
GET /token/keys
- Url parameters: none
- Query parameters: none
- Request content: none
- Response content: PublicJWKSet
Returns the collection of public signing keys.
Backwards-compatibility endpoint. Prefer the /configuration/ endpoint to receive other relevant configuration as well.
PublicJWTConfiguration
Configuration that the relying parties use for validating JWTs generated by the API.
{
"issuer": "beneapi.beneservices.com",
"keyset":
{
"keys": [
{
"alg": "RS256",
"e": "AQAB",
"kid": "80563dcf-5b21-4291-8bbf-c00706b6bc9f",
"kty": "RSA",
"n": "3C3jnwuFNmrfQ7CsUAZPjAeeRJLNRbF0GH4ZGlWrOEH3mcaz7uGqcE1fDZD9h2geEQH9g8lxV51T1Mul7ZGfj-920-4dQANcUqJQfSpiwyezfFhmrxQKvfRYQgGXHewVwMusc6o3O7hkOAxUS_Qtnc_umWbV3zrmzLBpTubtqP06mltNfXTbuOatTgv4u8jCC3XPfeHzu6Re5vYdtgxpD7QKGb9vFI4GAVBnx6rgaerubuphNMEUhjRgdg1Svd3NxrgUmQ46qaAk2C426bCCaYDJIo4uPIugMr096Rrb1ojp2GGidx94Zw3kAsuT4rEFDfMVOJ-s4hlHJNllt04p9Q"
}
]
}
}
Property name | Value type | Description |
---|---|---|
issuer | string | The issuer name to expect for received tokens |
keyset | PublicJWKSet | The keyset used for token signature validation |
PublicJWKSet
Property name | Value type | Description |
---|---|---|
keys | List<JWK> | Set of public keys to validate the token signature. The format follows RFC 7517 (https://datatracker.ietf.org/doc/html/rfc7517) |
JWK
Public key
Property name | Value type | Description |
---|---|---|
kid | string | Key identifier |
alg | string | Algorithm to use (e.g. RSA256) |
kty | string | Key type: Always RSA |
e | string | Key exponent for RSA keys. Part of public key. |
n | string | Key modulus for RSA keys. Part of public key. |