Connect API

Real-time messaging infrastructure for client applications

Overview

Version v1

The Connect API provides real-time messaging infrastructure for client applications to communicate with your contact center platform. It enables WebSocket connections via AWS IoT Core, allowing bidirectional message exchange between CRM systems, agent desktops, and your ACD platform.

Core Capabilities

Agent Connect — Establish secure WebSocket MQTT connections for real-time messaging
Send Message — Push data to subscribed clients via CRM or CTI topics
Screen Pop — Deliver context data to agent desktops on incoming interactions

Base URL
https://connect.openmethodscloud.com

Protocol
WebSocket MQTT over WSS

# Establish WebSocket connection
curl -X POST \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{"agentid": "agent123"}' \
  https://connect.openmethodscloud.com/api/agentconnect/CRM

# Response includes signed WebSocket URL
{
  "SignedUrl": "wss://iot.region.amazonaws.com/mqtt?..."
}

Authentication

JWT Bearer Token

All Connect API requests require a valid JWT token issued by your identity provider. The token must be passed in the Authorization header as a Bearer token.

Authorization: Bearer <jwt_token>

Tokens are validated against your configured identity provider. Ensure tokens include the appropriate claims for the operations being performed.

Endpoints

Stable

Agent Connect

POST /api/agentconnect/{rootTopic}

WebSocket URL

Obtain a signed WebSocket URL for establishing an MQTT connection to AWS IoT Core. Clients use this URL to subscribe to real-time message topics.

Parameter	Type	Description
`rootTopic`	string (path)	Topic namespace: `CRM` or `CTI`
`agentid`	string (body)	Unique agent identifier for topic subscription

// Request
POST /api/agentconnect/CRM
{
  "agentid": "agent_12345"
}

// 200 OK Response
{
  "SignedUrl": "wss://iot-endpoint.region.amazonaws.com/mqtt?X-Amz-Algorithm=..."
}

// 401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

// 400 Bad Request
{
  "error": "Agent Id is not provided."
}

Send Message

POST /api/sendmessage/{rootTopic}

Publish

Publish a message to connected clients via the specified topic. This endpoint is typically used by ACD systems to push screen pop data or by CRM systems to broadcast events.

Parameter	Type	Description
`rootTopic`	string (path)	`CRM` — messages from CRM systems `CTI` — messages from ACD/telephony

// Request - CTI Topic (from ACD)
POST /api/sendmessage/CTI
{
  "agentId": "agent_12345",
  "eventType": "call.incoming",
  "ani": "+15551234567",
  "dnis": "+18005551234",
  "callId": "call_abc123"
}

// 200 OK
"Result: Message sent successfully"

// Request via GET with query params
GET /api/sendmessage/CRM?agentId=agent_12345&event=button.click

// 200 OK
"Result: Message published"

// 400 Bad Request
"No data is provided"

GET /api/sendmessage/v1/{rootTopic}

JSON Response

Alternative endpoint that returns a structured JSON response instead of a plain text result. Useful for programmatic integrations that need to parse the response.

// Request
GET /api/sendmessage/v1/CTI?agentId=agent_12345&ani=+15551234567

// 200 OK Response (JSON)
{
  "message": "Published successfully",
  "topic": "CTI/agent_12345",
  "timestamp": "2025-01-15T10:30:00Z"
}

GET /api/sendmessage/bc/{rootTopic}

Browser Close

Special endpoint for browser-based integrations that automatically closes the browser window after sending the message. Commonly used for screen pop acknowledgment flows.

// Request (typically opened in popup/iframe)
GET /api/sendmessage/bc/CRM?event=acknowledged&callId=call_123

// Response: HTML page that closes after 100ms
<body>
  Message sent successfully
  <br>This Browser will close soon...
</body>
<script>setTimeout(function(){window.close();}, 100);</script>

Topic Structure

MQTT

Messages are organized into topics that clients subscribe to. The topic hierarchy allows for targeted message delivery to specific agents or broadcast to groups.

Root Topic	Use Case	Direction
`CTI`	Telephony events from ACD (call arrivals, transfers, hangups)	ACD → Agent Desktop
`CRM`	CRM events and actions (button clicks, record updates)	CRM ↔ Platform

Error Handling

HTTP Status Codes

Status	Code	Description
`400`	Bad Request	Missing required parameters (e.g., agentId not provided)
`401`	Unauthorized	Invalid or expired JWT token
`503`	Service Unavailable	IoT Core connection failure or internal error

// Standard error response
{
  "error": "invalid_token",
  "message": "The access token is invalid or expired."
}