The PureEngage Cloud API. Jim Crespino Director, Developer Enablement

Transcription

1

2 The PureEngage Cloud API Jim Crespino Director, Developer Enablement

3 The PureEngage Cloud API Analogous to the Platform SDK for PureEngage Premise Monolithic (v8.5) -> Microservices (v9.0) Architecture GWS 9.0 is NOT backward compatible with GWS 8.5 GWS 8.5 & 9.0 can run side-by-side Each Cloud Product may have its own API Agent Setup -> Provisioning API Workspace -> Workspace API

4 What is a Microservice, and why do I care? A microservice architecture is a method of developing software applications as a suite of independently deployable, small, modular services in which each service runs a unique process and communicates through a well-defined, lightweight mechanism to serve a business goal. All APIs share core services, cache, etc. Each development team to create and maintain their own API built on the core services. New features and fixes to one API does not affect the other and can be independently deployed.

5 Currently Available APIs Authentication API Validates credentials and/or application access Provisioning API Provision contact center agents Workspace API An API for Agent/Supervisor applications Statistics API A real-time statistics API over CometD

6 Getting Started with the PureEngage Cloud API

7 The PureEngage Cloud Developer Portal Includes: API Explorer Library Wrappers Tutorials Features on the Roadmap: Articles/Blogs Community Support Forum Log Viewer

