Getting started with Dstny's user API – Dstny

I denne artikel:

Description

Dstny DK's telephony platform comes with an extensive JSON REST API, which can be used for:

Call control (CTI)
Logging users in/out of queues
Sending SMS
Managing contacts
Setting/getting activities, roles, notes etc.
Much more....

Documentation

The documentation for the API can be found in Swagger format here:
https://api.connect.ipvision.dk/api/public/docs/mitelepo_enduser.json

If you don't have an Swagger parser, you can use this one:
http://petstore.swagger.io/

Just paste the Swagger URL into the field in the top of the page to generate the documentation.

Base URL for the API is: https://connect.ipvision.dk/

API authorization

Access to the API requires an API token on the user, which the API requests are performed on behalf.

The token can be created manually on users, or via the API (see more under Create new token via the API)

The token is used in the request, either as an argument in the query string, "t", or in an Authorization header, by setting the value to "Bearer <token>".

Example:

GET /api/user/info/example.com/username1/activity?t=<token>

Or as bearer, here using cURL:

curl -X GET -H 'Authorization: Bearer <token>' -H 'Accept: application/json' https://connect.ipvision.dk/api/user/info/example.com/username1/activity

Create new token via the API

A new token can be created on a user, using the API itself. This requires username, domain and password of either the user itself, or an organization administrator, which can create token on other users within the organization. Using these credentials, a signed request token can be calculated.

A signed token is calculated using this logic:

allowed_apis = ":USER:CONTACT"
secret = md5(username + ':' + domain + ':' + password)
token = 'D' + base64(domain) + '.' + base64("P:" + md5(username + allowed_apis + ':' + secret) +':' + username + allowed_apis)

Please notice: "allowed_apis" is a string concatenated by the names of the API's that the new tokens must have permissions to access. See the section API permissions for more informations about this.

With the generated token, a new token can be created on a user. See the section "Tickets" in the documentation for all available parameters when creating new tokens.

If a token is created with a name of an existing token on the user, it will be overwritten. This means the expire time are reset and a new token is generated.

API permissions

The API is divided into sections with the following permissions:


Name	Technical name	Description
Contact search	CONTACT	Search for contacts
CTI	None, always available	Control calls for a user
User informations	USER	Se/change informations for a user
Sending SMS	SMS	Send an SMS from the user
Queues	DISTRIBUTION_GROUP	Info about queues; simple statistics, available agents, log agents in/out
Communication log	COMMUNICATION_LOG	Lists of inbound, outbound and unanswered calls.
Personal contacts	PERSONAL_CONTACTS	See/edit personal contacts for a user

HTTP headers

In the API requests, the following headers may be used:

Accept:
Used to specify which format you want the response to be sent in. In most cases "application/json" should be used, but in case of SSE event streams, "text/event-stream" is used.
Please notice: The API has previously supported both JSON and XML, but XML has been deprecated and are being phased out.
Content-Type:
Used to specify which format a payload has, when sending data to the API. In most cases this should be "application/json".

Examples using cURL

Get current presence state on the user "jane" on the domain "example.com":

# curl -s -X GET -H 'Authorization: Bearer XXXXXXXXXX' -H 'Accept: application/json' https://connect.ipvision.dk/api/user/info/example.com/jane/presence | python3 -m json.tool
{
    "futurePresenceAccess": "WRITE",
    "activityAccess": "WRITE",
    "roleAccess": "WRITE",
    "noteAccess": "WRITE",
    "role": "business",
    "activity": {
        "id": "1511506396223",
        "expiration": "never",
        "available": true
    },
    "idle": false,
    "available": true,
    "capabilities": [
        "MESSAGE",
        "PARTIAL_COLLABORATION",
        "SMS"
    ]
}

Opret ny favorit-kontakt på en brugeren "jane" på domænet example.com:

# curl -s -X POST -H 'Authorization: Bearer XXXXXXXXXX' -H 'Accept: application/json' -H 'Content-Type: application/json' -d '{"company": "Dstny DK", "firstname": "John", "lastname": "Doe", "email": "john.doe@dstny.dk", "street": "Skodsborgvej 305D", "city": "Nærum", "postalcode": "2850", "country": "Denmark", "showInDefaultContactList": false, "contactStatus": "FAVORITE", "ownerType": "USER", "phoneNumbers": [{"type": "WORK", "phoneNumber": "+4588887777", "preferredNumber": true, "abbreviatednumber": "87"}]}' https://connect.ipvision.dk/api/personal_contacts/user/example.com/jane | python3 -m json.tool
{
    "cid": "123456@internal",
    "company": "Dstny DK",
    "firstname": "John",
    "lastname": "Doe",
    "email": "john.doe@dstny.dk",
    "street": "Skodsborgvej 305D",
    "city": "Nærum",
    "postalcode": "2850",
    "country": "Denmark",
    "showInDefaultContactList": false,
    "contactStatus": "FAVORITE",
    "ownerType": "USER",
    "phoneNumbers": [
        {
            "type": "WORK",
            "phoneNumber": "+4588887777",
            "preferredNumber": true,
            "abbreviatednumber": "87"
        }
    ]
}

Subscribe for SSE events from the CTI endpoint, for the user "john" on the domain "example.com" (here, the user calls "88887777" which then answers the call and the user hangs up):

# curl -X GET -H 'Authorization: Bearer XXXXXXXXXX' -H 'Accept: text/event-stream' https://connect.ipvision.dk/api/call/state/v1/sse/example.com/john


retry: 10000
data: {"version":0,"fullState":true,"calls":null}

