GoTo Developer
Contact Support
API Status
Guides
Changelog
Partners
GoTo Developer

Fetching Call Events Reports

This guide illustrates how to fetch a Call Events Report using its conversation space identifier, with a few different ways to get to reports of interest.

Report notifications

A Call Events Report contains detailed information on a call and becomes available as soon as a call completes on the GoTo Connect product1. An application can be notified of such data availability by creating a Call Events Reports notification subscription to receive a notification after each call completes. The notification contains a call indentifier used to fetch the complete report through a REST API.

Summary

You will complete the following steps:

  1. Configure development environment using Node.js.
  2. Download the sample application.
  3. Use the Notification Channel API to create a Websocket notification channel.
  4. Use the Call Events Report API to create a notification subscription and fetch its full report.

Prerequisites

Follow the next steps before running the application.

Create an OAuth client for the application

This guide assumes you already have a developer account and your GoTo account key.

Refer to the OAuth client guide to create a client with the following options:

  • Client name: Call Events Report Demo
  • Redirect URI: http://127.0.0.1:12021/app/redirect
  • Scopes:
    • cr.v1.read
    • call-events.v1.notifications.manage

Create the .env configuration file

Create a .env configuration file in the same directory as the application source code with the following content, replacing placeholder <values> with information noted in the previous step.

OAUTH_CLIENT_ID=<your_client_id>
OAUTH_CLIENT_SECRET=<your_client_secret>
ACCOUNT_KEY=<your_account_key>
LOG_LEVEL=info

Try the application

  1. Run npm install to download Node.js dependencies. This must be done only once.
  2. Run node app or npm start to launch the application.

At any point in time, press Ctrl-C to exit.

When the application starts, you will get prompted to follow a login link before the demo can continue. The client_id and state URL parameter will differ. Note that log timestamps are in the UTC time zone, the same time zone that Call Events Reports payload uses.

[18:42:21.660] info - Starting demo. Press Ctrl-C to exit...

Open this URL in a browser to authenticate:
-------------------------------------------
https://authentication.logmeininc.com/login?service=https%3A%2F%2Fauthentication.logmeininc.com%2FOAuth%2Fapprove
%3Fclient_id%3D11111111-1111-1111-1111-111111111111
%26response_type%3Dcode
%26redirect_uri%3Dhttp%253A%252F%252F127.0.0.1%253A12021%252Fapp%252Fredirect
%26scope%3Dcr.v1.read%2Bcall-events.v1.notifications.manage
%26state%3D1111111111111111111111111111111
-------------------------------------------

After authenticating, the application will:

  1. exchange the authorization code for an OAuth token to use with subsequent API calls.
  2. create a websocket Notification Channel.
  3. create a Call Events Report subscription attached to that channel.
  4. connect the websocket, listen for Call Events Report notifications and use an API to fetch the complete report.

From the Goto Connect softphone, make a test phone call and shortly after hanging up, the application will display its report.

In this example, observe how the application log timestamp is very close to the callEnded timestamp in the report payload.

[18:43:01.423] info - Listener - call events report: {
  "conversationSpaceId": "29a1c77a-e52a-3764-8606-8b02b1277be8",
  "callCreated": "2023-04-24T18:42:43.633Z",
  "callEnded": "2023-04-24T18:43:00.983Z",
  "direction": "OUTBOUND",
  "accountKey": "7507522985186226043",
  "participants": [
    {
      "participantId": "e26feaf0-d390-419f-8f20-c4c83e9f74fe",
      "legId": "602d0871-f21a-4f3c-815c-9f2c21f82cee",
      "originator": "e26feaf0-d390-419f-8f20-c4c83e9f74fe",
      "type": {
        "name": "Caller Name",
        "value": "LINE",
        "lineId": "b07a61db-b61e-4ce5-9593-0f40e9a0f25d",
        "deviceId": "3fd3f634-76f6-46e8-8476-788b3451b085",
        "extensionNumber": "1010"
      }
    },
    {
      "participantId": "6465f9b9-d3ee-4eae-be40-48a899b7daa4",
      "legId": "7350af56-d507-4492-9b9c-d6cb86d9733b",
      "originator": "e26feaf0-d390-419f-8f20-c4c83e9f74fe",
      "type": {
        "name": "Callee Name",
        "value": "LINE",
        "lineId": "5d5efd89-5c02-432d-bd58-933b81b81914",
        "deviceId": "18f65ad4-9884-40df-82e1-70d488ac4ce5",
        "extensionNumber": "1020"
      }
    }
  ],
  "callStates": [
    ... details left out for brevity ...
  ]
}
^C
[18:43:07.897] info - Received signal SIGINT: shutting down...
[18:43:07.898] info - Listener - disconnect(): closing websocket
[18:43:07.898] info - Listener - disconnect(): deleting subscription
[18:43:07.899] info - Listener - disconnect(): deleting notification channel
[18:43:08.270] info - Terminating with exit code 0

The application can be left running for as long as you wish and will automatically refresh websocket channel and perform reconnection attempts on network issues.

Detailed explanation

Turn on extra debugging logs to show all API requests and responses by editing the .env file and setting log level to debug:

LOG_LEVEL=debug

These logs should not be shared because they will contain your OAuth client secret and tokens which are confidential data. The next steps explain the important parts, skipping over details of the authentication flow already covered by the How to obtain an OAuth access token guide.

We assume you have placed your access token in a TOKEN environment variable like this:

# See access_token field of https://authentication.logmeininc.com/oauth/token response
# from the debug logs

export TOKEN='<your_access_token>'

Creating websocket notification channel

