Gå til hovedindhold

Kom i gang med Dstny's bruger-API

Opdateret

I denne artikel:

    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.

    Opret ny token via web

    Login med brugeren på https://connect.ipvision.dk - og vælg evt brugervisning til højre for menuen. 

    Under Hjem -> Tokens kan der oprettes en token til api. Bemærk at tokens oprettet via web altid gælder i et år og indtil den bliver slettet. Se også afsnittet API rettigheder.

     

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

    Relaterede artikler

    Kommentarer

    0 kommentarer

    Log ind for at kommentere.