retry: 10000
data: {"version":1,"fullState":false,"calls":[{"stateToken":1852693392595968,"callId":"d0ac9280-9da6-4b01-ba16-789acdd80620","userId":"john@example.com","remoteParty":{"partyId":null,"type":null,"telUri":"tel:+4588887777","displayName":null,"displayNumber":"88887777"},"participants":[],"conference":false,"conferenceId":null,"historyInfo":{"subject":null,"acdSupport":null,"campOn":false,"initialParty":null,"previousParty":null,"previousRetargetReason":null},"inbound":false,"intruded":false,"status":"INITIATED","event":null,"muted":false,"eventDescription":null,"duration":0,"recordable":false,"recording":null,"recordingDuration":null,"externalRecording":null,"externalRecordingDuration":null,"externalRecordingPaused":null,"deviceIds":["2.f07cabc0-4556-4dc8-9b31-1d934edc53fb"],"actions":[]}]}

retry: 10000
data: {"version":2,"fullState":false,"calls":[{"stateToken":1852694797094866,"callId":"d0ac9280-9da6-4b01-ba16-789acdd80620","userId":"john@example.com","remoteParty":{"partyId":null,"type":null,"telUri":"tel:+4588887777","displayName":null,"displayNumber":"88887777"},"participants":[],"conference":false,"conferenceId":null,"historyInfo":{"subject":null,"acdSupport":null,"campOn":false,"initialParty":null,"previousParty":null,"previousRetargetReason":null},"inbound":false,"intruded":false,"status":"RINGING","event":null,"muted":false,"eventDescription":null,"duration":0,"recordable":false,"recording":null,"recordingDuration":null,"externalRecording":null,"externalRecordingDuration":null,"externalRecordingPaused":null,"deviceIds":["2.f07cabc0-4556-4dc8-9b31-1d934edc53fb"],"actions":[]}]}

retry: 10000
data: {"version":3,"fullState":false,"calls":[{"stateToken":1852698116467978,"callId":"d0ac9280-9da6-4b01-ba16-789acdd80620","userId":"john@example.com","remoteParty":{"partyId":null,"type":null,"telUri":"tel:+4588887777","displayName":null,"displayNumber":"88887777"},"participants":[],"conference":false,"conferenceId":null,"historyInfo":{"subject":null,"acdSupport":null,"campOn":false,"initialParty":null,"previousParty":null,"previousRetargetReason":null},"inbound":false,"intruded":false,"status":"ACTIVE","event":null,"muted":false,"eventDescription":null,"duration":0,"recordable":false,"recording":null,"recordingDuration":null,"externalRecording":true,"externalRecordingDuration":null,"externalRecordingPaused":false,"deviceIds":["2.f07cabc0-4556-4dc8-9b31-1d934edc53fb"],"actions":[{"action":"MOVE","deviceIds":[]},{"action":"TRANSFER","deviceIds":[]},{"action":"SINGLE_STEP_TRANSFER","deviceIds":[]},{"action":"HOLD","deviceIds":[]},{"action":"PARK","deviceIds":[]},{"action":"ADD","deviceIds":[]},{"action":"SEND_DTMF","deviceIds":[]},{"action":"SAVE_REC","deviceIds":[]},{"action":"PAUSE_REC","deviceIds":[]}]}]}

retry: 10000
data: {"version":4,"fullState":false,"calls":[{"stateToken":1852698212020924,"callId":"d0ac9280-9da6-4b01-ba16-789acdd80620","userId":"john@example.com","remoteParty":{"partyId":null,"type":null,"telUri":"tel:+4588887777","displayName":null,"displayNumber":"88887777"},"participants":[],"conference":false,"conferenceId":null,"historyInfo":{"subject":null,"acdSupport":null,"campOn":false,"initialParty":null,"previousParty":null,"previousRetargetReason":null},"inbound":false,"intruded":false,"status":"ACTIVE","event":"EXTERNAL_RECORDING_STARTED","muted":false,"eventDescription":null,"duration":0,"recordable":false,"recording":null,"recordingDuration":null,"externalRecording":true,"externalRecordingDuration":null,"externalRecordingPaused":false,"deviceIds":["2.f07cabc0-4556-4dc8-9b31-1d934edc53fb"],"actions":[{"action":"MOVE","deviceIds":[]},{"action":"TRANSFER","deviceIds":[]},{"action":"SINGLE_STEP_TRANSFER","deviceIds":[]},{"action":"HOLD","deviceIds":[]},{"action":"PARK","deviceIds":[]},{"action":"ADD","deviceIds":[]},{"action":"SEND_DTMF","deviceIds":[]},{"action":"SAVE_REC","deviceIds":[]},{"action":"PAUSE_REC","deviceIds":[]}]}]}

: keepalive

retry: 10000
data: {"version":5,"fullState":false,"calls":[{"stateToken":1852703793679953,"callId":"d0ac9280-9da6-4b01-ba16-789acdd80620","userId":"john@example.com","remoteParty":{"partyId":null,"type":null,"telUri":null,"displayName":null,"displayNumber":null},"participants":[],"conference":false,"conferenceId":null,"historyInfo":{"subject":null,"acdSupport":null,"campOn":false,"initialParty":null,"previousParty":null,"previousRetargetReason":null},"inbound":false,"intruded":false,"status":"TERMINATED","event":"CLEARED","muted":false,"eventDescription":null,"duration":5,"recordable":false,"recording":null,"recordingDuration":null,"externalRecording":true,"externalRecordingDuration":null,"externalRecordingPaused":false,"deviceIds":["2.f07cabc0-4556-4dc8-9b31-1d934edc53fb"],"actions":[]}]}