Create an app for Gong

This article covers how to create an app which integrates with Gong and which supports data residency regulations. By utilizing our APIs you can create apps which use both the backend or frontend public APIs. Setting up an app to integrate with Gong includes the following steps:

1. Ensure you have credentials to log into your Gong Sandbox

2. Submit details of the integration as described in Create an app for Gong

3. Set up oAuth authentication if required

4. Create your app and test it

5. Update your integration details in Gong if needed

6. Publish the app in the Gong Collective. Your customers can then install the app on their instance of Gong, and their reps can then embed your HTML content to their emails.

In addition, you should decide which APIs you need in order to create your app.

Set up a developer account

Fill in this form to get a Gong developer account. This can take up to five working days.

Submit your integration details to Gong

Provide Gong with information on your integration, and receive the keys required to set up oAuth access. You can edit this information later if needed.

To submit your integration details to Gong:

1. Click Company settings > Ecosystem > API.

2. In the INTEGRATIONS tab, click Create Integration.

3. In the Integration details area, enter your integration name and a description, and short description. Once your integration is published, your integration name and short description are displayed in the integrations page, and the description is displayed on the specific page for your integration.

4. In the App logo area, upload 2 different-sized logos:

   • The small logo is used in the Gong app management page

   • The large logo is used in the OAuth connection approval screen

5. In the Required authorization scopes area, select the scopes that your app needs.

   Check the API documentation to see which APIs use which scopes. When installing your app, customers will be asked to grant access to the entities accessed by these scopes.

6. Add the links requested for your app:

   • Redirect URI needed for the OAuth authentication: only relevant if you are setting up OAuth authentication

   • Link to your integration's privacy policy page

   • Link to your terms and conditions page

   • Link to your integration's help article

   • Link to page in your integration where authorization process begins

   • Emails of contacts in your organization: list of emails of people in your organization that Gong can reach out to

   • Domains: list of your organization’s domains

7. Select the iFrame toggle integration toggle if you want to create a frontend integration with Gong. For details on the JavaScript SDK see xxx. You must provide the following:

   • Email composer: To enable adding suggested content to an email, provide a URL to your app which can add media or other content in the Gong email composer.

   • Account information: To enable adding content relevant to an account in the Engage account or pipeline pages, provide a URL to an app which returns data for that account.

   • Allowed origins: A list of static URLs that the iFrame can load. If you need to load dynamic sub-domains, you must configure this using the integrations-settings API.

8. Click Save. A new row appears in the list of integrations, with the Client ID and the Client Secret. You can also see the app status and edit the app details.

   

Set up OAuth access

Note:

You must be a Gong tech admin to set this up

If your app requires OAuth access, run this procedure once to set up OAuth. Use the client ID and the client secret you got from Gong and follow these steps so that you can access Gong's API on behalf of our mutual customers.

This follows the standard OAuth procedures as per RFC 6749, and explains the details of the protocol.

Use the authorization code flow

Enter the authorize URL in a browser as follows:

https://app.gong.io/oauth2/authorize?
client_id=<client_id_from_Gong>&response_type=code&scope=<list_of_scopes_you_require_access_to>&redirect_uri=<URI_OAuth_should_redirect_to>&state=296bc9a0-a2a2-4a57

The endpoint receives the following parameters:

• client_id matches the Client ID provided by Gong when you registered your integration.

• response_type is code, indicating that we're using the authorization code grant type.

• Use scope to specify the access scopes you need in your app. This is a space-delimited list of the scopes you selected when you registered your integration.

• redirect_uri is the callback endpoint where the user-agent (browser) will be redirected along with the access code. This must match one of the redirect URIs you specified when registering your integration.

• state is a random arbitrary alphanumeric string that the authorization server will reproduce when redirecting the user-agent back to the client. This is used to help prevent cross-site request forgery.

For more information on these parameters, refer to the OAuth 2.0 Specification.

If the user does not have an active Gong sign-in session, you will have to sign into Gong. Make sure you sign in with the credentials of a tech admin. An authorization page will appear requesting approval of the scopes.

Once the user approves, they will be redirected to the redirect_uri endpoint specified, along with a code and the state, as shown here:

https://example.com/oauth_cb?code=
eyJlbmMiOiJBSlV2R0NNIiwiYWxnIjoiZGlyIn0.RSJretizGL2N8625.5
GrNjj9jBKSMzaRYsktK3Q9CFa9vOqSVMRwbewEJXXPvexMSA0R8Q
PLeeQjeda1hHbPIABFAS82sVRMPQ.GF6t2dK-PvqbLs32iWc5pg
&state=296bc9a0-a2a2-4a57

