OpenConnect API

Why OpenConnect is Critical for Oracle & Zendesk

OpenConnect enables Experience Cloud to integrate with various contact center platforms, including telephony, voice, ACD, routing, and contact center solutions, to facilitate CRM automation and seamless data transfer.

Key Challenges Addressed

OpenConnect solves common inefficiencies caused by operating multiple disparate systems in Oracle & Zendesk environments. By seamlessly connecting your CRM with contact center routing platforms and telephony voice channels, OpenConnect enhances workflow efficiency in several critical ways:

• Eliminates manual data entry between systems
• Provides real-time synchronization of customer interaction data
• Enables automated workflow triggers based on telephony events
• Creates unified agent experiences across platforms
• Improves data accuracy and reduces human error
• Accelerates response times with automated routing and data population

Building a Connection

Follow this comprehensive 6-step process to establish a working OpenConnect integration. Each step is critical to ensure proper authentication and data flow between your contact center platform and Experience Cloud.

Supported SendMessage Endpoints

OpenConnect provides two types of endpoints for different integration scenarios:

CTI (Computer Telephony Integration) Endpoints

Use CTI endpoints for telephony and contact center integrations:

CRM (Customer Relationship Management) Endpoints

Use CRM endpoints for integrations with Zendesk, Oracle, and other CRM systems:

Request Parameters

CTI (Telephony) Connection Parameters

For CTI integrations, include these required parameters:

CRM Connection Parameters

For CRM integrations (Zendesk, Oracle, etc.), include these required parameters:

Optional Context Data

Pass additional custom data elements in your requests to personalize workflows. This can include interaction data, customer information, routing data, or ACD-specific fields.

// Examples of optional context data
"customerTier": "Platinum",
"orderId": "ORD-12345",
"callType": "Support",
"previousInteractions": 5,
"accountValue": 25000

Sending JWT for Authentication

Recommended: Authorization Header (Bearer Token)

It is strongly recommended to include your JWT in the Authorization header using the Bearer token scheme. This approach ensures secure and standardized transmission of authentication credentials.

Authorization: Bearer <your_jwt_token>

Fallback: Query Parameter or Request Body

In scenarios where it's not technically feasible to include the JWT in the header (such as certain browser-based requests or limited client environments), the token may be passed as a fallback:

For GET Requests

Include the token as a query parameter:

?agentid=<agent_id>&jwt=<your_jwt_token>&event=<event_name>

For POST Requests

Include the token in the request body as a JSON field:

{
  "agentid": "<agent_id>",
  "jwt": "<your_jwt_token>",
  "crmid": "<crm_id>",
  "event": "<event_name>"
}

Example API Calls

POST Request (Recommended)

POST requests provide better security and flexibility for passing complex data structures. Set the Content-Type header to application/json.

POST https://connect.openmethodscloud.com/api/sendmessage/CRM
Content-Type: application/json
Authorization: Bearer <your_jwt_token>

{
  "agentid": "john.doe",
  "crmid": "mycompany",
  "event": "CustomerOnboarding",
  "customerId": "CUST-12345",
  "customerTier": "Premium",
  "source": "InboundCall"
}

JavaScript / Node.js Example

const axios = require('axios');

