Digital Channels for a Digital WorldJim CrespinoDirector, Developer Enablement

Genesys Mobile Engagement can…• Make a connected application

• GME helps you create a better mobile, web, or desktop application by intelligently connecting your application to customer service. With GME, you can transform an application into a seamless business conversation.

• Create a personalized customer experience• GME delivers the right live agent at the right time to your mobile application.

• Engage agents effectively• Customers simply push a button and are connected to a customer service agent

without leaving your application. The agent can see information from your application along with the full customer history and preferences. This 360-degree view enables the agent to provide an ideal personalized experience that increases customer engagement.

Genesys Mobile Engagement features are based on services provided by the Genesys Mobile Services (GMS) component.

Services

What is a Service?• A Service is an API that is exposed by Genesys Mobile Services

• Services can be:

• Built-in:

• callback

• request-chat

• request-interaction

• ORS-based

• Your own SCXML application exposed via GMS

• Services are defined as Sections in the Options of the GMS

application object

• Option key/value pairs define how the service should operate

Service Name Examples• Service Section Name Examples

• chat (default catch-all)

• chat.request-chat

• email (default catch-all)

• email.email-survey

• openmedia (default catch-all)

• openmedia.submitter

• service.callme

• service.my-custom-service

• Other sections in GMS Options are related to overall GMS configuration behavior

Callback

Callback Overview

• Callback is a built-in service of GMS

• Enables mobile, web, desktop, and IVR applications to create

callback requests.

• Callback Base URL

• http://<host>:<port>/genesys/1/service/callback/{callback-service-name}

• {callback-service-name} = The name of a callback service defined

in the options of your GMS application object.

• If callback service in the GMS Options is defined in the section named

“service.request-callback” then {callback-service-name} is “request-

callback”

Scope of Use• Scheduled, immediate, or delayed callback requests.• Preview callback requests.• Proactive notification.• Schedule callback with enhancement multimedia confirmation.• Schedule an immediate return call or a callback at a convenient time

of the customer’s choosing, based on operating business hours.• Check and display agent availability by providing estimated wait

times.• Support for mobile push notification to provide an alert when agent

is available.

Use Cases• IVR Callback• If your contact center is busy, use IVR to offer an option for Callback while

retaining the caller’s position in queue, in order to free up valuable IVR resources and optimize contact center resources.

• Credit Card Verification• When a credit card is used abroad without a previous arrangement, the bank

must verify that the user is authorized to accept or reject the transaction.• Vehicle Roadside Assistance• An insurance company offers a Vehicle Roadside Assistance service. When

the car breaks down, the driver uses the mobile app to get assistance.

User Terminated Immediate Callback

User Terminated Delayed Callback

Callback States

StateActive In

ORSDescription

PROCESSING Yes The customer is connected to an agent and talking with this agent.

QUEUED Yes The callback is actively waiting for an agent in ORS/URS; the agent is not assigned yet.

SCHEDULED NoThe Callback service handles the callback (there are no sessions started in ORS). While in this state, the request is handled by the callback service running in GMS until the specified desired_time is approaching.

ROUTING Yes Customer phone is reached and waiting for an agent.

COMPLETED No The call has ended and the Callback is completed with the reason specified in _callback_reason.

Start Callback RequestPOSThttp://demosrv:8010/genesys/1/service/callback/request-callback { "_customer_number":"7854770504",

"_usr_customer_name":"Jim Crespino","_usr_customer_name":"Wants to talk”,"_desired_time":"2017-08-21T23:30:00.000Z”

}200 OK { "_ok_title": "Ok",

"_action": "ConfirmationDialog", "_id": "445-b66b3e10-6b95-4f13-bc2d-6e7a2d8900ea", "_text": "You will receive the call shortly", "_dialog_id": "0”

}

Reschedule Callback RequestPUThttp://demosrv:8010/genesys/1/service/callback/request-callback/45-b66b3e10-6b95-4f13-bc2d-6e7a2d8900ea{

"_new_desired_time":"2017-08-21T23:30:00.000Z”}

200 OK { }