The code is valid for 10 minutes, during which it can be exchanged for an access token as explained below.

Exchange the code for an access token

This should be done in a client such as Postman that can run a post request.

Copy the code in the url from the previous step and pass it via the /generate-customer-token endpoint. Use HTTP Basic Authorization when sending the POST request as shown below:

Authorization: Basic <token>

To create the basic token, combine the client_id and the client_secret you received from Gong with a colon (:), and then encode in Base64 as shown here:

Base64(<client_id>:<client_secret>)

Following is the URL for the HTTP POST request:

https://app.gong.io/oauth2/generate-customer-token?
grant_type=authorization_code&code=eyJlbmMiOiJBMjU2R0NNIiw
YWxnIjoiZGlyIn0..S_6dW2iO3QJj_D0s.Sa7P1N
y1XYsIgNDtAffPG3kh0ovf0_QPTXitYpUdRztXWGmkZrUQHFVbAs41ZKuB
wSIJSfyvJdKnIruZ
1WN_i.hajm9Bxv7JInrX503iGeZw&client_id=rekgfz28j&redirect_
uri=https://example.com/oauth_cb&validity_duration=600

The generate-customer-token endpoint receives the following parameters:

• code: the access code you retrieved in Use the authorization code flow.

• client_id: the Client ID of the Gong OAuth application that you created.

• redirect_uri: the callback location where the user-agent is directed along with the code. This must match the redirect_uri that was specified in the token request in Use the authorization code flow.

• validity_duration: (optional) defines the number of seconds the token is valid for. By default, the token is valid for 1 day. Include this parameter if you want to change the default amount of time the token is valid for.

The generate-customer-token response is as follows:

{
"access_token": "eyJhbG[...]9pDQ",
"refresh_token": "eyJhbF[...]5lSA",
"expires_in": 525600,
"token_type": "Bearer",
"scope": "api:calls:create api:calls:read:basic”

"api_base_url_for_customer": "https://company-17.api.gong.io"
}

This returns the access token which by default is valid for 1 day. The token should be used in the Bearer token authentication in the Gong Public API, and a refresh token for the future (see Refresh access token when expired).

Requests using this authentication token should be directed to the URI specified in the api_base_url_for_customer parameter. The api_base_url_for_customer is different for each customer and should be saved as part of the customer's context. 

Refresh access token when expired

Your access token expires periodically. Refresh the access token using the refresh token provided with your last access token.

Use HTTP Basic Authorization when sending the POST request as shown below:

Authorization: Basic <token>

To create the basic token, combine the client_id and the client_secret you retrieved after creating the app with colon (:), and then encode in Base64 as shown here:

Base64(<client_id>:<client_secret>)

Following is the URL for the HTTP POST request:

https://app.gong.io/oauth2/generate-customer-token?
grant_type=refresh_token&refresh_token=eyJlbmMiOiJBMjU2R0NNIiw
YWxnIjoiZGlyIn0..S_6dW2iO3QJj_D0s.Sa7P1N
y1XYsIgNDtAffPG3kh0ovf0_QPTXitYpUdRztXWGmkZrUQHFVbAs41ZKuB
wSIJSfyvJdKnIruZ
1WN_i.hajm9Bxv7JInrX503iGeZw&validity_duration=600

The generate-customer-token has the following parameters:

• refresh_token: is the refresh token you received with your last access token

• validity_duration: (optional) defines the number of seconds the token is valid for. By default, the token is valid for 1 day. Include this parameter if you want to change the default amount of time the token is valid for.

The generate-customer-token response is as follows:

{
"access_token": "eyJhbG[...]9pDQ",
"refresh_token": "eyJhbF[...]5lSA",
"expires_in": 525600,
"token_type": "Bearer",
"scope": "api:calls:create api:calls:read:basic”

"api_base_url_for_customer": "https://company-17.api.gong.io"
}

The response includes the access token which by default is valid for 1 day. The token should be used in the Bearer token authentication in the Gong Public API, and a refresh token for the future.

Requests using this authentication token should be directed to the URI specified in the api_base_url_for_customer parameter. The api_base_url_for_customer is different for each customer and should be saved as part of the customer's context. 

Get started with your app

Now is the time to create your app. Set up a sandbox and test it.