async function triggerOpenConnect() {
  try {
    const response = await axios.post(
      'https://connect.openmethodscloud.com/api/sendmessage/v1/CTI',
      {
        agentid: 'john.doe',
        crmid: 'mycompany',
        event: 'CustomerOnboarding',
        customerId: 'CUST-12345',
        tier: 'Premium'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.OPENCONNECT_JWT}`
        }
      }
    );
    
    console.log('Success:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

triggerOpenConnect();

Python Example

import requests
import os

def trigger_openconnect():
    url = 'https://connect.openmethodscloud.com/api/sendmessage/v1/CTI'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {os.environ["OPENCONNECT_JWT"]}'
    }
    payload = {
        'agentid': 'john.doe',
        'crmid': 'mycompany',
        'event': 'CustomerOnboarding',
        'customerId': 'CUST-12345',
        'tier': 'Premium'
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        print('Success:', response.json())
    except requests.exceptions.RequestException as error:
        print('Error:', error)

trigger_openconnect()

cURL Example

curl -X POST https://connect.openmethodscloud.com/api/sendmessage/v1/CTI \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "agentid": "john.doe",
    "crmid": "mycompany",
    "event": "CustomerOnboarding",
    "customerId": "CUST-12345",
    "tier": "Premium"
  }'

Troubleshooting

Experience Not Triggered?

If your PopFlow experience isn't launching, check these common issues:

1. Event Name Mismatch
   Ensure the event name is typed correctly with exact case and length (including spaces). Event names are case-sensitive and must match exactly what's configured in Experience Cloud.
2. Unpublished PopFlow
   Double-check that the PopFlow you're trying to trigger is published to the event being called in your API request.
3. Profile Mismatch (Oracle Service Cloud)
   If using Service Cloud CRM, ensure the published profile matches the CRM user's profile. Mismatched profiles will prevent the experience from launching.
4. Invalid or Expired API Key
   Verify your JWT token is valid and hasn't expired. Regenerate if necessary from the API Keys section.
5. Domain Restrictions
   If you've configured domain allow-lists on your API key, ensure requests are coming from authorized domains.

Error Messages & Status Codes

Supported Contact Center Platforms

OpenConnect has been tested and verified with the following contact center platforms. Each platform has specific integration guides available in the Experience Cloud knowledge base.

Best Practices

Security

• Always use Authorization header with Bearer token scheme instead of including JWT in query parameters or request body
• Never expose your API key in client-side code or commit it to version control systems
• Store API keys in secure environment variables or secrets management systems
• Configure domain allow-lists on your API keys to restrict usage to authorized domains only
• Rotate API keys periodically (recommended every 90 days) for enhanced security
• Use separate API keys for development, staging, and production environments
• Monitor API key usage logs for suspicious activity

Performance & Reliability

• Implement retry logic with exponential backoff for failed requests (max 3 retries recommended)
• Set appropriate timeout values (recommended: 10-30 seconds for API calls)
• Use the /v1/CTI endpoint for structured JSON responses and better error handling
• Cache API responses when appropriate to reduce redundant calls
• Monitor API response times and set up alerts for degraded performance
• Use asynchronous/non-blocking requests in high-volume scenarios
• Keep payload sizes well under the 128 KB limit - aim for < 64 KB for optimal performance

Error Handling

• Always check HTTP status codes before processing responses
• Log failed requests with full context (timestamp, parameters, error message) for debugging
• Implement graceful degradation - don't let OpenConnect failures break critical user workflows
• Validate all request parameters before sending to catch errors early
• Handle both network errors and API errors appropriately
• Provide meaningful error messages to users when integrations fail

Testing & Validation

• Test with sample data in a non-production environment before going live
• Verify event names match exactly (case and space sensitive) in all environments
• Test with various payload sizes to ensure you stay within the 128 KB limit
• Validate that all required PopFlows are published before deploying
• Test error scenarios (invalid tokens, missing parameters, timeout conditions)
• Document your integration configuration for future reference

Contributing to This Documentation

This documentation must stay in sync with the OpenConnect user interface and API behaviour. Follow these guidelines when making pull requests that touch OpenConnect functionality.

Check for Interface Changes

Every pull request that modifies the OpenConnect UI or API surface should be reviewed for documentation impact. Before merging, ask yourself:

• Does the PR add, rename, or remove a connection type card (e.g. "Generic CTI Integration", "CRM Connection", "Zoom Contact Center")?
• Are new feature-flag-gated elements introduced that change what the user sees?
• Have endpoint URLs, request parameters, or response formats changed?
• Has the error-handling behaviour or status-code mapping been updated?
• Are there new or updated "Coming Soon" badges, tooltips, or labels?

If the answer to any of the above is yes, update the relevant section of this document in the same PR so the docs and code ship together.

Keeping Documentation & Implementation in Sync

• Same PR, same review — Documentation changes should travel with the code they describe. Reviewers should verify that doc updates match the implementation.
• Section mapping — The major sections of this page correspond directly to areas of the codebase:
  • Supported Contact Center Platforms → platform grid in open-connect-v2.component.html
  • Supported SendMessage Endpoints → API endpoint configuration
  • Request Parameters → parameter types used in API calls
• Feature flags — When a feature is behind a flag, document it as "Coming Soon" here and note the flag name in a code comment so the docs can be promoted to "Supported" once the flag is removed. (Example: Zoom Contact Center was promoted from "Coming Soon" to "Supported" when the apps.ZoomIntegration feature was enabled.)
• Terminology consistency — Use the exact display labels from the UI (e.g. "Generic CTI Integration", not "CTI Connection"). When a label is renamed in the app, update this document to match.

Screenshots & Visual Assets

When a PR changes the visual appearance of the OpenConnect page (new cards, updated labels, badge changes, layout shifts), updated screenshots may be required.

• Capture from E2E test recordings — Run the relevant end-to-end tests in headed mode and extract screenshots from the test video recordings, as we have done in past documentation updates.
• Prompt for a test run — If you are unable to capture screenshots yourself, flag the PR and ask a team member (or the reviewer) to run the E2E suite so screenshots can be taken from the resulting video artefacts.
• Store screenshots in docs/images/ and reference them with a relative path. Use descriptive filenames (e.g. openconnect-zoom-coming-soon.png).
• Include alt-text on every <img> tag for accessibility.

Need Help?

If you encounter issues or have questions about OpenConnect, consult these resources:

• API Keys Documentation - Review the complete guide to generating and managing API keys in Experience Cloud
• Platform-Specific Integration Guides - Access detailed setup instructions for your specific contact center platform
• Experience Cloud Knowledge Base - Search for troubleshooting articles and integration examples
• Account Administrator - Contact your organization's Experience Cloud administrator for environment-specific configuration
• OpenMethods Support - Submit a support ticket for technical assistance with integration issues