Cancel Callback RequestDELETEhttp://demosrv:8010/genesys/1/service/callback/request-callback/45-b66b3e10-6b95-4f13-bc2d-6e7a2d8900ea

200 OK {

"_action": "ConfirmationDialog", "_id": "445-b66b3e10-6b95-4f13-bc2d-6e7a2d8900ea", "_text": "Your service request is now cancelled.", "_ok_title": "Ok", "_dialog_id": "0”

}

Estimated Wait Time Request (added in GMS 8.5.109)

GET http://demosrv:8010/genesys/1/ewt/vq-callback

200 OK {

"hit": 66, "ewt": 19.1428571428571, "calls": 0, "pos": 1, "aqt": 19.1428571428571, "wpos": 1, "time": 1490650821, "wt": 0, "wcalls": 0

}

Chat

Chat Overview

• Chat is a built-in service of GMS

• Enables mobile, web, and desktop applications to provide chat

capabilities.

• Chat Base URL

• http://<host>:<port>/genesys/2/chat/[chat-service-name]

• {chat-service-name} = The name of a chat service defined in the

options of your GMS application object.

• If chat service in the GMS Options is defined in the section named

“chat.request-chat” then {chat-service-name} is “request-chat”

• If omitted, then the default “chat” service section is used

Chat Service Configuration

Chat v2 API• Traditional REST-based API with a long-polling ”Refresh” request for

transcript updates

• GMS 8.5.109 introduced Chat over CometD using long-polling

• GMS 8.5.110 introduced Chat over CometD using WebSockets

• API Operations:

• Request Chat

• Send Message

• Start Typing

• Stop Typing

• Refresh Chat

• Typing Preview

• Disconnect

• Push URL

• Update Nickname

• Custom Notice

• Update User Data

• File Management

Chat Submission Trail

GMS Chat Service

Chat Server

Endpoint

Interaction Server Queue

Routing Application

Request Chat RequestPOST http://demosrv:8010/genesys/2/chat/request-chat firstName=Jim&lastName=Crespino&subject=Update Account200 OK { "statusCode":0,

"alias":"117", "userId":"007555677B20000A", "secureKey":"4ee15d7e1c343c8e", "messages":[ { "from":{"nickname":"First Last",

"participantId":1,"type":"Client"},

"index":1, "type":"ParticipantJoined", "utcTime":1432845088000 }

], "chatId":"00048aAPEQJ8000U"

}

Send Message RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/senduserId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229&transcriptPosition=8&message=hello

{ "messages":[ {"from":{"nickname":"FirstLast","participantId":1,"type":"Client"},

"index":7, "text":"hello","messageType":null,"type":"Message","utcTime":1432845541000},

{"from":{"nickname":"FirstLast","participantId":1,"type":"Client"},

"index":8,"text":"hello", "messageType":null,"type":"Message","utcTime":1432845548000}

],"chatEnded":false, "statusCode":0, "alias":"117", "secureKey":"3e2a69d421ae2672", "userId":"007555677CB4000D" }

Refresh Chat RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/refresh userId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229&transcriptPosition=1200 OK { "messages": [{"from":{"nickname":"AgentNick","participantId":3,"type":"Agent"},

"index":7,"text":"hello","type":"Message","utcTime":1451961875000}

], "chatEnded":false,"statusCode":0,"alias":"249", "secureKey":"45327f306556129f","userId":"00F9568B2DA601BA", "tenantName":"Resources","nextPosition":8 }

Push URL RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/pushUrluserId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229&pushURL=http://url.to.see

200 OK {

“messages”: null,“chatEnded”: false,“statusCode”: 0, “alias”: "117”, “secureKey”: "09fa6e8a8691c229",“userId”: "00755567761A0008"

}

Custom Notice RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/customNoticeuserId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229&message=BotCustomNotice:Disconnect

200 OK {

“messages”: null,“chatEnded”: false,“statusCode”: 0, “alias”: "117”, “secureKey”: "09fa6e8a8691c229",“userId”: "00755567761A0008"

}

Update User Data RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/updateDatauserId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229&userData[key1]=value1&userData[key2]=value2200 OK {

“messages”: null,“chatEnded”: false,“statusCode”: 0, “alias”: "117”, “secureKey”: "09fa6e8a8691c229",“userId”: "00755567761A0008"

}

