Gong ExecModule

Overview

GongModule connects ValkyrAI workflows to Gong Public API v2 for bounded, read-only revenue intelligence. It retrieves extensive call data, call transcripts, Gong users, and configured call outcomes through the native map I/O ExecModule ABI.

The connector follows the operation shape of n8n's Gong node while adding ValkyrAI governance: a READY IntegrationAccount, trusted customer-specific Gong API origins, strict filter and response bounds, one page per execution, provider identity checks, transient read retry, shared sensitive-data redaction, and restricted output classification.

No operation creates recordings, changes access, modifies users, uploads CRM data, or performs outreach.

Usage

1. Ask a Gong technical administrator for API access or authorize a Gong OAuth application.
2. Store credentials only in a ValkyrAI IntegrationAccount, set the account to READY, and bind it through ExecModuleConfig.authConfig.integrationAccount.
3. Set apiBase to the Gong-issued API origin. The default is https://api.gong.io; OAuth installations normally receive a customer-specific origin such as https://company-17.api.gong.io.
4. Select one operation and provide only its conditional filters.
5. When hasMore is true, pass nextCursor into a later execution with the same filters.
6. Treat calls, participants, transcripts, comments, and Gong user data as restricted business evidence.

Inputs

Name	Type	Required	Description	Constraints
operation	string	Yes	Operation listed below.	Exact allowlist of seven values.
callId	string	Conditional	Call for get_call or get_transcript.	1–20 decimal digits.
userId	string	Conditional	User for get_user.	1–20 decimal digits.
callIds	array	No	Calls for list filtering.	1–100 numeric IDs.
primaryUserIds	array	No	Call-host filters.	1–100 numeric IDs.
fromDateTime	string	No	Inclusive lower time bound.	ISO-8601 with UTC or numeric offset.
toDateTime	string	No	Exclusive upper time bound.	ISO-8601 with UTC or numeric offset.
workspaceId	string	No	Gong workspace filter.	1–20 decimal digits.
speakerId	string	No	Transcript speaker filter.	1–20 decimal digits; transcript operations only.
contentFields	array	No	Extensive-call content selector.	Allowlisted values only; no arbitrary provider fields.
includeAvatars	boolean	No	Include Gong support avatar users.	list_users only; default false.
cursor	string	No	Opaque continuation from Gong.	1–4,096 safe opaque characters; URLs are rejected.
maxItems	integer	No	Maximum accepted resources in one response page.	1–1,000; default 1,000.
timeoutMs	integer	No	Per-attempt HTTP timeout.	100–300,000; default 30,000.

contentFields accepts parties, media, brief, highlights, keyPoints, outline, callOutcome, structure, trackers, topics, pointsOfInterest, and publicComments. Gong media URLs are temporary and require the separate api:calls:read:media-url scope.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
data	object	Get success	Exactly one identity-verified call, transcript, or user.
id	string	Get success	Requested provider identity.
items	array	List success	One bounded provider page.
count	integer	List success	Items in the returned page.
total	integer	When Gong reports it	Provider-reported matching-record total.
hasMore	boolean	List success	Whether Gong returned another cursor.
nextCursor	string	When another page exists	Opaque continuation for a later execution.
requestId	string	When Gong supplies it	Provider support reference.
httpStatus	integer	Provider response	HTTP status accepted by the module.
attempts	integer	Provider call or failure	Total attempts consumed.
error	object	Failure	Redacted code, message, and retryable fields.

Forward-compatible provider fields remain inside data or items; the module does not fabricate missing summaries, transcripts, identities, totals, or outcomes.

IntegrationAccount Requirements

Setting	Basic access key	OAuth
Status	Exactly READY	Exactly READY
apiKey	Gong access key	Current OAuth access token
password	Gong access key secret	Unused
authentication	basic	oauth
Authorization header	Basic Base64(accessKey:secret)	Bearer accessToken
API base	Gong-issued https://api.gong.io or customer *.api.gong.io origin	api_base_url_for_customer from OAuth

Suggested least-privilege scopes are:

• api:calls:read:extensive for call metadata and analysis.
• api:calls:read:transcript for transcripts.
• api:calls:read:media-url only when media is requested.
• api:users:read for user operations.
• api:call-outcomes:read for call outcomes.

Do not put either credential in payload parameters, apiBase, logs, workflow descriptions, or article content. OAuth refresh is an IntegrationAccount lifecycle concern and is not performed inside this execution module.

Configuration

Illustrative persisted configuration:

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:gong-revenue-intelligence"
  },
  "payloadConfig": {
    "parameters": "{\"authentication\":\"oauth\",\"apiBase\":\"https://company-17.api.gong.io\",\"operation\":\"list_calls\",\"fromDateTime\":\"2026-08-01T00:00:00Z\",\"contentFields\":[\"parties\",\"topics\"]}"
  }
}

