Kom i gang med Dstny's bruger-API

Beskrivelse

Dstny DK's telefoniplatform kommer med et omfattende JSON REST API, som kan bruges til at:

• Styre kald på brugere (CTI)
• Logge brugere ind/ud af køer
• Afsende SMS'er
• Styre kontakter
• Sætte brugerens aktivitet, rolle, note etc.
• Meget mere...

Dokumentation

Dokumentationen for API'et findes i Swagger-format her:
https://api.connect.ipvision.dk/api/public/docs/mitelepo_enduser.json

Hvis du ikke har en Swagger-parser, kan f.eks. denne anvendes:
http://petstore.swagger.io/

Angiv blot Swagger-URL'en i feltet i toppen for at parse den.

Base-URL'en til API'et er: https://connect.ipvision.dk/

API autorisering

Adgang til API'et sker via en API-token på den bruger, som API-forespørgslerne foretages på vegne af.

Tokenen kan enten oprettes manuelt på brugere eller via API (se mere under Opret ny token via API). 

Denne token anvendes i forespørgslen som et argument, "t", i query-strengen. Alternativt kan den angives som bearer, ved at sætte headeren Authorization med værdien "Bearer <token>".

Eksempel:

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

Eller med bearer, her eksempelvis med curl:

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

Opret ny token via API

Via API'et kan der oprettes en ny token på en bruger, ved at bruge dennes brugernavn, domæne og kode. Derudover kan organisations-administratorer også anvende deres brugernavn, domæne og kode til at oprette en token på en anden bruger.

For at oprette en token skal der laves en signeret token, som laves efter følgende logik:

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

Bemærk: "allowed_apis" er en streng sammensat af navnene på de API'er, som den nye token skal have rettigheder til at tilgå. Se afsnittet API rettigheder for mere information herom.

Med den genererede token kan der oprettes en ny token på den pågældende bruger. Se dokumentationen under "Tickets" for tilgængelige parametre.

Hvis der oprettes en token med et navn, som allerede eksisterer på organisationen, bliver den blot overskrevet, udløbstiden fornyet og en ny token-streng genereret.

 

API rettigheder

API'et er opdelt i sektioner med følgende rettigheder:

Navn	Teknisk navn	Beskrivelse
Kontaktsøgning	CONTACT	Søgning på kontakter
CTI	Intet, altid tilgængeligt	Styring af opkald på brugeren
Brugerinformationer	USER	Se/ændre oplysninger på en bruger
SMS-afsendelse	SMS	Afsendelse af SMS fra brugeren
Køer	DISTRIBUTION_GROUP	Info om køer; antal ledige agenter, log brugeren ind/ud, m.m.
Kommunikationslog	COMMUNICATION_LOG	Hent liste over indgående, udgående og mistede opkald
Personlige kontakter	PERSONAL_CONTACTS	Se/rediger liste over brugerens personlige kontakter

 

HTTP headere

I requesten kan angives følgende headere:

• Accept:
  Anvendes til at bestemme hvilket format API'et returnerer dataen i. I de fleste tilfælde supporteres kun "application/json", men i tilfælde af subscribe på SSE-events, anvendes "text/event-stream" og ved f.eks. API-kald der returnerer CSV, skal det tilsvarende passe til det format, osv.
  Bemærk: API'et har tidligere supporteret både JSON og XML, men XML er ikke længere supporteret og bliver gradvist udfaset.
• Content-Type:
  Anvendes til at angive hvilken type payload der sendes til API'et. De fleste API-kald supporterer kun "application/json"

Nogle forespørgsler kræver ikke at ovenstående headere er sat, men vi anbefaler det i tilfælde af der i fremtiden kommer ændringer så andre formater supporteres.

 

Eksempler med cURL

Se nuværende presence-status på brugeren "jane" på domænet 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å 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 på SSE-events fra CTI-endpointet for brugeren john på domænet example.com (her ringer brugeren til "88887777" som besvarer kaldet og brugeren lægger derefter på):

# 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":[]}]}