What are capabilities?

Capabilities is a complimentary concept the Web Services API uses to help client application developers decide when it's appropriate to allow an operation to be performed.

When you perform an operation, Web Services returns a CometD notification that includes the related resource, with a property called "capabilities". This property provides a list of operation names that are valid for the current state of the resource.

One of the great things about capabilities is that they can help you understand when to enable or disable functionality in your UI. For instance, consider the capabilities available for the device resource below:

{
  "data": {
    "messageType": "DeviceStateChangeMessage",
    "devices": [
      {
        "id": "9c14cad7-17c4-48d0-8492-7cf0ff92c224",
        "deviceState": "Active",
        "userState": {
          "id": "900D55CC-2BB0-431F-8BF9-D3525B383BE6",
          "displayName": "Not Ready",
          "state": "NotReady"
        },
        "phoneNumber": "5001",
        "e164Number": "5001",
        "telephonyNetwork": "Private",
        "doNotDisturb": "Off",
        "voiceEnvironmentUri": "http://127.0.0.1:8080/api/v2/voice-environments/370ef5e6-9e3c-4d91-9588-7f4dfe67e011",
        "capabilities": [
          "ForwardCallsOn",
          "DoNotDisturbOn"
        ]
      }
    ]
  },
  "channel": "/v2/me/devices"
}

The device resource has two capabilities in its current state:

• ForwardCallsOn
• DoNotDisturbOn

Based on this, your application could enable the UI elements for forwarding calls and turning on Do Not Disturb while at the same time disabling others, such as the ability to turn off Do Not Disturb (since it's already off, as indicated by the list of capabilities and "doNotDisturb": "Off" in the example above).

If the user triggers the UI to turn on Do Not Disturb, you would send a DoNotDisturbOn request, and receive the following DeviceStateChangeMessage:

{
  "data": {
    "messageType": "DeviceStateChangeMessage",
    "devices": [
      {
        "id": "9c14cad7-17c4-48d0-8492-7cf0ff92c224",
        "deviceState": "Active",
        "userState": {
          "id": "900D55CC-2BB0-431F-8BF9-D3525B383BE6",
          "displayName": "Not Ready",
          "state": "NotReady"
        },
        "phoneNumber": "5001",
        "e164Number": "5001",
        "telephonyNetwork": "Private",
        "doNotDisturb": "On",
        "voiceEnvironmentUri": "http://127.0.0.1:8080/api/v2/voice-environments/370ef5e6-9e3c-4d91-9588-7f4dfe67e011",
        "capabilities": [
          "ForwardCallsOn",
          "DoNotDisturbOff"
        ]
      }
    ]
  },
  "channel": "/v2/me/devices"
}

In the example above, you can see that DoNotDisturbOn is no longer available in the capabilities — it's been replaced by DoNotDisturbOff. Also note that the doNotDisturb property is now set to "On".

Like devices, the call resource provides a capabilities property, as shown in the CallStateChangeMessage:

{
  "data": {
    "messageType": "CallStateChangeMessage",
    "notificationType": "StatusChange",
    "extensions": {
        "WrapUpTime": 0,
        "BusinessCall": 0
    },
    "call": {
      "id": "011DJV5JI898NB2L04000VTAES00000B",
      "connId": "007102385535e00a",
      "state": "Ringing",
      "callUuid": "011DJV5JI898NB2L04000VTAES00000B",
      "deviceUri": "http://127.0.0.1:8080/api/v2/devices/74152ed8-858f-4a33-9e96-36213a678d30",
      "uri": "http://127.0.0.1:8080/api/v2/me/calls/011DJV5JI898NB2L04000VTAES00000B",
      "participants": [
         {
            "e164Number": "5001",
            "formattedPhoneNumber": "5001",
            "phoneNumber": "5001",
            "digits": "5001"
         }
      ],
      "dnis": "5000",
      "callType": "Internal",
      "capabilities": [
        "AttachUserData",
        "Answer",
        "UpdateUserData",
        "DeleteUserData",
        "DeleteUserDataPair"
      ],
      "duration": "0",
      "mute": "Off",
      "supervisorListeningIn": false,
      "monitoredUserMuted": false
    },
    "phoneNumber": "5000"
  },
  "channel": "/v2/me/calls"
}

Since this call is ringing (see the "state" property in the example above), a limited set of capabilities are provided, including the Answer operation. If the user answers the call, Web Services sends another CometD notification with an updated state and list of capabilities:

{
  "data": {
    "messageType": "CallStateChangeMessage",
    "notificationType": "StatusChange",
    "extensions": {
        "WrapUpTime": 0,
        "BusinessCall": 0
    },
    "call": {
      "id": "011DJV5JI898NB2L04000VTAES00000B",
      "connId": "007102385535e00a",
      "state": "Established",
      "callUuid": "011DJV5JI898NB2L04000VTAES00000B",
      "deviceUri": "http://127.0.0.1:8080/api/v2/devices/74152ed8-858f-4a33-9e96-36213a678d30",
      "uri": "http://127.0.0.1:8080/api/v2/me/calls/011DJV5JI898NB2L04000VTAES00000B",
      "participants": [
         {
            "e164Number": "5001",
            "formattedPhoneNumber": "5001",
            "phoneNumber": "5001",
            "digits": "5001"
         }
      ],
      "dnis": "5000",
      "callType": "Internal",
      "capabilities": [
        "AttachUserData",
        "InitiateConference",
        "UpdateUserData",
        "Hold",
        "SingleStepTransfer",
        "DeleteUserData",
        "SingleStepConference",
        "Hangup",
        "DeleteUserDataPair",
        "SendDtmf",
        "InitiateTransfer"
      ],
      "duration": "5",
      "mute": "Off",
      "supervisorListeningIn": false,
      "monitoredUserMuted": false
    },
    "phoneNumber": "5000"
  },
  "channel": "/v2/me/calls"
}

As you can see, the set of available capabilities is expanded to allow typical call operations, like Hold or Hangup, once the call is established ("state": "Established").

For details about capabilities for other resources, just look at the "Samples" section for any operation page in this guide — it includes a "CometD Notification" section with a real-world examples of notifications.