How to create a channel and receiving notifications from GoTo services

The GoToConnect Notification Channel API allows an integrator to subscribe to different GoTo APIs like the Call Events API or the Recording API.

Prerequisites

This article assumes you can make API calls successfully which requires:

• A GoTo Developer account
• An OAuth client
• An access token with the required scopes to use with the

GoTo API to which you want to subscribe (the same token/user must be used for the notification channel creation and for the subscription to the GoTo service).

Usage Guidelines

The Notification Channel API assumes clients are implemented in such a way that unknown attributes are ignored. The addition of new response attributes may occur at any time, for any API response, without prior notice. This is not considered a break in backward-compatibility.

Usage Examples

Webhook

The Notification Channel API requires the URL of a webhook. A webhook is a user-defined callback over HTTP which can receive a request containing a JSON content body. This means that you will need to create a web server and then make it available publicly, you can find complete steps which explain how to expose your web server publicly here.

Note: You can also use tools like localTunnel, ngrok, Serveo, Pagekite and ForwardHQ to name a few.

You will need to provide the URL of your web server to the notification API to create your channel. The channel ID is used to subscribe to other GoTo APIs.

Create the Channel Using cURL

Once you have a webhook URL, you can use the /notification-channel/v1/channels endpoint to create the notification channel. A https://webhook.site/ URL will be used for this example:

curl --request POST 'https://api.goto.com/notification-channel/v1/channels/my-channel-nickname' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'Content-Type: application/json' \
  --data '{"channelType": "Webhook", "webhookChannelData": {"webhook": {"url": "https://webhook.site/b359458d-9987-4def-997a-20ab2d489723"}}}'

Response:

{
    "channelId": "Webhook.channelid-0000-aaaa-0000-channelid",
    "channelNickname": "my-channel-nickname",
    "webhookChannelData": {
        "webhook": {
            "url": "https://webhook.site/b359458d-9987-4def-997a-20ab2d489723"
        },
        "channelType": "Webhook"
    },
    "channelLifetime": 2147483647,
    "resourceURL": "https://webrtc.jive.com/notification-channel/v1/channels/my-channel-nickname/Webhook.channelid-0000-aaaa-0000-channelid",
    "doNotDisturbAware": false
}

It is expected that an HTTP 201 Created is returned as a successful response. If the channel creation is successful the webhook server will also receive an empty request with GoTo Notifications as user-agent in the HTTP headers.

The channel ID Webhook.channelid-0000-aaaa-0000-channelid can now be used to subscribe to other APIs like the Call Events API

WebSocket

The Notification Channel API can also use a WebSocket. It is a communication protocol which enables bidirectional real-time communication between a client and a server over a single TCP connection. A WebSocket uses a handshake process to establish and maintain the connection. The advantage of the WebSocket compared to the webhook is that you do not need to publicly expose your web server but with the WebSocket it needs to keep sending pings to the server to keep the connection alive.

curl --request POST 'https://webrtc.jive.com/notification-channel/v1/channels/my-channel-nickname' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {ACCESS_TOKEN} \
  --data '{"applicationTag": "my_channel_tag","channelType": "WebSockets"}'

Response:

{
    "applicationTag": "my_channel_tag",
    "channelId": "websocket-channel-id-0000-websocket-channel-id",
    "channelNickname": "my-channel-nickname",
    "channelData": {
        "channelType": "WebSockets",
        "isConnected": false,
        "channelURL": "wss://webrtc.jive.com/notification-channel-ws/v1/channels/my-channel-nickname/websocket-channel-id-0000-websocket-channel-id/ws"
    },
    "channelLifetime": 1200,
    "callbackURL": "https://webrtc.jive.com/notification-channel/v1/callBackUrl/websocket-channel-id-0000-websocket-channel-id",
    "resourceURL": "https://webrtc.jive.com/notification-channel/v1/channels/my-channel-nickname/websocket-channel-id-0000-websocket-channel-id",
    "doNotDisturbAware": false
}

It is expected that an HTTP 201 Created is returned as a successful response. You can use the channelURL to create your websocket. It will indicate to the WebSocket to which URL to connect. Once your WebSocket is created, you can then use the channel ID to subscribe to other APIs like with the webhook.

The Call Events Report Guide has the link to a demo application to make a webSocket client in node.js, the example can be easily modified to use the other APIs.