CometD notifications

Many requests in the Web Services API are asynchronous. When you send an asynchronous request, typically an operation, Web Services still returns an HTTP response with a status code like other requests, but this only means the request was processed and sent to a backend Genesys server, like T-Server. When the server finishes processing the request and notifies Web Services of any changes in state or errors, Web Services then sends the updated state or error details to the client application as CometD notifications.

Web Services uses CometD to deliver these unsolicited notifications to clients. CometD is a library that allows the server to deliver messages to a web-based client with low-latency using a variety of transports. The transport used to deliver messages is negotiated between the client and server based on what the client supports running in a particular browser. Example transports include long polling and web sockets. CometD also provides a basic infrastructure for publishing and subscribing to messages. For more information about CometD, or for details about where to obtain client-side CometD libraries for various platforms, see the official CometD site.

Important

A basic understanding of CometD is a prerequisite to developing a client application using the Web Services API.

Topics

Once your client application establishes a CometD session, you must create a subscription to one or more of the CometD topics used by the Web Services API. Your subscriptions should be based on the functionality available in your client application.

Topic	Description	MessageTypes
/v2/me/devices	Messages related to devices. Examples include changes to agent state, do-not-disturb, call forwarding, and supervisor monitoring.	DeviceStateChangeMessage ErrorMessage
/v2/me/calls	Messages related to calls. Examples include changes to call state, updates to call participant information, and updates to call data.	CallStateChangeMessage ErrorMessage
/notifications/services	Messages relating to the state of different services. If the connection to T-Server is lost, or T-Server's connection to the CTI link is broken, a message is delivered to the client.	ServiceStateChangeMessage
/v2/me/chats	Messages related to chats. Examples include changes to chat state, updates to chat participant information, updates to chat data, and updates to chat transcript.	ChatStateChangeMessage MessageLogUpdated
/v2/me/emails	Messages related to emails. Examples include changes to email state and updates to email data.	EmailStateChangeMessage
/v2/me/facebook	Messages related to Facebook interactions. Examples include changes to Facebook interaction state and updates to Facebook interaction data.	FacebookStateChangeMessage
/v2/me/facebooksession	Messages related to private Facebook messages. Examples include changes to private Facebook message state, updates to private Facebook message data, and updates to private Facebook message transcript.	FacebooksessionStateChangeMessage MessageLogUpdated
/v2/me/im-sessions	Messages related to instant messaging between agents. Examples include changes to IM session state and updates to IM session data.	IMSessionStateChangeMessage IMLogUpdateMessage
/v2/me/openmedia	Messages related to OpenMedia interactions. Examples include changes to OpenMedia interaction state and updates to OpenMedia interaction data.	OpenmediaStateChangeMessage
/v2/me/twitter	Messages related to Twitter interactions. Examples include changes Twitter interaction state, updates to Twitter interaction data, and updates to Twitter account following.	TweetStateChangeMessage TweetOperationResponse
/v2/me/workbins	Messages related to workbins. Examples include changes to workbin state and updates to workbin contents.	WorkbinSubscriptionStateChangeMessage WorkbinStateChangeMessage
/v2/me/workitems	Messages related to workitems. Examples include changes to workitem state and updates to workitem data.	WorkitemStateChangeMessage

Messages

[+] ServiceStateChangeMessage

ServiceStateChangeMessage

Property	Description
data	The data element is present in all CometD notifications and is the root JSON element. The data.messageType property can always be used to identify the message and determine what other properties should be present.
data.messageType	This property identifies the message type and will have a value of ServiceStateChangeMessage.
data.service	A JSON object that describes the service the notification relates to and its current state.
data.service.type	The type of service: Voice, Provisioning, Reporting, MultiMediaState, MultiMediaContent, Chat, or Unknown. The Voice API requires only the Voice and Provisioning services.
data.service.state	The state of the service: ReadOnly, Inactive, Active, or Unknown
channel	The topic to which the message was published.

The following example message is received when the connection to T-Server is unavailable

{
  "data": {
    "messageType": "ServiceStateChangeMessage",
    "service": {
      "id": "370ef5e6-9e3c-4d91-9588-7f4dfe67e011",
      "name": "SIPS",
      "type": "Voice",
      "state": "Inactive"
    }
  },
  "channel": "/notifications/services"
}

This second example message is received when the connection to T-Server is restored.

{
  "data": {
    "messageType": "ServiceStateChangeMessage",
    "service": {
      "id": "370ef5e6-9e3c-4d91-9588-7f4dfe67e011",
      "name": "SIPS",
      "type": "Voice",
      "state": "Active"
    }
  },
  "channel": "/notifications/services"
}