The notification channel is the communication media by which Call Events Report notifies the application. It is created by doing an HTTP POST toward the channel creation API. Some details have been left out in the example response.

curl -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  -d '{"channelType":"WebSocket"}' \
  https://api.goto.com/notification-channel/v1/channels/demo

{
  "channelId": "0XbOBiat_MAPrjoIjCB7KWSrIsofrzEU1jYNxtKu7Ji__wWNux1enJwXuzjAVuRme68g8dUDAt7zC6PtLGMd5jw",
  "channelData": {
    "channelType": "WebSockets",
    "channelURL": "wss://webrtc.jive.com/notification-channel-ws/v1/channels/demo/0XbOBiat_MAPrjoIjCB7KWSrIsofrzEU1jYNxtKu7Ji__wWNux1enJwXuzjAVuRme68g8dUDAt7zC6PtLGMd5jw/ws"
  }
}

The important parts of the response are the channelId and channelData.channelURL field to use with the next API calls.

Creating Call Events Report subscription

A subscription is required to receive completed calls of a GoTo Connect account. The simplest subscription type requires only an account key and channel ID to relay all completed calls of that account:

curl -H "Authorization: Bearer ${TOKEN}" -H 'Content-Type: application/json' \
  -d '{"channelId":"0XbOBiYzaBjzIvrf0xh9MlXYvEMozpvgEiRys-G3JuQDHmrMZtTXUh1U3y2805Rq6oUaxgF5UMRG2Bu3iStItJw","eventTypes":["REPORT_SUMMARY"],"accountKeys":["7507522985186226043"]}' \
  https://api.goto.com/call-events-report/v1/subscriptions

{
  "items": [
    {
      "id": "e0d161f0-3b31-494a-9a2a-a26bfb5a499e",
      "channelId": "0XbOBiYzaBjzIvrf0xh9MlXYvEMozpvgEiRys-G3JuQDHmrMZtTXUh1U3y2805Rq6oUaxgF5UMRG2Bu3iStItJw",
      "value": "7507522985186226043",
      "eventTypes": [
        "REPORT_SUMMARY"
      ]
    }
  ]
}

Note: even though the request does not require specifying eventTypes, it is highly recommended to include the REPORT_SUMMARY event type to receive the latest notification payload schema. Not specifying any event type will fall back to using LEGACY events for backward compatibility (not recommended).

Receiving Call Events Report notifications

Once the notification channel and associated subscription exists, a websocket client must be connected to the channel URL (see channelData.channelURL).

In most programming languages, a websocket client library will expose a message handler for reception of incoming websocket messages. All notifications share a common envelope with fields that can be used to determine how to properly handle the messages:

  • data.source can be used to determine the event publisher;
  • data.type can be used to discriminate the payload schema of the data.content field;
  • data.content contains the notification payload itself.

Below is an example Call Events Report notification. For brevity, some fields have been left out.

{
  "data": {
    "source": "call-events-report",                  <=== Identifies Call Events Report
    "type": "REPORT_SUMMARY",                        <=== Identifies the event type (content schema)
    "timestamp": "2023-04-24T18:55:35.993967226Z",
    "content": {                                     <=== Payload
      "conversationSpaceId": "29a1c77a-e52a-3764-8606-8b02b1277be8"
    },
    "bypassDoNotDisturb": null
  }
}

The important field here is the conversationSpaceId that is the key to get the associated Call Events Report.

Browsing report summaries

Alternatively, reports can be browsed with the report-summaries endpoint using a simple HTTP GET. Each summary contains a digest of a conversation, and can be used to quickly glance over how a call went.

Summaries can be searched using either accounts, lines, phone numbers or users. By taking the same account key as in the subscription example, searching for report summaries for a given day would look like this (for brevity, some fields have been left out):

curl -H "Authorization: Bearer ${TOKEN}" \
  'https://api.goto.com/call-events-report/v1/report-summaries?accountKey=7507522985186226043&startTime=2024-07-01T00%3A00%3A00Z&endTime=2024-07-02T00%3A00%3A00Z'

{
  "pageSize": 100,
  "items": [
    {
      "conversationSpaceId": "29a1c77a-e52a-3764-8606-8b02b1277be8",
      "accountKey": "7507522985186226043",
      "callCreated": "2023-04-24T18:42:43.633Z",
      "callEnded": "2023-04-24T18:43:00.983Z",
      ...                              <=== Content left out for brevity
    },
    ...                                <=== Other report summaries for the same day
  ]
}

Fetching a Call Events Report

After either receiving a Call Events Report notification or finding a particular report summary of interest, a simple HTTP GET can be used to fetch the report using the conversationSpaceId value. The last part of the URL this conversation space ID.

curl -H "Authorization: Bearer ${TOKEN}" \
  https://api.goto.com/call-events-report/v1/reports/9a5ad0e3-4509-3a56-9630-0efba4efa11d

{
  "conversationSpaceId": "29a1c77a-e52a-3764-8606-8b02b1277be8",
  "callCreated": "2023-04-24T18:42:43.633Z",
  "callEnded": "2023-04-24T18:43:00.983Z",
  "direction": "OUTBOUND",
  "accountKey": "7507522985186226043",
  "participants": [ ... ],             <=== Content left out for brevity
  "callStates": [ ... ]
}

Websockets and authentication concerns

Because OAuth access tokens have a limited lifetime, the application proactively refreshes them so that it can be left running for a long time.

Websocket also have such lifetime limitation and will need to be periodically refreshed. The remote endpoint may also require you to recreate a new notification channel. This can happen during regular service upgrades.

1: Although all reports are available for querying directly after call completion, some features involving post-call analysis will appear in the report only when they are individually completed. Refer to the API documentation for more details.