Chat Service

Arc Chat Service (api.melodyarc.com) is the messaging backbone of MelodyArc. It stores and routes chat messages, powers the real-time chat experience inside the Portal — known as the Conversation Portal Website (CPW) — and exposes a REST API that external developers can use to build on MelodyArc without needing expert points or the portal.

How It Works

When an associate opens a conversation in CPW, the following happens:

1. Authentication — CPW calls the portal_op_mcs_auth expert point to exchange an org-scoped API key for a short-lived Chat JWT (10-minute TTL). This token scopes all subsequent chat requests to the org and integration.
2. Message hydration — MACIE (see below) fetches the conversation's existing messages from GET /conversations/controller/{conversation_id}/messages and renders them in the chat thread.
3. Sending a message — When an associate sends a message, MACIE posts it to POST /conversations/controller/{conversation_id}/messages. The Chat Service stores the message and forwards it to the MelodyArc orchestrator for processing.
4. Receiving messages — After storing each message, the Chat Service publishes a conversation_message event to the Agent State Manager (ASM) over Redis. ASM delivers it to the associate's browser over WebSocket, and MACIE renders it in real time.

MACIE (MelodyArc Chat Integration Experience)

MACIE is the chat layer inside CPW. It connects the Portal's WebSocket connection to a @melodyarc/macie-ui embeddable widget, handling everything between the associate's browser and the Chat Service.

MACIE is composed of four layers:

Real-Time Event Delivery

Real-time message delivery is handled by the Agent State Manager (ASM), which lives in the Live Conversation Service. ASM maintains a persistent WebSocket connection to each associate's browser and is responsible for delivering chat events as they happen.

When the Chat Service stores a message, it publishes to a Redis channel scoped to the org and associate:

asm:{orgId}:agent:{agentId}

ASM picks up the event and delivers it to the associate's open WebSocket connection. Three event types flow through this channel:

All events share a common envelope:

{
  "type": "conversation_message",
  "source": "chat",
  "schema_ver": "events/1.0.0",
  "at": 1762178862817,
  "orgId": "acme-corp",
  "userId": "operator-alice",
  "data": { }
}

Using the Chat API

The Chat Service REST API is the primary way to build on MelodyArc without using expert points or the Portal. External developers can use it to create conversations, send and receive messages, and manage operators programmatically.

Base URL: https://api.melodyarc.com

Authentication

All write operations require a Chat JWT. To obtain one:

1. Call POST /auth/generateToken with your org-scoped API key (requires write:generate-chat-token scope).
2. Pass the returned JWT as a Bearer token on subsequent requests.
3. JWTs expire after 10 minutes — request a new one as needed.

Every request must include your org ID header:

x-melodyarc-organization-id: <your-org-id>

Core Endpoints

Start a conversation

POST /conversations/controller
Authorization: Bearer <Chat JWT>
x-melodyarc-organization-id: <org-id>

{
  "sender_id": "user-123",
  "content": "Hello, I need help with my order."
}

The service generates a conversation_id and forwards the message to the MelodyArc orchestrator.

Send a message to an existing conversation

POST /conversations/controller/{conversation_id}/messages
Authorization: Bearer <Chat JWT>
x-melodyarc-organization-id: <org-id>

{
  "sender_id": "user-123",
  "content": "Any update on my request?"
}

Supports @mentions to address specific operators. Rate limited to 20 messages per minute per conversation.

Retrieve messages

GET /conversations/controller/{conversation_id}/messages?page=1&limit=20
Authorization: Bearer <Chat JWT>
x-melodyarc-organization-id: <org-id>

Returns messages in reverse-chronological order.

API Scopes