Uploading calls from a non-integrated telephony system

This article is aimed at developers and integrators who want to learn how to upload calls from telephony systems with which Gong does not have a pre-built integration.

For information on the telephony systems that Gong supports natively, refer to Supported telephony systems.

Overview

Here are the main steps for uploading calls from non-integrated telephony systems to Gong:

1. Use Gong’s API to retrieve a list of users (step 1 below).

   This data is required to map the email address for the host of the call to a Gong user ID which is required for the next step.

2. Upload a call to Gong using one of the following paths:

   • Gong pulls media file (step 2 below) (recommended):

     Your call media file is stored at a URL from which Gong can retrieve it. You’ll make a single API call to Gong providing the call metadata and URL and Gong will pull in the media file.

   • Push media file to Gong (step 2, option 2 below)

     A 2-step process where you make an API call to Gong providing the call metadata, receive a unique ID back from Gong, and then make a second API call to push the media file to Gong.

3. Repeat step 2 to upload a batch of calls.

Before you begin

Pre-requisites

In Gong:

• Have access to the Gong API documentation

• Have a login to your company’s Gong account

• Have access to the Gong API credentials for your account (you will need Technical Admin permissions, or have a Technical Admin provide you with the credentials in a secure manner)

• Have users set up to have their calls imported

In your telephony system:

• Have access to all calls that need to be uploaded

• Have the complete metadata that the telephony system makes available for each call

In your CRM:

• (Optional) Have access to CRM data that you want to associate with calls. This is usually not needed.

Encode your API credentials

Get the API access key and secret from Gong here (requires Technical Admin permissions on your Gong account). You’ll need to BASE64 encode your key pair as ACCESS_KEY:ACCESS_SECRET

export ACCESS_KEY ="...."
export ACCESS_SECRET="..."
export AUTH_HEADER=$(echo "${ACCESS_KEY}:${ACCESS_SECRET}" | base64)

STEP 1: Pull a list of users from Gong

Start by calling the list all users endpoint to pull a list of all Gong users associated with your account. You’ll use the results from this call to map users in your telephony system to their Gong user IDs. This is also a good initial check that you can retrieve data from Gong using the API.

Sample request:

curl \
--header "Content-Type: application/json" \
--header "Authorization: Basic ${AUTH_HEADER}" \
--request GET \
https://api.gong.io/v2/users

The response will include a JSON formatted list of users with a number of items of metadata. Note that the response is paged, with a default page size of 100 records. If there are more than 100 records, the API returns a cursor which you’ll need to submit in a second request to get the next page, and iterate until you’ve retrieved the complete list.

Sample response:

