GoTo Developer
Contact Support
API Status
Guides
Changelog
Partners
GoTo Developer

How to subscribe to and get call events

The GoToConnect Call Events API allows an integrator to receive information on ongoing calls.

This API requires the following authentication scopes which you should specify while requesting an access token as listed in the prerequisites further down:

  • call-events.v1.notifications.manage
  • call-events.v1.events.read

Prerequisites

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

Usage Guidelines

The Call Events 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.

Flow of the Call Events Subscription

This is the expected flow when you use the Call Events API. You will first create the notification channel using the Notification Channel API. You will then use the channel ID to subscribe to the Call Events API using the /call-events/v1/subscriptions endpoint.

Once you are subscribed, the Call Events API will send the call states to the web server via the Webhook or the WebSocket you used to create the notification channel.

If there is at least one missing call state in the sequence, you can use the /call-events/v1/conversations-spaces endpoint to get the missing call states from the Call Events API.

15 Flow Call events

Subscribe to Call Events Using cURL

You can use the /call-events/v1/subscriptions endpoint to subscribe to the Call Events:

curl --request POST \
  --url https://api.goto.com/call-events/v1/subscriptions \
  --header 'Authorization: Bearer {ACCESS_TOKEN}' \
  --header 'content-type: application/json' \
  --data '{"channelId":"Webhook.channelid-0000-aaaa-0000-channelid","accountKeys":[{"id":"1234567890123456789","events":["STARTING","ENDING"]}]}'

Response:

{
    "accountKeys": [
        {
            "id": "1234567890123456789",
            "status": 200,
            "message": "Success"
        }
    ]
}

It is expected that an HTTP 207 Multi-Status is returned as a successful response.

In this example, the subscription is done using the Account Key and the subscription is for the events with the STARTING and ENDING statuses.

Note: Coming soon You will also be able to subscribe using the User Key, the Line ID and Phone Number ID.

Receiving the Call States

Once you are subscribed, you will start receiving the call states.


{
    "metadata": {
        "conversationSpaceId": "convid-0000-aaaa-0000-convid",
        "direction": "OUTBOUND",
        "accountKey": "1234567890123456789",
        "callCreated": "2023-04-27T18:48:29.413Z"
    },
    "state": {
        "id": "8b29865b-4657-4b6b-8f0e-9ee0a219a8d6",
        "sequenceNumber": 1,
        "type": "STARTING",
        "participants": [
            {
                "participantId": "1aae9b72-acb6-4a3b-9210-a64cc82ebbec",
                "legId": "8fd236d1-5e74-422a-b532-3b007adbb0ae",
                "originator": "1aae9b72-acb6-4a3b-9210-a64cc82ebbec",
                "status": {
                    "value": "RINGING"
                },
                "type": {
                    "value": "LINE",
                    "lineId": "cb31b79d-b125-41c2-b4fe-2edb3a535918",
                    "deviceId": "9722813c-163e-45c8-8faa-10555d2bd000",
                    "extensionNumber": "1090",
                    "name": "Agent A"
                }
            }
        ],
        "timestamp": "2023-04-27T18:48:29.413Z"
    }
}

Requesting Missing Call States

Call states have a sequenceNumber starting at 1 and always increasing which allows detecting missing call states. In the case of a network failure for instance, a call state might not be received through the notification channel. To retrieve missing call states, you can use the /call-events/v1/conversation-spaces endpoint.

To send a GET request to the /call-events/v1/conversation-spaces endpoint, you need the conversationSpaceId which is in the metadata section of call states. The sequenceFrom and sequenceTo query parameters can be specified to select specific missing call states. If sequenceFrom and sequenceTo are not specified, all the call states for the conversation space will be returned.

If for instance the call state with sequence number 3 is missing, the sequenceFrom and sequenceTo should both be set to 3.

curl 'https://api.goto.com/call-events/v1/conversation-spaces/convid-0000-aaaa-0000-convid/events?sequenceFrom=3&sequenceTo=3' \
  --header 'Authorization: Bearer {ACCESS_TOKEN}'

Response:

{
    "pageSize": 100,
    "nextPageMarker": "",
    "metadata": {
        "conversationSpaceId": "convid-0000-aaaa-0000-convid",
        "direction": "OUTBOUND",
        "accountKey": "1234567890123456789",
        "callCreated": "2023-04-24T17:12:15.385Z"
    },
    "states": [
        {
            "id": "0d48498b-bf45-4d26-879d-91cdf96b51bd",
            "sequenceNumber": 3,
            "type": "ACTIVE",
            "participants": [
                {
                    "participantId": "5472fb73-7801-4f51-89d1-def10e17c4f5",
                    "legId": "4cbaab2c-ce07-4432-8280-2f9252024afd",
                    "originator": "5472fb73-7801-4f51-89d1-def10e17c4f5",
                    "status": {
                        "value": "CONNECTED"
                    },
                    "type": {
                        "value": "LINE",
                        "lineId": "141b951b-897b-40a7-b243-5c797b954519",
                        "deviceId": "fdb1a9d1-7984-43ba-8b00-9331bd979389",
                        "extensionNumber": "1090",
                        "name": "Agent A"
                    }
                },
                {
                    "participantId": "543a858f-7dc3-4b2c-ac4b-3d5f07f06b76",
                    "legId": "c5449f69-3a53-4679-a5b0-f2d41ea7347e",
                    "originator": "5472fb73-7801-4f51-89d1-def10e17c4f5",
                    "status": {
                        "value": "CONNECTED"
                    },
                    "type": {
                        "value": "PHONE_NUMBER",
                        "phoneNumberId": "0ef64dd2-5dfe-488c-b923-fbcc884c698c",
                        "number": "+12223334444",
                        "callee": {
                            "name": "Bob",
                            "number": "+17778889999"
                        }
                    }
                }
            ],
            "timestamp": "2023-04-24T17:12:21.921Z"
        }
    ]
}

The request is successful with an HTTP 200 OK returned, and you received the missing call state. In the meantime, you will continue receiving call states through the created notification channel.