Disconnect RequestPOST http://demosrv:8010/genesys/2/chat/request-chat /00048aAPEQJ8000S/disconnectuserId=00755567761A0008&alias=117&secureKey=09fa6e8a8691c229

200 OK {

“messages”: null,“chatEnded”: null,“statusCode”: 0,“alias”: null,“secureKey”: null,“userId”: null

}

Email (WebForm)

Email Overview

• Email is a built-in service of GMS

• Enables mobile, web, and desktop applications to provide email

submission capabilities.

• Email Base URL

• http://<host>:<port>/genesys/2/email/[email-service-name]

• {email-service-name} = The name of a email service defined in the

options of your GMS application object.

• If email service in the GMS Options is defined in the section named

“email.request-email” then {email-service-name} is “request-email”

• If omitted, then the default “email” service section is used

Email Service Configuration

Email Submission Trail

GMS Email Service

Email Server

Endpoint

Interaction Server Queue

Routing Application

Submit Email as multipart/form-data<form id="EmailSubmission"

method="post"

action=https://demosrv:8010/genesys/2/email

enctype="multipart/form-data">

<input type="text" id="firstName" name="firstName"></input>

<input type="text" id="lastName" name="lastName"></input>

<input type="text" id="subject" name="subject"></input>

<input type="text" id="fromAddress"

name="fromAddress"></input>

<textarea id="text" name="text" rows="3"></textarea>

<input type="submit" value="Submit">

</form>

Submit Email as application/x-www-form-urlencoded (new in GMS 8.5.110.07)

POST http://demosrv:8010/genesys/2/email/request-emailContent-Type: application/x-www-form-urlencodedfirstName=Jim&lastName=Crespino&fromAddress=jim.crespino@genesys.com&subject=Help+with+account&text=I+need+help+with+my+account&userData[key1]=value1&userData[key2]=value2&

200 OK { "statusCode": 0, "interactionId":"0000KaA0C8XH003X" }

OpenMedia

Open Media Overview

• Open Media is a built-in service of GMS

• Enables mobile, web, and desktop applications to submit non-voice

interactions.

• Open Media Base URL

• http://<host>:<port>/genesys/2/openmedia/{openmedia-

service-name}

• {openmedia-service-name} = The name of a open media service

defined in the options of your GMS application object.

• If open media service in the GMS Options is defined in the section named

“openmedia.request-openmedia” then {openmedia-service-name} is

“request-openmedia”

OpenMedia Service Configuration

OpenMedia API

• Offers a REST-based API to submit Open Media Interactions

• Replaces or works in conjunction with:

• OpenMedia Platform SDK

• eServices/iWD Capture Points

• API Operations:

• Create

• Get

• Update

• Stop

Open Media Submission Trail

GMS Open Media

Service

Interaction

Server

Queue

Routing

Application

Create OpenMedia Interaction (new in GMS 8.5.110.07)

POSThttp://demosrv:8010/genesys/2/openmedia/customer-serviceexternalId=xy932&userData[OrderNumber]=ABC123456789&userData[TestKey2]=Test value&userData[KeyToDelete]=value to delete

200 OK { "statusCode": 0, "interactionId":"01QG0Q2S5S50G000" }

Get OpenMedia Interaction (new in GMS 8.5.110.07)

POST http://demosrv:8010/genesys/2/openmedia/customer-service/ 01QG0Q2S5S50G000/get

200 OK { "statusCode": 0, "interactionProperties": { "interactionType": "Inbound", "interactionId": "01QG0Q2S5S50G000", "interactionReceivedAt": "2017-05-31T04:43:52Z", "interactionIsHeld": false, "interactionSubmittedBy": "GMS-DC-API:gms1:1", "interactionMediatype": "promotion", "interactionTenantId": 1, "interactionQueue": "ATS Inbound Queue", "interactionSubmitSeq": "1049036", "interactionMovedToQueueAt": "2017-05-31T04:43:52Z", "interactionState": "Queued", "interactionSubmittedAt": "2017-05-31T04:43:52Z", "interactionPlacedInQueueAt": "2017-05-31T04:51:39Z", "interactionUserData": [ { "key": "KeyToDelete", "type": "str", "value": "value to delete" }, { "key": "OrderNumber", "type": "str", "value": "ABC123456789" }, { "key": "TestKey2", "type": "str", "value": "Test value" }, ... ], "interactionSubtype": "InboundNew", "interactionIsLocked": false, "interactionIsOnline": false, "interactionPlaceInQueueSeq": "1050198" } }

