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 payload as soon as a call completes on our GoTo Connect product.

A Call Events Report contains detailed information and becomes available as soon as a call completes. 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","accountKeys":["7507522985186226043"]}' \
  https://api.goto.com/call-events-report/v1/subscriptions

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

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 have a common envelope where the event publisher can be determined by inspecting the data.source field. The payload is in the content field.

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": "call-events-report",
    "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 we will to get its Call Events Report.

Fetching the Call Events Report

After receiving a Call Events Report notification, 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.dev.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.