Agent and Engagement Events 0.1.1 documentation

Contact Center Agent and Engagement events are available for the streaming needs of client applications via websockets. The Notification API facilitates subscribing to different families of events and transport protocols (Websockets and Webhooks). Agent & Engagement are one of these available families.
This following focuses on the websocket implementation of Agent and Engagement events.

Create Subscription

The example provided below will create a subscription for a WebSocket stream of Agent & Engagement events. Upon a successful response a transport endpoint URL will be provided for the WebSocket interface to connect and begin consuming events from.

  POST https://{{CCaaS_FQDN}}/api/notification/v1beta/accounts/{accountId}/subscriptions
  Content-Type: application/json
  Accept: application/json
  Header: Authorization: Bearer {{token}}

Request Body:

    {
      "family": "AGENT_ENGAGEMENT",
      "events": ["ALL"],
      "transport": {
        "type": "WEBSOCKET"
      }
    }

Response:

    {
      "subscriptionId": "fdbec917-e76e-4645-8120-4eac46f29487",
      "createdAt": "2020-08-01T14:25:23.162Z",
      "expiresAt": "2020-08-01T15:25:23.177Z",
      "expiresIn": 900,
      "status": "ACTIVE",
      "family": "AGENT_ENGAGEMENT",
      "events": [
        "ALL"
      ],
      "transport": {
        "type": "WEBSOCKET",
        "endpoint": "wss://uk.cc.avayacloud.com/ws/notification/v1beta/agent-engagement",
        "pingInterval": 300
      }
    }

As you have seen above agent and engagement events are subscribed to via the Notification API. In choosing WEBSOCKET as the transport option these events are then consumed through a WebSocket connection. The events are contained within JSON that makes up the payload of the WebSocket messages.
The following section shows how to use the Websocket interface.

Table of Contents

• Servers
• Channels

Servers

production Server

URL Variables

Security Requirements

Channels

/v1beta/agent-engagement Channel

publish Operation

Upon creating a subscription and connecting to the WebSocket endpoint you will need to send a message to the server confirming you are authenticated before any notification events will be sent. This token must be obtained from the A&A service.

NOTE: For further details and code examples please refer to: How to Authenticate with Avaya Experience Platform™ APIs

Accepts one of the following messages:

Message authentication

The first message the client should send to server after establishing the connection must be an authentication message.

Payload

Examples of payload (generated)

{
  "event": "authentication",
  "subscriptionId": "fdbec917-e76e-4645-8120-4eac46f29487",
  "token": "7e0cd42a22b451701fg29c3bde214…"
}

Tags

• Authentication

Message ping

Client must send ping to the server in order to determine whether connection is alive, server responds with pong.
The ping is also used to keep the websocket connection alive, by keep sending ping messages every pingInterval time to the server.

It is recommended the client send ping more frequently (every 30 seconds) to preclude any proxies from closing the connection.

Payload

Examples of payload

pingMessage

Example of an ping message to server.

{
  "event": "ping"
}

Tags

• Heartbeat

subscribe Operation

Notification messages that you receive from the server

Accepts one of the following messages:

Message notification

Notification event consumed over the WebSocket connection

Payload

• If transferTo is QUEUE, then returns the queueId
• If transferTo is USER, then returns the destinationAgentId
• If transferTo is AUTOMATION, then returns the ivrAddress
• If transferTo is EXTERNAL, then returns the externalAddress | Any |
  | body.9.dialogId | string | The identifier for the dialog. NOTE this will equate to the UCID created by the ASBCE for an inbound call | Any |
  | body.9.channelProviderId | string | The unique identifier for this engagement provider | Any |
  | body.9.channelId | string | The channel ID which represents the media type | Any |
  | body.9.correlationId | string | The correlationId for the request. This should be referenced when notifying a related error | Any |
  | body.9.title | string | The error description | Any |
  | body.9.detail | string | The cause of the error | Any |
  | body.9.id | string | Each event has its own unique ID | Any |
  | body.9.timestamp | string | Timestamp (milliseconds since epoch) when the event was generated | Any |
  | body.event | string | The name of the specific event being sent. For instance AgentState, AgentParticipant, InboundEngagementCreated, etc... | Any |

Examples of payload (generated)

{
  "correlationId": "a425851d-5225-4b76-8ca0-4fa31ecfd5db",
  "subscriptionId": "fdbec917-e76e-4645-8120-4eac46f29487",
  "family": "AGENT_ENGAGEMENT",
  "sentAt": "2020-08-24T08:20:23.395Z",
  "accountId": "DYNNUG",
  "loginId": "[email protected]",
  "body": {
    "event": "AgentState",
    "agentId": "4a785201-73b8-4842-abf7-36f5e572d310",
    "profileId": "HomeProfile",
    "state": "NOT_READY",
    "reasonCode": 514,
    "cause": "RONA",
    "id": "d3c8400d-c44f-4451-8316-e75c4efb8bb2",
    "timestamp": 9223372036854776000
  }
}

Tags

• Agent and Engagement Data

Message pong

Server pong response to a ping message.

Payload

Examples of payload

pongMessage

Example of a pong message to client.

{
  "event": "pong"
}

Tags

• Heartbeat

Message authenticationResponse

Authentication response message sent to the client after websocket authentication.

Payload

• CONNECTION_CONFIRMED: Connection was confirmed
• CONNECTION_FAILED_INVALID_TOKEN: Authentication token is invalid
• CONNECTION_FAILED_UNKNOWN_SUBSCRIPTION: Unknown Subscription, can be for a subscription that never existed or one that is no longer active
• CONNECTION_FAILED_INTERNAL_SERVER_ERROR: Server Error, client can retry later
• CONNECTIONFAILED_CONSTRAINT_VIOLATION: Client issue, malformed client request, client must update payload and rerty | CONNECTION_CONFIRMED, CONNECTION_FAILED_INVALID_TOKEN, CONNECTION_FAILED_UNKNOWN_SUBSCRIPTION, CONNECTION_FAILED_INTERNAL_SERVER_ERROR, CONNECTION_FAILED_CONSTRAINT_VIOLATION |
  | subscriptionId | string | The unique id of the subscription. | _Any |
  | pingInterval | integer | The maximum interval (seconds) at which a ping is expected to be sent by the client before websocket is closed and subscription set to INACTIVE.

It is recommended the client send ping more frequently (every 30 seconds) to preclude any proxies from closing the connection. | Any |
| expiresInterval | integer | Expiration interval in seconds before the subscription is set to INACTIVE. | Any |

Examples of payload (generated)

{
  "event": "authenticationResponse",
  "status": "CONNECTION_CONFIRMED",
  "subscriptionId": "fdbec917-e76e-4645-8120-4eac46f29487",
  "pingInterval": 300,
  "expiresInterval": 900
}

Tags

• Authentication