callstats.io

The callstats Developer Hub

Welcome to the callstats developer hub. You'll find comprehensive guides and documentation to help you start working with callstats as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    API Reference

Webhook Notifications

How do I get the data out of callstats? You do that by configuring notifications. Interval Threshold notifications or End of call summary notifications

callstats.io sends notifications (JSON encoded messages) to webhook URLs. The notification messages are sent when either a single event occurs (individual notification) or a metric exceeds a threshold value in a defined interval (threshold notification), in the message these are identified by the triggerType.

Interval Threshold notifications

These occur when an issues exceed a threshold value in a measurement period. For example, if you want to be notified every hour/day when the number of failed calls exceed the 5% threshold.

Keys

Description

reason

camelCase string identifying the notification, see next table for possible values.

timestamp

Unix timestamp in seconds when the message was sent.

appId

The application identifier corresponding to the message.

triggerType

Either it set to interval or individual.

actualValue

The actual measured value of the metric when the message was triggered.

threshold

The threshold over which the notification is triggered. For individual metrics, this value is 1.

fractionalValue

The ratio of the actualValue of a certain metric and the total measurement points of that metric. e.g., failed/total conferences.

period

Object containing start and end timestamps.

url

The search URL that will find the conference on callstats.io dashboard.
text Notification in english text.

Keys for Notification Reason

failedConferences

ratio of failed conferences exceeded threshold

droppedConferences

ratio of dropped conferences exceeded threshold

partiallyFailedConferences

ratio of partially failed conferences (where some participants were unable to join) exceeded threshold

highChurn

ratio of conferences where user joined, left, rejoined (churn) exceeded threshold

highSetupDelays

ratio of conferences which had a high setup time exceeded threshold

highRoundTripTime

ratio of average round trip time in milliseconds exceeds preset threshold. If for example 200 milliseconds is set as the threshold for high roundtrip time, the notification is sent if average round trip time for all conferences exceeds 200 milliseconds within one hour.

dissatisfactoryUserFeedback

ratio of userfeedback rated 1 or 2 out of 5 that exceed threshold

Example JSON webhook notifications that you will receive is as follows:

{
   "reason":"dissatisfactoryUserFeedback",
   "timestamp":1471354044616,
   "appId":"xxxxx",
   "triggerType":"interval",
   "actualValue":5,
   "threshold":0.2,
   "fractionalValue":0.3333333333333333,
   "period":{
      "start":1458125913802,
      "end":1458129519080
   },
   "url":"https:\/\/dashboard.callstats.io\/search?feedback12=1",
   "text":"33% of the conferences had dissatisfactory feedback in the last hour i.e., 5 of 15 total conferences with appID xxxxx. The current trigger threshold is 20%."
}
{
   "reason":"failedConferences",
   "timestamp":1471354046133,
   "appId":"xxxxx",
   "triggerType":"interval",
   "actualValue":7,
   "threshold":0.1,
   "fractionalValue":0.11290322580645161,
   "period":{
      "start":1458125913802,
      "end":1458129519080
   },
   "url":"https:\/\/dashboard.callstats.io\/search?failureGroup=totalFailure",
   "text":"11% of the conferences failed in the last hour i.e., 7 of 62 total conferences with appID xxxxx. The current trigger threshold is 10%."
}

Individual notification: End of call summary notification