Update OpenMedia Interaction (new in GMS 8.5.110.07)

POSThttp://demosrv:8010/genesys/2/openmedia/customer-service/ 01QG0Q2S5S50G000/update change[OrderNumber]=uABC123456789&change[TestKey2]=uTest+value&delete[KeyToDelete]=

200 OK { "statusCode": 0 }

Stop OpenMedia Interaction (new in GMS 8.5.110.07)

POSThttp://demosrv:8010/genesys/2/openmedia/customer-service/ 01QG0Q2S5S50G000/stop reason=Cancel&description=Not Needed

200 OK { "statusCode": 0 }

ORS Custom Services

ORS Custom Service Overview

• Custom Services are executed in ORS via GMS

• Enables mobile, web, desktop, and IVR applications to create

custom functionality that is exposed via GMS.

• Custom Service Base URL

• http://<host>:<port>/genesys/1/service/{service-name}

• {service-name} = The name of a custom service defined in the

options of your GMS application object.

• If the custom service in the GMS Options is defined in the section named

“service.custom-service” then {service-name} is “custom-service”

ORS Service Configuration

Custom SCXML Echo Request<transition event="echo">

<log expr="'===================Enter echo transition: ' +_event.sendid" />

<log expr="JSON.stringify(_data)" /><log expr="JSON.stringify(_event)" /><script>

var echoMessage = '';if ( _event.data.param._message != undefined ) {

echoMessage = _event.data.param._message;}

</script><!-- Respond with the string we received --><ws:response requestid="_event.sendid">

<param name="id" expr="_sessionid" /><param name="message" expr="echoMessage" />

</ws:response><log expr="'===================End echo transition'" />

</transition>

Create Custom Service SessionPOST http://demosrv:8010/genesys/1/service/crespino{}

200 OK {

"id": "V47TK49H3H6FV7BC4MR4NKSMO000000N", "version": "1.0”

}

Custom Service Session RequestPOSThttp://demosrv:8010/genesys/1/service/V47TK49H3H6FV7BC4MR4NKSMO000000N/echo{"_message": "Echo this!”

}

200 OK {"id":"V47TK49H3H6FV7BC4MR4NKSMO000000N","message":"Echo this!”

}

Delete Custom Service SessionDELETEhttp://demosrv:8010/genesys/1/service/V47TK49H3H6FV7BC4MR4NKSMO000000N{}

200 OK ok

Non-Service APIs

Supporting GMS APIs• Notification API• Storage API• Stat Service API

• Capacity API• Calendar Service API• Pattern Matcher API• Phone Number Validation API

Notification API

Subscription RequestPOSThttps://demosrv:8010/genesys/1/notification/subscription{"subscriberId":"A1", "notificationDetails":{"deviceId":"https://requestb.in/whb391wh", "type":"httpcb"},

"filter":"*"}

200 OK {"id":"445-93ad5db8-2fba-440f-b604-a981c696f691"}

Publish RequestPOSThttps://demosrv:8010/genesys/1/notification/publish { "message": "{'prop1':'value1','prop2':'value2'}", "tag": "gms.notification.agentstatus", "mediaType": "STRING", "notificationDetails": { "deviceId": "https://requestb.in/whb391wh", "type": "httpcb", "properties": { }

}}

204 No Content

Publish Request

Storage API

Create RequestPOST https://demosrv:8010/genesys/1/storage/3600Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW------WebKitFormBoundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="Key1”Value1------WebKitFormBoundary7MA4YWxkTrZu0gWContent-Disposition: form-data; name="Key2”Value2------WebKitFormBoundary7MA4YWxkTrZu0gW--