8 GitHub Samples Available in: Java Javascript (Node.js).NET (C#) Libraries include: Authentication API Provisioning API Workspace API Statistics API

9 API Keys and Credentials x-api-key custom HTTP header A unique key value that must be specified in the HTTP header of each API request Validated by the API Gateway Client ID & Secret Credentials that are used to authenticate that an application should be allowed to make API requests Keys and credentials are currently generated by Genesys DevOps as access to the Cloud API is approved.

10 URL Schemes API URL: Application URL:

11 Authentication API

12 Authentication API Overview An API to verify that you are who you say you are Implements standard OAuth SAML supported behind the scenes Supported Grant Types: Authorization Code Implicit Resource Owner Password Credentials Client Credentials

13 OAuth Terminology Grant type One of the methods of implementing OAuth Authorization Code The temporal intermediate code used only in the Authorization Code Grant. This is not used to make authenticated API requests. Access Token The temporal token that identifies a user when making authenticated API requests Client ID The identifier (GUID) of an OAuth client Client Secret A secret code for an OAuth client used in Auth Code and Client Credentials grants. This value should be handled with the same security as a password. Redirect URI A URI/URL that the user will be redirected to after entering valid credentials during an Implicit or Auth Code grant. OAuth Client A configuration in PureEngage Cloud that generates a Client ID and Client Secret.

14 Grant Types Authorization Code Grant Two step process Application redirects end-user to Auth Service to login to PureEngage Cloud After successful login, redirects back to application with a code Code must be exchanged for an access token. Implicit Grant Single step process Similar to Authorization Code Grant Successful login redirects back to application with an access token Resource Owner (Password) Grant Single step process End-user credentials are passed in the body of the request and an access token is returned Client Credentials Grant Single stop process Authenticates using only Client ID and Client Secret Operates outside the scope of a user Useful for headless applications that do not have a UI for a user to authenticate

15 Authorization Code Grant GET /auth/v3/oauth/authorize&response_type=code&scope=*& client_id={{client_id}}&redirect_uri= x-api-key: {{api_key}} Authorization: Basic {{client_id_and_secret}} User authenticates via UI presented by Authentication service Redirect after success login Code must be exchanged for a token by calling /auth/v3/oauth/token

16 Implicit Grant GET /auth/v3/oauth/authorize&response_type=token& client_id={{client_id}}&redirect_uri= x-api-key: {{api_key}} Authorization: Basic {{client_id_and_secret}} User authenticates via UI presented by Authentication service Redirect after success login cf4f23d70a07&token_type=bearer&expires_in=43199

17 Password Grant Example POST /auth/v3/oauth/token Authorization: Basic {{client_id_and_secret}} Content-Type: application/x-www-form-urlencoded x-api-key: {{api_key}} grant_type=password&scope=*&client_id=5446b017f a2aa a2ed97&refresh_token=&username={{domain}} \{{user}}&password={{password}} HTTP 200 OK { "access_token": "5ac7c e-468c-9bba-c5bbc94f5bfc", "token_type": "bearer", "refresh_token": "5f51be0f-cab8-4e78-951c-b97340fd10cd", "expires_in": 42882, "scope": "* }

18 Figuring out who the user is Using OAUTH, your application may never see the username or password Your application will most likely need to know who the user is that logged in After authentication, you may query user information

19 Userinfo Request GET /auth/v3/userinfo Authorization: bearer 5ac7c e-468c-9bba-c5bbc94f5bfc x-api-key: {{api_key}} 200 OK { "username": "jim.crespino@genesys.com.com:8745:bf0eb d-ba6a-63bd4cfb00be", "loginname": "jim.crespino@genesys.com", "authorities": [{"name": "ROLE_AGENT"}], "environmentid": "018d4180-5be9-48b a3501a4a2edf", "contactcenterid": "bf0eb d-ba6a- 63bd4cfb00be", "dbid": 8745, "cmeusername": "jim.crespino@genesys.com" }

20 Provisioning API

21 Provisioning API Overview The REST API that powers Agent Setup Provides CRUD operations on config server person objects A single request can provision person, place, dn, agent login, etc. Read operations for skills, DNs, and agent groups Bulk Import/Export of Users from CSV file Provisioning API library available for Java, Javascript, and C# Swagger Doc: /provisioning/v3/doc Must include x-api-key header

22 Provisioning Application Flow Get Auth Token: /auth/v3/oauth/authorize Login: /provisioning/v3/initialize-provisioning Perform operations: /provisioning/v3/users Logout: /provisioning/v3/logout

23 Login Request POST {{baseurl}}/provisioning/v3/initializeprovisioning x-api-key: {{api_key}} Accept: application/json Content-type: application/json { code": B6C7H1 } 200 OK { "status":{"code":0}, "data":{"sessionid":"9d1c0f82-6bb6-41a8-97b3-4f69e2b5a6a0"} }

24 Request: /provisioning/v3/users/me GET /provisioning/v3/users/me Authorization: bearer {{access_token}} x-api-key: {{api_key}}

25 Response: /provisioning/v3/users/me { "status":{"code":0}, "data": { "user": { "lastname": "Crespino", "firstname": "Jim", "employeeid": "jcrespin_admin@tiaa.com", "username": "jcrespin_admin@tiaa.com", "isagent": false, " address": "jcrespin_admin@tiaa.com", "id": "person-8804", "enabled": true, "wrapuptime": 0, "domainusername": "jcrespin_admin@tiaa.com", "settings": {}, "tenantname": "TIAA",... } } }

26 Creating a New User POST /provisioning/v3/users Authorization: bearer {{access_token}} x-api-key: {{api_key}} { "username": john.doe@genesys.com", "firstname": John", "lastname": Doe", "password": Password1", " address": john.doe@genesys.com", "employeeid": john.doe@genesys.com", "enabled": true, "isagent": true, "phones": [{"number":" ","description": Mobile", "isdefault":true, "placename": "}], "skills": [{"level": 1,"name": "SimpleSkill"}], } 200 OK { "status":{"code":0} }

27 Get Skills GET /provisioning/v3/users/skills Authorization: bearer {{access_token}} x-api-key: {{api_key}} 200 OK { "data": { "skills": [ {"name": "HR_ALL","DBID": "281 }, {"name": "HR_COMPENSATION","DBID": "282"}, {"name": "HR_CORE_ONLINE_INFO","DBID": "283"},... ] }, "status": {"code": 0} }

28 Logout Request POST /provisioning/v3/logout Authorization: bearer {{access_token}} x-api-key: {{api_key}} 200 OK { "status": { "code":0, "message":"logged out } }

29 Workspace API

30 Workspace API Overview The REST API that powers Workspace (WWE) Provides for Agent and Supervisor operations Voice is the initial channel with chat to follow in mid/late 2018 Swagger Doc: /workspace/v3/doc Must include x-api-key header

31 Workspace Application Flow Get Auth Token: /auth/v3/oauth/token Initialize CometD event channel subscriptions: /workspace/v3/notifications/subscribe Channel: /workspace/v3/initialization Channel: /workspace/v3/voice Initialize Workspace API: /workspace/v3/initialize-workspace Handle WorkspaceInitializationComplete event Activate Channels (Voice): /workspace/v3/activate-channels Handle DnStateChanged, CallStateChanged, or EventError events Disconnect CometD Logout: /workspace/v3/logout

32 Important Application Notes x-api-key custom HTTP header MUST be sent on every request, even CometD event polling requests GWS uses cookies to manage load balancing and sessions, so a global cookie container should be utilized for the lifetime of your application for all requests

33 Initializing Workspace POST /workspace/v3/initialize-workspace?code= &redirect_uri= Authorization: bearer {{access_token}} x-api-key: {{api_key}} 200 OK {"status": {"code": 1}}

34 WorkspaceInitiazationComplete CometD Event { "channel":"/workspace/v3/initialization", "data":{ "state":"complete", "data":{ user":{ "dbid":8745, "firstname":"jim", "lastname":"crespino", "username":"jim.crespino@genesys.com", "employeeid":"jimc123", "userproperties":[], "tenantdbid":1, "agentlogin":"jimc }, "configuration":{ "actioncodes":[],"agentgroups":[],"settings":[], "transactions":[],"businessattributes":[]}}, "messagetype":"workspaceinitializationcomplete"} }

35 Activate Channels: Voice POST /workspace/v3/activate-channels Authorization: bearer {{access_token}} x-api-key: {{api_key}} { data":{ "agentid":"jimc", "agentworkmode":"manualin } } 200 OK {"status": {"code": 1}}

36 DnStateChanged Event { "channel":"/workspace/v3/voice", "data":{ "dn":{ "number":" ", "switchname":"sip_cluster", "agentid":"jimc", "capabilities": ["ready","not-ready","dnd-on", "set-forward","startmonitoring"], "agentstate":"loggedout", "agentworkmode":"unknown"}, "messagetype":"dnstatechanged"} }

37 Ready POST /workspace/v3/voice/ready Authorization: bearer {{access_token}} x-api-key: {{api_key}} {} 200 OK {"status": {"code": 1}}

38 DnStateChanged { "channel":"/workspace/v3/voice", "data":{ "dn":{ "number":" ", "switchname":"sip_cluster", "agentid":"jimc", "capabilities":["ready","not-ready","dnd-on", "set-forward","startmonitoring"], "agentstate":"ready", "agentworkmode":"unknown", "reasons":[]}, "messagetype":"dnstatechanged"} }

39 Make Call POST /workspace/v3/voice/make-call Authorization: bearer {{access_token}} x-api-key: {{api_key}} {"data":{"destination":" "}} 200 OK {"status": {"code": 1}}

40 CallStateChanged Event { "channel":"/workspace/v3/voice", "data":{ "notificationtype":"statechange", "call":{ "id":"019602adfe441f7c", "phonenumber":" ", "connid":"019602adfe441f7c", "calluuid":" j2ocud5k4l6u362laes0007td", "extensions":[], "dnis":" ", "calltype":"outbound", "state":"dialing", "participants":["number":" ","role":"roledestination"}], "capabilities":["release","clear","attach-user-data","update-user-data", "delete-user-data-pair","start-recording","send-dtmf"], "duration":0}, "messagetype":"callstatechanged" }}

41 Logout POST /workspace/v3/logout Authorization: bearer {{access_token}} x-api-key: {{api_key}} {} 200 OK {"status": {"code": 0}}

42 Statistics API

43 Statistics API Overview Real-time statistics feed over CometD A thin layer on top of Statistics Platform SDK Statistics subscriptions use standard statistic properties Object Type Object ID Category Subject Mask Swagger Doc: /statistics/v3/doc Must include x-api-key header

44 Real-time Statistics Application Flow Get Auth Token: /auth/v3/oauth/token Initialize CometD event channel subscriptions: /statistics/v3/notifications/subscribe Channel: /statistics/v3/service Channel: /statistics/v3/updates Subscribe to one or more Genesys statistics: /statistics/v3/subscriptions Handle /statistics/v3/updates events Delete Subscriptions

45 Peek Statistics Application Flow Get Auth Token: /auth/v3/oauth/token Subscribe to one or more Genesys statistics: /statistics/v3/subscriptions Loop and request statistics values: /statistics/v3/{operationid}/statistic-values Delete Subscriptions: /statistics/v3/{operationid}/delete

46 Statistics Subscription: Example JSON { } "operationid":"69731cb2-859f-41ff-8b14-f57b19486b89", "data":{ "statistics":[ { "statisticid": AgentStatus jim.crespino@genesys.com", "objectid":"jimc123", "objecttype":"agent", "definition":{ "notificationmode":"immediate", "category":"currentstate", "subject":"agentstatus", "mainmask":"*", "objects":"agent" } } ] }

47 Statistics Subscription Request POST /statistics/v3/subscriptions Authorization: bearer {{access_token}} x-api-key: {{api_key}} { "operationid": " 69731cb2-859f-41ff-8b14-f57b19486b89 ", "data": { "statistics":[{ "statisticid": AgentStatus jim.crespino@genesys.com", "objectid": "jimc123", "objecttype": "Agent", "definition":{ "notificationmode": "Immediate", "category": "CurrentState", "subject": "AgentStatus", "mainmask": "*", "objects": "Agent } }] }}

48 Statistics Subscription Response { "status": {"code": 0}, "data": { "subscriptionid": 69731cb2-859f-41ff-8b14-f57b19486b89 ", "operationid": " 69731cb2-859f-41ff-8b14-f57b19486b89 ", "statistics": [{ "value": { "intervallength": 0, "statevalue": { "$class": ".AgentStatus", "agentid": "jimc123", "loginid": "LoggedOut", "place": { "$class": ".PlaceStatus", "time": , "dnstatuses": [], "status": 23 }, "time": , "status": 23 }, "tag": -1, "timestamp": , "intvalue": 0 }, "timestamp": , "objectid": "jimc123", "objecttype": "Agent", "statisticid": AgentStatus jim.crespino@genesys.com"}] }}

49 Statistics Values Request GET /statistics/v3/subscriptions/69731cb2-859f-41ff- 8b14-f57b19486b89/statisticvalues?statisticIds=AgentStatus Authorization: bearer {{access_token}} x-api-key: {{api_key}}

50 Statistics Values Response { "status": {"code": 0}, "data": { "subscriptionid": " 69731cb2-859f-41ff-8b14-f57b19486b89 ", "operationid": " 69731cb2-859f-41ff-8b14-f57b19486b89 ", "statistics": [{ "value": { "intervallength": 0, "statevalue": { "$class": ".AgentStatus", "agentid": "jimc123", "loginid": "LoggedOut", "place": { "$class": ".PlaceStatus", "time": , "dnstatuses": [], "status": 23 }, "time": , "status": 23 }, "tag": -1, "timestamp": , "intvalue": 0 }, "timestamp": , "objectid": "jimc123", "objecttype": "Agent", "statisticid": AgentStatus jim.crespino@genesys.com"}] }}

51 Delete Subscription DELETE /statistics/v3/subscriptions/ 69731cb2-859f- 41ff-8b14-f57b19486b89 Authorization: bearer {{access_key}} x-api-key: {{api_key}} 200 OK {"status": {"code": 1}}

52 Troubleshooting

53 Troubleshooting Requests Validate x-api-key, client id, and client secret Make sure network proxies are configured for traffic pass-thru Maintain cookies in desktop applications Verify that users defined in Agent Setup have appropriate roles CometD channel requests must: Send x-api-key HTTP custom header on all requests Send bearer token in HTTP Authorization header Use the same cookie storage as other requests

54 What Now! This Week Visit us in the DevLounge area of the Partner Pavilion After the Event to access our developer portals, Q&A forums, and resources

55 Thank You Visit developer.genesys.com for more information