API Reference: Conversations

Overview

Conversations provide threaded messaging between team members and constituents. Each conversation is a sequence of messages exchanged over chat, email, SMS, or recorded as internal notes, often linked to a Data Record (the person). The core endpoints on this page are standard tier and require the DATA_CONVERSATIONS_VIEW feature permission; a much larger standard-tier surface covers the inbox workspace, conversation widgets, routing rules, and analytics — summarized below.

Key Concepts

• Thread — A conversation is a thread of messages with a visitor or constituent, optionally linked to a data record.
• Channel — Message channels: CHAT (embedded widget), FORM, EMAIL, SMS, WHATSAPP, FACEBOOK, and INTERNAL_NOTE (visible only to the team). A conversation also records its origin channel as channel.
• Status — OPEN, PENDING, RESOLVED, CLOSED, or ESCALATED. Priority is LOW, NORMAL, HIGH, or URGENT.
• Author type — Each message has an authorType: END_USER, AI, AGENT, or SYSTEM. Conversations with aiHandling: true are currently answered by the AI assistant.
• Assignment — Conversations may be assigned to a team user (assignedUserId, a user Simply ID) for handling.

List Conversations

GET /v1/conversations supports status, channel, and assignedUserId filters plus limit (1–100, default 25) and offset, ordered by most recent message.

const conversations = await s360.conversations.list({
  status: 'OPEN',
  limit: 25,
});

for (const conv of conversations.data) {
  console.log(`${conv.id}: ${conv.subject ?? '(no subject)'} [${conv.channel}]`);
}

curl -s "https://api.simply360.app/v1/conversations?status=OPEN&limit=25" \
  -H "Authorization: Bearer $S360_API_KEY"

Get a Conversation

const conversation = await s360.conversations.get('CONV-1234-ABCD');
console.log(conversation.data);

curl -s "https://api.simply360.app/v1/conversations/CONV-1234-ABCD" \
  -H "Authorization: Bearer $S360_API_KEY"

Create a Conversation

POST /v1/conversations accepts subject, channel (default CHAT), priority (default NORMAL), visitorName, and visitorEmail. New conversations start with status OPEN.

const created = await s360.conversations.create({
  subject: 'Follow-up on event registration',
  channel: 'EMAIL',
  visitorName: 'Jane Doe',
  visitorEmail: 'jane@example.com',
});

List Conversation Messages

Messages are returned oldest first; limit defaults to 50 (max 100).

const messages = await s360.conversations.listMessages('CONV-1234-ABCD', {
  limit: 50,
});

for (const msg of messages.data) {
  console.log(`[${msg.channel}] ${msg.authorType}: ${msg.content}`);
}

curl -s "https://api.simply360.app/v1/conversations/CONV-1234-ABCD/messages?limit=50" \
  -H "Authorization: Bearer $S360_API_KEY"

Post a Message

Add an agent message to an existing conversation. The body accepts content (required), channel (default CHAT), and contentType (default TEXT). Use channel: "INTERNAL_NOTE" for team-only notes.

TypeScript SDK

const reply = await s360.conversations.sendMessage('CONV-1234-ABCD', {
  content: 'Thank you for reaching out. We will follow up shortly.',
  channel: 'CHAT',
});

console.log(`Sent message: ${reply.data.id}`);

cURL

curl -s -X POST "https://api.simply360.app/v1/conversations/CONV-1234-ABCD/messages" \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thank you for reaching out. We will follow up shortly.",
    "channel": "CHAT"
  }'

Update a Conversation

PUT /v1/conversations/{conversationSimplyId} updates status, priority, subject, and assignedUserId (a team member's user Simply ID, or null to unassign). Setting status to RESOLVED stamps resolvedAt.

await s360.conversations.update('CONV-1234-ABCD', {
  status: 'RESOLVED',
});

Inbox, Widgets, Routing & Analytics

The full conversation workspace is also exposed as standard-tier endpoints. Highlights, grouped by area:

Area	Representative Endpoints	Description
Inbox workspace	GET /v1/conversations/inbox, GET .../inbox/{id}, POST .../inbox/{id}/messages, POST .../inbox/{id}/read, GET .../inbox/unread-summary, GET .../inbox/by-record/{dataRecordSimplyId}, GET .../inbox/{id}/related	The agent inbox: filtered lists, rich detail, message send/edit/delete, read cursors, unread counts, and per-record threads.
Lifecycle	PUT .../inbox/{id}/takeover, PUT .../inbox/{id}/assign-ai, PUT .../inbox/{id}/snooze / unsnooze, POST .../inbox/{id}/merge, POST / DELETE .../inbox/{id}/follow	Take over from AI, hand back to AI, snooze, merge duplicate threads, follow conversations.
AI assistance	POST .../inbox/{id}/suggest-replies, POST .../inbox/{id}/messages/{messageSimplyId}/translate, POST .../inbox/{id}/translate-outgoing	Suggested replies and message translation.
Widgets	GET / POST /v1/conversations/widgets, GET / PUT / DELETE .../widgets/{widgetSimplyId}, POST .../widgets/{widgetSimplyId}/tokens, POST .../widgets/{widgetSimplyId}/simulate	Conversation widget configuration, embed tokens, and no-persist test messages. See Embedding DataViews, Wizards & the Conversation Widget.
Routing & staffing	/v1/conversations/assignment-rules (+ /reorder), /v1/conversations/sla-policies, /v1/conversations/canned-responses (+ /{id}/use), GET /v1/conversations/assignable-team-users, GET / PUT /v1/conversations/presence	Assignment rules, SLA policies, canned responses, and agent presence.
Analytics	GET /v1/conversations/analytics, GET /v1/conversations/analytics/content-gaps	Conversation volume/response metrics and unanswered or low-grounding AI turns.

Usage Notes

• Conversations are created automatically when a constituent starts a chat through the conversation widget or replies through a tracked channel; the API create endpoint is for programmatic or imported threads.
• Inbox detail and related-conversation summaries preserve assignment scope: users with DATA_CONVERSATION_INBOX_VIEW can read only their own and unassigned conversations, while DATA_CONVERSATION_INBOX_VIEW_ALL grants team-wide visibility.
• To list the conversations linked to one constituent record, use GET /v1/data-records/{dataRecordSimplyId}/conversations — see API Reference: Data Records.
• Internal notes (channel: "INTERNAL_NOTE") are never delivered to the constituent — they are recorded for your team only.
• One-to-many campaign email/SMS is a different surface: see API Reference: Messages.