{
  "requestId" : "6d8cgicehos3hobow90",
  "records" : {
  "totalRecords" : 250,
  "currentPageSize" : 100,
  "currentPageNumber" : 0,
  "cursor" : "eyJhbGciOiJIUzI1NiJ9.eyJ0b3Rh..."
 },
 "users" : [ {
  "id" : "65192578128262669",
  "emailAddress" : "[email protected]",
  "created" : "2019-05-26T17:31:25.979+03:00",
  "active" : true,
  "emailAliases" : [ ],
  "firstName" : "Joe",
  "lastName" : "Smith",
  ...

Sample request (second page):

curl \
--header "Content-Type: application/json" \
--header "Authorization: Basic ${AUTH_HEADER}" \
--request GET \
https://api.gong.io/v2/users?cursor=yJhbGciOiJIUzI1NiJ9.eyJ0b3Rh..

You can test the same call using Postman. Here's how.

Troubleshooting

If you receive an error:

• Check there are no errors in the hashed API key or token.

• Validate there aren’t any extra spaces, or other mistakes, in the code.

• The API will provide a meaningful error message to help you debug.

STEP 2: Upload a call to Gong

A note about supported media files. Via API, Gong accepts call recordings in various audio and video file formats, including WAV, MP3, MP4, MKV and FLAC, with a maximum file size of 1.5GB.

Option 1 - Have Gong pull the call media file (recommended)

In this method, you make a single API call to Gong containing the call metadata and a URL at which Gong can access the call media file. For example, if your telephony system is set to upload the files to Amazon S3, you can create an expiring URL with an expiration date. Gong typically fetches your media file within an hour of your API call.

Use the add new call endpoint to upload a call. You’ll need to retrieve metadata from your telephony system (and possibly from your CRM) and map this to the fields in the JSON payload in your request. You should provide as many fields as possible, as these will help users search for calls in the Gong interface. We recommend that you familiarize yourself with your telephony system’s documentation and learn about the available fields.

The most important fields to consider are:

• clientUniqueId (required): Your telephony system’s unique ID for the call. Gong uses this ID to prevent repeat attempts to upload the same call.

• title: You should include a descriptive title for the call, derived from the telephony system metadata. Users can search by title in the Gong interface, so avoid using an ID or other non-human-readable field.

• primaryUser (required): The Gong user ID for the call’s host/owner. You will need to map the owner in your telephony system to their Gong user ID, using the Gong user data you retrieved in step 1. Typically you’ll map from their email address to their user ID.

• actualStart (required): The actual date and time when the call started (in ISO-8601 format).

• workspaceId: Most customers can omit this field.

• parties (required): The parties on the call. As a minimum, the primaryUser must be included as a party. For each party, these are the most import fields to consider:

  • name: The party’s name.

  • phoneNumber: The party’s phone number. This is the most likely unique identifier your telephony system will provide. Gong imports your CRM data and will use this field to try to match the party to a lead or contact record. This allows users to filter based on the properties of the attached CRM record when searching for calls in the Gong interface.

  • emailAddress: The party’s email address. As with phone number, Gong will use this field to match the party to a CRM record, to improve users’ ability to search for calls in the Gong interface.

  • context: Most customers can omit this field. If the party is a lead or contact in your CRM, you can use this field to link them to the CRM ID for the relevant record and override the default association that Gong makes using email address or phone number.

  • userId: If the party is a Gong user, add their Gong user ID, using the Gong user data you retrieved in step 1. This will usually be the case for the primaryUser.

  • mediaChannelId: Some telephony systems separate speakers onto the left and right channels of a stereo recording. If available, it is important to provide this field to define the channel for this party. Otherwise the field can be omitted.

• direction (required): Whether the call was inbound, outbound, a conference call, or unknown. The majority of uploads are typically inbound or outbound dialer calls. Internal calls can be uploaded as conference calls.

• disposition: The disposition of the call. This is a free text field, but you should use an enumerated list of values determined by your company’s sales process, as users can filter on this field when searching for calls in the Gong interface.

• purpose: The purpose of the call. As with disposition, this is a free text field, but you should use an enumerated list of values, as users can filter on this field when searching for calls in the Gong interface.

• context: Most customers can omit this field. If the call is linked to an account or opportunity in your CRM, you can use this field to link it to the CRM IDs for the relevant records. By default Gong tries to associate the call to an opportunity and account by looking at the parties on the call. This field allows you to override Gong’s default association.

• downloadMediaUrl: The expiring URL for the media file. You must include this field, or Gong will expect you to send a follow-up PUT request with the media file (see the next section).

• callProviderCode: Code identifying the provider conferencing or telephony system using predefined values. For example: zoom, gotomeeting, ringcentral, outreach, insidesales, and so on. Contact Gong Support if you need the value for your system.

You need to make a separate request to the add new call endpoint for each call that you need to upload. For each request, Gong will attempt to fetch the call media file from the downloadMediaURL and upload it.

JSON payload template (minimum required fields):

{
    “clientUniqueId”: "",
    “actualStart”: "2018-02-17T02:30:00-08:00",
    “primaryUser": "",
    “parties”:  [ { “userId”: “” }],
    “direction”: “Inbound”,
    “downloadMediaUrl”: “”
}

Use the payload example as a template to create a JSON file called callMetaPayloadFile.json and post it to the server using the example below.

Sample request:

curl \
 --header "Content-Type: application/json" \
 --header "Authorization: Basic ${AUTH_HEADER}" \
 --request POST \
 --data @callMetaPayloadFile.json \
 https://api.gong.io/v2/calls

Response:

{
  "callId": "7782342274025937895",
  "requestId": "4al018gzaztcr8nbukw",
  "url": "https://app.gong.io/call?id=7782342274025937895"
}

An HTTP Status 200 (OK) response includes a unique callId and indicates that Gong has processed the API request and has queued the call media file for upload and processing. If the upload and processing is successful you will later be able to find the call in the Gong user interface. You won’t receive a callback via the API regarding the status or success of the upload.

Tip

Find the uploaded call in the Conversations page using the fields exported from the telephony system as search filters. You can also find the call at the URL returned in the JSON response.

Troubleshooting

If there are any issues processing the initial request, the endpoint returns a descriptive error message. In this instance, you should apply a retry scheme. The endpoint will reject duplicate requests with the same clientUniqueId if the previous request succeeded or is still being processed.

Note that Gong will not process a call that lasts fewer than 60 seconds (after trimming blank audio at the beginning and end of the recording). If this happens, the API request will succeed, but you will not see the call in the Gong interface. You should validate the minimum length of call that you attempt to upload.

Option 2 - Push the call media file to Gong

Use this method if the pull method described above is not appropriate. You make two API requests to upload a call: one to create the call record with all the required metadata and a subsequent request to add the media file.

The first request to the add new call endpoint is identical to option 1 above, with the exception that the downloadMediaUrl field is omitted. The response includes a unique callId.

The second request is a PUT to the add call media endpoint. Add the callId returned by the previous request as a URL parameter and add the media file in the body of the request.

Sample request:

curl \
 --header "Content-Type: application/json" \
 --header "Authorization: Basic ${AUTH_HEADER}" \
 --request PUT \
 --data @callMediaFile \
  https://api.gong.io/v2/calls/7782342274025937895/media

Sample response:

{
  "callId": “7782342274025937895",
  "requestId": "4al018gzaztcr8nbukw",
  "url": "https://app.gong.io/call?id=7782342274025937895"
}

An HTTP Status 200 (OK) response indicates that Gong has successfully uploaded the call. After the call is processed you will be able to find the call in the Gong user interface.

STEP 3: Complete the integration

The examples so far have shown how to upload an individual call. Typically you will need to upload batches of calls. It’s common for a customer to upload the last 30 days of calls to Gong when setting up their integration. This will be determined by your business needs.

You will also set the integration up to upload new calls as they occur. Typically customers run a periodic batch job, for example every hour or once per day, to upload the new calls that have occurred since the last batch. It’s less common to upload calls individually as they occur, but this is possible if your telephony system provides an event when a new call recording is available.

The batching strategy will be determined by your business needs, but you should be aware of the following:

• We recommend that you pull a fresh user list each time you upload a batch of calls. Your company can add, remove, or edit users in their Gong account at any time.

• Gong limits the number API requests per customer. The default limits are 3 requests per second and 10,000 requests per day, across all API endpoints. Remember that you may be making two API requests to upload a single phone call.

• Note that an individual call upload can fail for a number of reasons. Build your batch process so that it is well-behaved if an individual request fails, and log any failed uploads and the response received.

Using Postman to test the API

Pull user list from Gong

You may prefer to use Postman to perform some of your initial testing of the API, particularly if you are coding in a language that makes it slower to iterate. In this example, you will pull a user list from Gong.

1. In Postman, click New, and choose Request.

2. Give your request a name, for example “All users”.

3. Add a description, select a collection, and click Save.

4. Make sure the request type is set to GET, and in the value, paste the endpoint URL: https://api.gong.io/v2/users

5. Go to the Authorization tab.

6. Choose Basic Auth.

7. Paste your key into Username.

8. Paste your secret into Password.

   Postman encodes your key.

   

9. Click SEND.

   The result appears in the bottom panel.

10. Click Save response to save the page results.

11. To get more page results manually using the paging cursor:

    Tip

    This step can also be automated. Refer to this article and this article for more info.

    1. Copy the cursor value from the previous response.

    2. In Postman, go to Params, enter “cursor” as the key, and paste the cursor field into the value.

    3. Click SEND.

       In the results, page 1 is displayed. (Note that the first page of results is page 0.)

    4. Click Save response to save the page results.

       You can add them to the JSON file created in step 10.

    5. Repeat these steps to get the next page of results.