Telephony Session Notifications

A developer can use Telephony Session Notifications to detect all changes in the status of a call effectively.

What are Telephony Session Notifications?

Telephony Session Notifications are a series of notifications or events a developer can use to track an end-to-end telephony call in RingCentral. The call can be from an external PSTN or any mobile number to a RingCentral extension, or it can be from a RingCentral Digital Line to an external PSTN number, or it can be between two RingCentral extensions. The Telephony Session Notification provides detailed end-to-end call sessions and party (endpoints/user) level information to enable developers to take specific actions or build custom reports based on that call information. The Telephony Session Notification events can be subscribed both at an Account level or at an Extension level.

• Account Level Telephony Session Notification - Will track and provide notifications for all the extensions within an account.
• Extension Level Telephony Session Notification - Will track calls on a specific extension.

Detailed instructions on the Notification types are available in the API reference.

Detailed instructions on how to subscribe to RingCentral events or notifications are available in the API reference.

Popular use cases for Telephony Sessions

Call Analytics

Developers can use the raw data from Telephony Session Notification events and build call analytics dashboards replicating live reports which use the same event streams. Some of the standard call analytics metrics and their corresponding formulas are:

• Ring Time
• Talk Time
• Hold Time

See the Calculating Call Time Metrics guide on how to calculate these metrics using notifications.

Call Monitoring via Real-Time Streaming

Telephony Session Notifications can be used to monitor calls at an Extension or an Account level to fulfill use cases like contact center agent assist using Dual-Channel or Single-Channel Call Monitoring

Incoming Call Routing

Telephony Session Notifications can be used to monitor and detect an incoming call and apply custom call routing logic to suit business-specific needs. For example, forwarding calls from an important customer to a call queue supervisor.

Call Status Codes

A call transitions through various states from the start of the call to the end. A Telephony Session Notification captures each of these states. States of a call are associated with the parties involved in the call, and it can be the "Outbound" party (party making the call) or the "Inbound" party (party receiving the call). The schema object "status.code" in the Telephony Session Notification captures the state of the call in regards to the party (Outbound or Inbound) involved in the call. The table below illustrates the different states that a party goes though in a call session.

What are the key Schema Objects of a Telephony Session Notification?

The two key elements for a Telephony Session Notification are:

Sample Telephony Session Notification Event

{
  "uuid": "1823485288313944239",
  "event": "/restapi/v1.0/account/809646016/extension/809646016/telephony/sessions",
  "timestamp": "2020-06-14T19:27:18.390Z",
  "subscriptionId": "53300e7c-5e69-42bf-ab4d-179aabc6e869",
  "ownerId": "809646016",
  "body": {
    "sequence": 3,
    "sessionId": "425008160016",
    "telephonySessionId": "s-a6abd24ca6774373a8120a3390d3cbe8",
    "serverId": "10.13.22.28.TAM",
    "eventTime": "2020-06-14T19:27:18.340Z",
    "parties": [
      {
        "accountId": "809646016",
        "extensionId": "809646016",
        "id": "p-a6abd24ca6774373a8120a3390d3cbe8-2",
        "direction": "Inbound",
        "to": {
          "phoneNumber": "+19043014558",
          "name": "TESTER Babji",
          "extensionId": "809646016"
        },
        "from": {
          "phoneNumber": "+14083388064"
        },
        "status": {
          "code": "Setup",
          "rcc": false
        },
        "park": {},
        "missedCall": false,
        "standAlone": false,
        "muted": false
      }
    ],
    "origin": {
      "type": "Call"
    }
  }
}

Example Telephony Session Notification for a Typical Call Flow (Inbound & Outbound with all States & Sequence)

• PSTN to RingCentral
• RingCentral to RingCentral
• RingCentral to PSTN

Error Codes

For Error Codes refer to RingCentral Error Codes in API Reference

What is the difference between Telephony Session Notifications and Telephony Presence Notifications

Summary

Telephony Session Notifications are detailed telephony event notifications that capture raw data of all the activity going on in a call session, including the details of the parties involved in the call. Developers can use this information to build a customized call analytics dashboard, custom call routing applications, call monitoring applications, and other applications that need detailed call session data. The Telephony Session Notifications also provides the detail call elements like telephonySessionId and id(party id) required to control an active call.

FAQ

• Does the Telephony Session Notification emit the events in the same sequence as seen by the sequence number?

  It might be the case that sometimes later sequence numbers are emitted first for example an event with a sequence number of 5 can be received before sequence 2 or 3, this can happen due to delay or differences in timing by the Webhook or PubNub event delivery services.

• Can the Telephony Session Notification be used to subscribe for specific extensions?

  Yes Telephony Session Notification can be used to subscribe at an Extension or at an Account Level.

• What App permission is needed to access Telephony Session Notification?

  CallControl permission is needed.