200 OK{ "id": "445-574b1028-9e13-4d7d-93e0-c6fd42785380” }

Get All Keys RequestGET https://demosrv:8010/genesys/1/storage/445-574b1028-9e13-4d7d-93e0-c6fd42785380

200 OK{ "Key2": "Value2", "Key1": "Value1”

}

Get One Key Request

GET https://demosrv:8010/genesys/1/storage/445-574b1028-9e13-4d7d-93e0-c6fd42785380/Key1

200 OKValue1

Get One Key Request

DELETE https://demosrv:8010/genesys/1/storage/445-574b1028-9e13-4d7d-93e0-c6fd42785380

200 OKok

Stat Service API

GMS Configuration for Statistics• In order to use the Stat Server API, there must be a connection to

Stat Server in the GMS Application.

• You can add several Stat Servers in the Connection tab; this feature

is used in case of different statistic definitions in the Stat Servers.

GMS will open the statistic on the Stat Server to which the statistic

belongs to. In the case of the same statistic definition in Stat

Servers, GMS will take the first Stat Server that contains the statistic

definition.

• If Stat Servers (defined in GMS connections) are configured to use

High Availability (HA) (Primary/Backup Stat Server), in the case of a

lost connection with the primary Stat Server, the Stat Server API will

switch to the backup Stat Server.

Peek Stat Sequence: Statistic Not Already Opened

Peek Stat Sequence: Statistic Already Exists

Update Statistics Cache

Accessing the APIs• The Stat Service API exposes two interfaces:

• /genesys/1/internal_statistic - for internal access with no authentication

control

• /genesys/1/statistic – for external use using HTTP Basic Authentication to

authenticate users

• must specify the credentials of a configured Person object with appropriate

permissions

• As a standard protocol, the username and password for basic

authentication can be passed in the URL

• http://username:password@127.0.0.1:8080/genesys/1/statistic

PeekStat Request (x-www-form-urlencoded)POST http://demosrv:8010/genesys/1/statistic HTTP/1.1Authorization: Basic ZGVmYXVsdDpwYXNzd29yZA==Content-Type: application/x-www-form-urlencodedCache-Control: no-cache

objectId=Any_Agent&objectType=GroupAgents&tenant=Environment&tenantPassword=&metric=CurrentAgentGroupTargetState&notificationMode=Immediate

PeekStat Response{

"value": [{

"agentDbId": 644,"placeDbId": 0,"agentId": "0071","placeId": null,"extensions": [

{"VOICE_MEDIA_STATUS": 0},{"AGENT_VOICE_MEDIA_STATUS": 0},{"DEVCAP": "AAA="}

],"mediaCapacityList": null,"dnstatusExList": null

},…

}

PeekStats Request: JSON with Multiple Statistics

POST http://demosrv:8010/genesys/1/statisticsAuthorization: Basic ZGVmYXVsdDpwYXNzd29yZA==Content-Type: application/jsonCache-Control: no-cache{"stat1": { "objectId":”KSippola",

"objectType":”Agent","tenant":"Environment","tenantPassword":"","metric":"TotalLoginTime","filter": "Bronze" },

"stat2": { "objectId":"9002@SIP_Switch","objectType":"Queue","tenant":"Environment","metric":"ExpectedWaitTime” }

}200 OK{"stat1":0,"stat2":10000}

URS Statistics via GMS• This API allows you to query URS statistics with GMS.• To use this request, you must add the following configuration

information:• URS version must be 8.1.400.12 or higher.• In your URS application, allow HTTP requests:

• Open your URS application in Genesys Administrator or Configuration Manager.• In the Server Info tab, create an HTTP listening port.

• In the ‘reporting’ section of your GMS application, create the _urs_url option and set it to the URL of URS.

• You can also create a builtin service to retrieve URS statistics with the urs-stat template. When you create your service, select the "urs-stat" type in the Admin UI service panel. See the Admin UI Help for further details. • To retrieve the statistics, you can make the following request:

• GET http://<gms_home>:<gms_port>/genesys/1/service/<urs_service>

URS Statistic RequestGET /genesys/1/statistics/urs/{parameters}

Example Request:

http://username:password@localhost:8080/genesys/1/statistic/urs/stat/targetstate?tenant=Environment&target=KSippola.A&json=&ext=

Parameters can be discovered directly from URS by navigating to:

http://URS_host:URS_port/urs/help/

URS Statistic Response{"dnsall":6, "voice":1, "status":4, "loading":0, "dns": [ { "type":38,

"number":"KSippola", "switch":"", "status":4, "loading":0, "ready":1, "media":1, "loggedin":0 },

…]

"login":"SIP1", "place":"SIP_Server_Place1", "ready":1, "agent":"KSippola", "dnsrdy":3

}

PeekStat Request – Configurated Statistic• [stat.stat1]

• _type=builtin• _service=statistic • metric=TotalLoginTime• notificationMode=Immediate • objectId=KSippola• objectType=Agent • tenant=Environment • filter=Bronze

• Then, you can retrieve the statistics for stat1 with a simple statistics query:

POST http://localhost:8080/genesys/1/statistic/stat1

Response: {"value":41889}

Available in

8.5.101

EWT Statistics: Single VQ Queries• You can query Estimated Wait Time statistics if you have configured a

Virtual Queue for your Callback service by using the _urs_virtual_queue option. • Three calculation types are available and use a URS query to retrieve the

Estimated Wait Time in seconds.• ewt: GET /genesys/1/ewt/{VQ-Name}

• http://<urshost>:<ursport>/urs/call/max/lvq?name={VQ_Name}&aqt=urs&tenant=TenantName

• ewt2 (added in 8.5.112): GET /genesys/1/ewt2/{VQ-Name}• http://<urshost>:<ursport>/urs/call/max/lvq?name={VQ_Name}&aqt=urs2&tenant=TenantName

• ewt3 (added in 8.5.112): GET /genesys/1/ewt3/{VQ-Name}• http://<urshost>:<ursport>/urs/call/max/lvq?name={VQ_Name}&aqt=stat&tenant=TenantName

EWT Statistics: Single VQ Responses

EWT Statistics: All VQs Queries• You can query Estimated Wait Time statistics if you have configured at

least a Virtual Queue for one of your Callback service by using the _urs_virtual_queue option. Three calculation types are available and use a URS query to retrieve the Estimated Waiting Time in seconds.• ewt: GET /genesys/2/ewt

• http://<urshost>:<ursport>/urs/call/max/lvq?aqt=urs&tenant=TenantName

• ewt2 (added in 8.5.112): GET /genesys/2/ewt2• http://<urshost>:<ursport>/urs/call/max/lvq?aqt=urs2&tenant=TenantName

• ewt3 (added in 8.5.112): GET /genesys/2/ewt3• http://<urshost>:<ursport>/urs/call/max/lvq?aqt=stat&tenant=TenantName

EWT Statistics: All VQs Responses

Statistics over CometD: Subscription

This must be unique for each CometD subscriber. It identifies

your channel!

Statistics over CometD: Statistics Request

Must match the identifier you sent when you subscribed!

CometD Statistics Limitations• CometD requests TTL is 120 seconds (by default).• The statistics filter subscription is set to 10000 seconds, then the

subscription is removed and you must send back the same stat request before the end of TTL subscription.• You cannot define a statistic in Configuration Server for the GMS

application that will be automatically subscribed at GMS startup. You must subscribe to the statistics as detailed above.

Summary

Things to Remember• GMS is not just about Mobile!

• GMS should be thought of as our Consumer-facing API.

• GMS is a conglomeration of APIs built by different groups, and each

API operates a little differently from the other in regards to

parameters and payloads.

• The built-in services (Callback, Chat, etc.) are powerful and flexible.

• You can build your own custom ORS-based services.

• Some nice hidden gems are buried in the API:

• Notification API

• CometD real-time stat feed

What Now!• This Week• Visit us in the DevLounge area of

the Partner Pavilion

• After the Event• https://developer.genesys.com to

access our developer portals, Q&A forums, and resources

Thank YouVisit developer.genesys.com for more information