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/v1/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',
        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',
        '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",
    "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

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