The relationship is symbolic. The generated IntegrationAccount owns encrypted credential fields and the runtime resolves it through the native execution configuration.

Operations

Operation	Gong path	Behavior
list_calls	POST /v2/calls/extensive	Returns one cursor page of extensive calls using bounded date, call, host, workspace, and content filters.
get_call	POST /v2/calls/extensive	Filters by one call ID and requires exactly one matching response identity.
list_transcripts	POST /v2/calls/transcript	Returns one page of transcripts filtered by call/date/host/speaker.
get_transcript	POST /v2/calls/transcript	Retrieves one call transcript and verifies callId.
list_users	GET /v2/users	Returns one page of users; optionally includes Gong support avatars.
get_user	POST /v2/users/extensive	Retrieves one user and verifies the user ID.
list_call_outcomes	GET /v2/call-outcomes	Returns the workspace's configured outcome taxonomy.

Call recording creation/media upload, call modification, user provisioning, call-access mutation, data-privacy deletion, CRM upload, flow mutation, engagement writes, statistics, scorecards, trackers, library administration, and webhook triggers are deferred. Those surfaces require separate authorization, idempotency, privacy, or irreversible-write controls.

Errors and Failure Modes

Failure	Cause	Recovery
VALIDATION_ERROR	Missing/invalid ID, time, cursor, origin, content field, credential, bound, or response identity.	Correct the named field; invalid local inputs send no request.
INTEGRATION_ACCOUNT_REQUIRED	No bound Gong account.	Bind the intended account through ExecModuleConfig.
INTEGRATION_ACCOUNT_NOT_READY	Account status is not READY.	Repair or reauthorize the account first.
GONG_HTTP_400	Malformed provider filter or unsupported field combination.	Correct filters; do not reuse a cursor with changed filters.
GONG_HTTP_401	Invalid access key/secret or OAuth token.	Rotate or refresh through the account lifecycle.
GONG_HTTP_403	Required scope, seat, plan, or object permission is absent.	Grant only the needed scope and confirm Gong object visibility.
GONG_HTTP_404	No records matched the requested filter.	Check identity and time bounds; do not fabricate an empty success.
GONG_HTTP_429	Gong's per-second or daily quota was exceeded.	Honor Retry-After; the module applies bounded read retry.
GONG_HTTP_5xx / NETWORK_ERROR	Gong or the network is unavailable.	Read-only requests retry up to the configured bounded attempt count.
RESPONSE_TOO_LARGE	The provider response exceeded 8 MiB.	Narrow dates, call IDs, or content fields.

Provider messages are limited to 500 characters and scrubbed through explicit credential replacement plus ValkyrAI's shared sensitive-data policy.

Example

Retrieve a call transcript for an approved customer follow-up:

{
  "operation": "get_transcript",
  "callId": "7782342274025937895"
}

Expected normalized result:

{
  "status": "success",
  "operation": "get_transcript",
  "data": {
    "callId": "7782342274025937895",
    "transcript": [
      {
        "speakerId": "234599484848423",
        "sentences": [
          {
            "start": 1520,
            "end": 4380,
            "text": "The security review is the remaining launch gate."
          }
        ]
      }
    ]
  },
  "id": "7782342274025937895",
  "requestId": "4al018gzaztcr8nbukw",
  "httpStatus": 200,
  "attempts": 1
}

The transcript text above is illustrative. The module returns only provider data.

Notes

• Pagination: one execution returns one Gong page. Preserve every original filter and pass nextCursor into the next execution. Cursors are opaque and must not be interpreted or replaced with arbitrary URLs.
• Rate limits: Gong documents a default limit of three API calls per second and 10,000 per day. A 429 response includes Retry-After; the module caps provider-directed delay at 60 seconds and total attempts at 10.
• API limits: ID arrays are capped at 100, request JSON at 256 KiB, response bytes at 8 MiB, returned page items at 1,000, content selectors to the documented allowlist, and provider errors at 500 characters.
• Idempotency: every exposed operation is read-only and can be retried at the transport layer. Repeated media URL retrieval can generate different temporary URLs and still represent the same call.
• Destructive behavior: none is exposed. This version cannot create calls, upload media, change call access, delete data, or mutate Gong users or CRM state.
• Privacy: transcripts can contain customer statements, personal data, commercial terms, and regulated information. Keep outputs restricted, apply purpose limitation, and avoid sending them to unrelated models or destinations.
• External verification: deterministic tests cover Basic and OAuth headers, trusted origin enforcement, filter construction, cursor paging, transcripts, users, outcomes, retry, error redaction, response identity, bounds, and metadata discovery. Live provider execution is deferred until a separately authorized Gong tenant and credential are supplied.

See Gong's official API introduction, extensive call endpoint, transcript endpoint, user endpoint, API access guidance, and the official n8n Gong node source for upstream behavior and functional reference.