For example an end of call summary notification contains all the information related to the call.

  • fabric summaries contains all the connections (local and remote userIDs).
  • streamSummary: contains the network and media metrics related to the inbound or outbound media stream (identified by ssrc).
  • fabricSetupErrors contains the failure reason for each failed connectionID.
  • fabricTerminationStatuses contains the termination status, for example the reason can be dropped, timeout, or terminated.
{
   "confID":"foo",
   "setupStatus":"success",
   "eMOS":2.9000000000000004,
   "fabricSummaries":[
      {
         "loginID":"superman",
         "connectionID":"37jij3m5wj",
         "siteID":"site-1",
         "localID":"pT3JHEXx7gbBtH3oAAAK",
         "remoteID":"NpKRhenBtlRQaXFPAAAL",
         "streamSummary":[
            {
               "meanFractionLost":0,
               "codec":"opus",
               "streamType":"inbound",
               "packetsReceived":750,
               "ssrc":"3408891923",
               "meanThroughput":37.43179028614632,
               "meanJitter":0,
               "mediaType":"audio"
            },
            {
               "codec":"VP8",
               "streamType":"outbound",
               "ssrc":"596429603",
               "meanThroughput":1677.2597806353933,
               "packetsSent":2884,
               "mediaType":"video",
               "meanFrameHeight":480,
               "meanFrameRate":29,
               "meanRoundTripTime":9.333333333333336E-4,
               "meanFrameWidth":640
            },
            {
               "meanFractionLost":0,
               "codec":"VP8",
               "streamType":"inbound",
               "packetsReceived":1691,
               "ssrc":"1348375532",
               "meanThroughput":926.6697215351869,
               "meanJitter":0.49046666666666666,
               "mediaType":"video",
               "meanFrameHeight":280,
               "meanFrameRate":29.866666666666667,
               "meanFrameWidth":373.3333333333333
            },
            {
               "codec":"opus",
               "streamType":"outbound",
               "ssrc":"1923068671",
               "meanThroughput":39.42784483825522,
               "packetsSent":750,
               "mediaType":"audio",
               "meanRoundTripTime":0.0010000000000000005
            }
         ]
      }
   ],
   "hostGeoData":[
      {
         "country":"FI",
         "city":"Espoo",
         "ISP":"Elisa Oyj",
         "userID":"pT3JHEXx7gbBtH3oAAAK"
      },
      {
         "country":"FI",
         "city":"Espoo",
         "ISP":"Elisa Oyj",
         "userID":"NpKRhenBtlRQaXFPAAAL"
      }
   ],
   "fabricSetupErrors":[
      
   ],
   "fabricTerminationStatuses":[
      {
         "reason":"terminated",
         "connectionID":"37jij3m5wj",
         "localID":"pT3JHEXx7gbBtH3oAAAK",
         "remoteID":"NpKRhenBtlRQaXFPAAAL",
         "timestamp":1.62438934264092E12
      },
      {
         "reason":"terminated",
         "connectionID":"8tk9mk2lwrf",
         "localID":"NpKRhenBtlRQaXFPAAAL",
         "remoteID":"pT3JHEXx7gbBtH3oAAAK",
         "timestamp":1.62438933964147E12
      }
   ],
   "networkGeoData":[
      {
         "country":"GB",
         "city":"Wandsworth",
         "ISP":"COLT Technology Services Group Limited",
         "userID":"pT3JHEXx7gbBtH3oAAAK"
      },
      {
         "country":"GB",
         "city":"Wandsworth",
         "ISP":"COLT Technology Services Group Limited",
         "userID":"NpKRhenBtlRQaXFPAAAL"
      }
   ],
   "terminationStatus":"success",
   "userCount":2,
   "appID":623115995,
   "startTime":"1624389323683",
   "endTime":"1624389344667",
   "userIDList":[
      "pT3JHEXx7gbBtH3oAAAK",
      "NpKRhenBtlRQaXFPAAAL"
   ],
   "fabricSetupTimes":{
      "minSetupDelay":49.5,
      "maxSetupDelay":74.80005,
      "meanSetupDelay":62.150025,
      "medianSetupDelay":62.150025
   },
   "conferenceUrl":"https://dashboard.callstats.io/apps/623115995/conferences/MH58pU3xEguzzqNrBn6V7PZ9dw==-k1-csiop/1624389323683/overview"
}

Individual notification: User Feedback

{
   "confID":"politicalparadesvolunteerunder",
   "feedback":{
      "overallRating":5,
      "comments":"AAA",
      "audioQualityRating":2,
      "videoQualityRating":4
   },
   "originID":"userA",
   "appID":1,
   "backendTimestamp":1491490309595,
   "eventType":"userFeedbackEvent",
   "localID":"Jeffery-0Dz",
   "deviceID":"AAA",
   "timestamp":1491490309595
}

Updated 5 months ago


Webhook Notifications


How do I get the data out of callstats? You do that by configuring notifications. Interval Threshold notifications or End of call summary notifications

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.