Building a Genesys Cloud Plugin Backend That Exposes Custom REST endpoints for Agent-Side Tools Using the Plugin SDK and TypeScript
What You Will Build
- A Node.js backend service that registers custom routes under the Genesys Cloud Plugin Platform, returning structured agent queue membership data and conversation summaries.
- This implementation uses the
genesyscloud-plugin-sdkandgenesyscloud-platform-clientSDKs. - The tutorial covers TypeScript with strict mode, async/await patterns, pagination handling, and production-grade error handling.
Prerequisites
- Genesys Cloud organization with Plugin development permissions
- Node.js 18+ and npm
genesyscloud-plugin-sdk(v2.x)genesyscloud-platform-client(v175.x or later)- TypeScript 5.x
- Required OAuth scope for underlying API calls:
user:read,routing:read
Authentication Setup
Plugin backends execute inside the Genesys Cloud managed runtime environment. You do not configure standard OAuth client credentials flows. The runtime automatically injects the authenticated agent access token into the request context. The genesyscloud-plugin-sdk exposes a pre-configured platformClient instance through context.client. This instance inherits the scope and identity of the user triggering the plugin request. Token caching and refresh logic are handled by the platform runtime. You only need to import the SDK and attach your router.
import { createPluginServer, Router } from 'genesyscloud-plugin-sdk';
import { platformClient } from 'genesyscloud-platform-client';
const router = new Router();
// Routes are registered here
// router.get('/agent-tools/data', handler);
createPluginServer(router);
Implementation
Step 1: Initialize the Plugin Server and Router
The plugin SDK expects a single export that initializes the server. You create a Router instance, attach route handlers, and pass the router to createPluginServer. The SDK automatically binds the server to the internal Genesys Cloud execution port and handles lifecycle events.
import { createPluginServer, Router, PluginContext, PluginRequest, PluginResponse } from 'genesyscloud-plugin-sdk';
const router = new Router();
router.get('/agent-tools/queue-members', async (context: PluginContext, request: PluginRequest, response: PluginResponse) => {
await handleQueueMembers(context, response);
});
createPluginServer(router);
HTTP Request/Response Cycle
GET /api/v2/plugin/platform/{pluginId}/agent-tools/queue-members?page_size=25
Host: {org}.mygen.com
Authorization: Bearer {agent_access_token}
Accept: application/json
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"entities": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jane Doe",
"routing_email_address": "jane.doe@example.com",
"routing_phone_numbers": ["+15551234567"],
"routing_status": "available"
}
],
"nextPage": "/api/v2/users?division_id=123&page_size=25&page_token=abc123",
"pageSize": 25,
"totalCount": 142
}
Step 2: Create a Custom Endpoint with Pagination
Genesys Cloud REST APIs use cursor-based pagination via the nextPage field. You must loop through pages until nextPage returns null. The following handler fetches all users matching a division, aggregates them, and returns a clean payload for the agent tool.
import { platformClient } from 'genesyscloud-platform-client';
async function handleQueueMembers(context: PluginContext, response: PluginResponse) {
try {
const { divisionId } = context.request.query as { divisionId?: string };
if (!divisionId) {
response.status(400).json({ error: 'divisionId query parameter is required' });
return;
}
const apiClient = context.client as typeof platformClient;
const usersApi = apiClient.UsersApi;
const allUsers: any[] = [];
let nextPage = `/api/v2/users?division_id=${encodeURIComponent(divisionId)}&page_size=25`;
let pageCount = 0;
const maxPages = 20; // Prevent runaway loops
while (nextPage && pageCount < maxPages) {
const result = await usersApi.postUsersQuery({
body: {
divisionId: divisionId,
pageSize: 25,
nextPage: nextPage.includes('page_token') ? nextPage.split('page_token=')[1]?.split('&')[0] : undefined
}
});
if (result.entities) {
allUsers.push(...result.entities);
}
nextPage = result.nextPage || null;
pageCount++;
}
response.status(200).json({
success: true,
totalCount: allUsers.length,
agents: allUsers.map(u => ({
id: u.id,
name: u.name,
status: u.routing_status,
email: u.routing_email_address
}))
});
} catch (error) {
handleApiError(error, response);
}
}
OAuth Scope Requirement: user:read
Non-Obvious Parameter Note: The postUsersQuery endpoint accepts a nextPage string directly in the request body for pagination continuation. You must extract the page_token from the previous response or pass the full nextPage URL depending on SDK version behavior. The example above demonstrates token extraction for safety.
Step 3: Implement Retry Logic and Error Handling
Genesys Cloud APIs return 429 Too Many Requests when rate limits are exceeded. Production plugin backends must implement exponential backoff. You also need to map SDK exceptions to HTTP status codes for the agent frontend.
async function fetchWithRetry<T>(apiCall: () => Promise<T>, maxRetries = 3): Promise<T> {
let attempt = 0;
while (true) {
try {
return await apiCall();
} catch (error: any) {
if (error.status === 429 && attempt < maxRetries) {
const retryAfter = parseInt(error.headers?.['retry-after'] || '2', 10);
const delay = Math.pow(2, attempt) * 1000 + (retryAfter * 1000);
console.log(`Rate limited. Retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
await new Promise(resolve => setTimeout(resolve, delay));
attempt++;
continue;
}
throw error;
}
}
}
function handleApiError(error: any, response: PluginResponse) {
const status = error.status || 500;
const message = error.message || 'Internal server error';
switch (status) {
case 401:
response.status(401).json({ error: 'Unauthorized. Agent token expired or invalid.' });
break;
case 403:
response.status(403).json({ error: 'Forbidden. Missing required OAuth scope.' });
break;
case 404:
response.status(404).json({ error: 'Resource not found.' });
break;
case 429:
response.status(429).json({ error: 'Rate limit exceeded. Please retry later.' });
break;
default:
console.error('Plugin API Error:', error);
response.status(500).json({ error: 'Internal server error. Check plugin logs.' });
}
}
HTTP Error Response Example
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "Forbidden. Missing required OAuth scope."
}
Complete Working Example
Copy the following into src/index.ts. Run npm install genesyscloud-plugin-sdk genesyscloud-platform-client typescript @types/node and compile with tsc.
import { createPluginServer, Router, PluginContext, PluginRequest, PluginResponse } from 'genesyscloud-plugin-sdk';
import { platformClient } from 'genesyscloud-platform-client';
const router = new Router();
router.get('/agent-tools/queue-members', async (context: PluginContext, request: PluginRequest, response: PluginResponse) => {
try {
const { divisionId } = context.request.query as { divisionId?: string };
if (!divisionId) {
response.status(400).json({ error: 'divisionId query parameter is required' });
return;
}
const apiClient = context.client as typeof platformClient;
const usersApi = apiClient.UsersApi;
const allUsers: any[] = [];
let nextPage = `/api/v2/users?division_id=${encodeURIComponent(divisionId)}&page_size=25`;
let pageCount = 0;
const maxPages = 20;
while (nextPage && pageCount < maxPages) {
const result = await fetchWithRetry(() =>
usersApi.postUsersQuery({
body: {
divisionId: divisionId,
pageSize: 25,
nextPage: nextPage.includes('page_token') ? nextPage.split('page_token=')[1]?.split('&')[0] : undefined
}
})
);
if (result.entities) {
allUsers.push(...result.entities);
}
nextPage = result.nextPage || null;
pageCount++;
}
response.status(200).json({
success: true,
totalCount: allUsers.length,
agents: allUsers.map(u => ({
id: u.id,
name: u.name,
status: u.routing_status,
email: u.routing_email_address
}))
});
} catch (error) {
handleApiError(error as any, response);
}
});
async function fetchWithRetry<T>(apiCall: () => Promise<T>, maxRetries = 3): Promise<T> {
let attempt = 0;
while (true) {
try {
return await apiCall();
} catch (error: any) {
if (error.status === 429 && attempt < maxRetries) {
const retryAfter = parseInt(error.headers?.['retry-after'] || '2', 10);
const delay = Math.pow(2, attempt) * 1000 + (retryAfter * 1000);
console.log(`Rate limited. Retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
await new Promise(resolve => setTimeout(resolve, delay));
attempt++;
continue;
}
throw error;
}
}
}
function handleApiError(error: any, response: PluginResponse) {
const status = error.status || 500;
switch (status) {
case 401:
response.status(401).json({ error: 'Unauthorized. Agent token expired or invalid.' });
break;
case 403:
response.status(403).json({ error: 'Forbidden. Missing required OAuth scope.' });
break;
case 404:
response.status(404).json({ error: 'Resource not found.' });
break;
case 429:
response.status(429).json({ error: 'Rate limit exceeded. Please retry later.' });
break;
default:
console.error('Plugin API Error:', error);
response.status(500).json({ error: 'Internal server error. Check plugin logs.' });
}
}
createPluginServer(router);
Common Errors & Debugging
Error: 401 Unauthorized
- What causes it: The agent access token injected into the plugin context has expired, or the agent session terminated.
- How to fix it: The plugin runtime automatically refreshes tokens for active sessions. If the agent logs out, the request fails. Implement client-side token refresh in the frontend plugin, or catch the 401 and redirect the agent to re-authenticate.
- Code showing the fix:
if (error.status === 401) {
response.status(401).json({
error: 'Session expired',
redirect: '/plugin/auth/refresh'
});
return;
}
Error: 403 Forbidden
- What causes it: The plugin application lacks the required OAuth scope for the underlying API call.
- How to fix it: Navigate to the Plugin configuration in the Genesys Cloud admin console. Add
user:readorrouting:readto the Plugin OAuth scopes. Republish the plugin version. - Code showing the fix: No code change required. Update the plugin manifest scopes field and deploy.
Error: 429 Too Many Requests
- What causes it: The plugin exceeds the per-user or per-organization rate limit for the target API endpoint.
- How to fix it: Implement the
fetchWithRetryexponential backoff pattern shown in Step 3. Cache frequent read operations using the plugincontext.cacheobject to reduce API calls. - Code showing the fix:
// Use plugin cache to avoid repeated 429s
const cacheKey = `queue_members_${divisionId}`;
const cached = context.cache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < 60000) {
response.status(200).json(cached.data);
return;
}
// ... fetch logic ...
context.cache.set(cacheKey, { data: result, timestamp: Date.now() });
Error: 500 Internal Server Error
- What causes it: Unhandled SDK exception, malformed JSON response, or runtime type mismatch in TypeScript.
- How to fix it: Enable strict TypeScript compilation. Wrap all API calls in try-catch blocks. Log the full error object to
console.errorfor plugin log inspection in the Genesys Cloud admin UI. - Code showing the fix:
try {
const result = await usersApi.postUsersQuery({ body: { divisionId } });
// Process result
} catch (err: any) {
console.error('Users API failed:', JSON.stringify(err, null, 2));
response.status(500).json({ error: 'Failed to fetch user data' });
}