CCaaS integration

gecx-chat-ccaas ships opt-in adapters for the major contact-center platforms. Each adapter consumes a TransferContextBundle produced by the SDK and writes it to the destination platform.

Opt-in by design. None of these ship in gecx-chat's core. You only install the adapters you use, and the core SDK never imports any of them.

Install

pnpm add gecx-chat gecx-chat-ccaas

Common shape

Every adapter is a factory returning CcaasAdapter:

interface CcaasAdapter {
  name: string;
  capabilities: CcaasCapabilities;
  onTransferComplete(bundle: TransferContextBundle): Promise<CcaasAck>;
  onTransferFailed?(bundle: TransferContextBundle, reason: string): Promise<void>;
  onTransferUpdate?(bundle: TransferContextBundle): Promise<void>;
}

Call onTransferComplete from your back-end when the cockpit picks up. The adapter records the engagement and returns an ack containing externalId (and usually externalUrl) so you can deep-link from the agent's UI.

Google CCAI Platform

The most important target for CES — drives a real CCAI Platform conversation with the destination queue.

import { createGoogleCcaiAdapter } from 'gecx-chat-ccaas/google-ccai';

const adapter = createGoogleCcaiAdapter({
  projectId: 'cx-prod',
  location: 'us-central1',
  conversationProfileId: 'cp-tier1',
  getAccessToken: () => oauth.fetchAccessToken(),
});

const ack = await adapter.onTransferComplete(bundle);
// → ack.externalId = "projects/cx-prod/locations/us-central1/conversations/abc"

See: https://docs.cloud.google.com/contact-center/ccai-platform/docs

Salesforce Service Cloud

Creates a Case via the REST API, attaches the transcript as a ContentNote, and links it back to the Case. Status defaults to Working for warm transfers and New otherwise.

import { createSalesforceAdapter } from 'gecx-chat-ccaas/salesforce';

const adapter = createSalesforceAdapter({
  instanceUrl: 'https://acme.my.salesforce.com',
  getAccessToken: () => oauth.fetchAccessToken(),
  apiVersion: 'v62.0',
});

const ack = await adapter.onTransferComplete(bundle);
// → ack.externalUrl points to the Case in Lightning

The adapter expects three custom fields on Case: GECX_BundleId__c, GECX_SessionId__c, GECX_TransferType__c. If you haven't created these, drop them from the body — the adapter is robust to Salesforce ignoring unknown fields, but lint-strict orgs may reject the request.

ServiceNow CSM

Posts to sn_customerservice_case by default. Override tableName for non-standard installs.

import { createServiceNowAdapter } from 'gecx-chat-ccaas/servicenow';

const adapter = createServiceNowAdapter({
  instanceUrl: 'https://acme.service-now.com',
  getAccessToken: () => oauth.fetchAccessToken(),
});

await adapter.onTransferComplete(bundle);

Zendesk Support

Creates a ticket, tags it with gecx_chat + the transfer type, and sets priority based on sentiment.

import { createZendeskAdapter } from 'gecx-chat-ccaas/zendesk';

const adapter = createZendeskAdapter({
  subdomain: 'acme',
  getAccessToken: () => oauth.fetchAccessToken(),
  defaultGroupId: 360000000123,
});

await adapter.onTransferComplete(bundle);

Genesys Cloud

Routes the conversation as an ACD callback. Customer-info is attached via the callback data map so the destination agent sees it.

import { createGenesysAdapter } from 'gecx-chat-ccaas/genesys';

const adapter = createGenesysAdapter({
  baseUrl: 'https://api.mypurecloud.com',
  getAccessToken: () => oauth.fetchAccessToken(),
  queueId: 'qid-1234',
});

await adapter.onTransferComplete(bundle);

Five9

Records a contact under a campaign.

import { createFive9Adapter } from 'gecx-chat-ccaas/five9';

const adapter = createFive9Adapter({
  apiRoot: 'https://api.five9.com/wsadmin/v13',
  getAccessToken: () => oauth.fetchAccessToken(),
  campaignId: 'camp-1',
});

await adapter.onTransferComplete(bundle);

Injecting a custom HTTP client

All adapters accept an http option. Override it to inject auth, retries, rate-limiting, or test fakes:

const adapter = createSalesforceAdapter({
  instanceUrl: '…',
  getAccessToken: () => '…',
  http: async ({ method, url, headers, body }) => {
    const res = await retryingFetch(url, { method, headers, body: JSON.stringify(body) });
    return { status: res.status, body: await res.json() };
  },
});

The default client is built on fetch and is dependency-free.