Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway.

Chat & Messaging API

Real-time messaging system for team communication with channels, threads, and presence.

Overview

Attribute	Value
Base Path	`/api/v1/chat`
Authentication	Bearer Token
Required Roles	`pos_staff`, `server`, `restaurant_staff`, `kitchen`, `host`, `bartender`, `cashier`, `drive_thru_staff`, `manager`, `restaurant_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`
Real-time	WebSocket at `wss://api.olympuscloud.ai/ws/chat`

Channel Endpoints

List Channels

Retrieve channels the user has access to.

GET /api/v1/chat/channels

Query Parameters

Parameter	Type	Description
`type`	string	`public`, `private`, `dm`, `incident`
`location_id`	uuid	Filter by location
`archived`	boolean	Include archived channels

Response

{
  "data": [
    {
      "id": "ch_general",
      "name": "general",
      "display_name": "General",
      "type": "public",
      "description": "General team discussion",
      "member_count": 45,
      "unread_count": 3,
      "last_message_at": "2026-01-24T18:30:00Z",
      "is_muted": false
    },
    {
      "id": "ch_kitchen",
      "name": "kitchen",
      "display_name": "Kitchen Team",
      "type": "private",
      "member_count": 12,
      "unread_count": 0
    }
  ]
}

Channel Types

Type	Description
`public`	Open to all workspace members
`private`	Invite-only channel
`dm`	Direct message (2 people)
`group_dm`	Group direct message
`incident`	Auto-created for incidents
`support`	Customer support thread

Create Channel

Create a new channel.

POST /api/v1/chat/channels

Request Body

{
  "name": "morning-shift",
  "display_name": "Morning Shift",
  "type": "private",
  "description": "Coordination for morning shift team",
  "location_id": "loc_123",
  "member_ids": ["user_001", "user_002", "user_003"]
}

Get Channel

Retrieve channel details.

GET /api/v1/chat/channels/{channel_id}

Response

{
  "id": "ch_kitchen",
  "name": "kitchen",
  "display_name": "Kitchen Team",
  "type": "private",
  "description": "Back of house communication",
  "created_by": "user_abc",
  "created_at": "2025-06-01T00:00:00Z",
  "member_count": 12,
  "members": [
    {"id": "user_001", "name": "Chef Mike", "role": "admin"},
    {"id": "user_002", "name": "Sous Chef Ana", "role": "member"}
  ],
  "settings": {
    "who_can_post": "all_members",
    "message_retention_days": 365
  }
}

Message Endpoints

List Messages

Retrieve messages from a channel.

GET /api/v1/chat/channels/{channel_id}/messages

Query Parameters

Parameter	Type	Description
`before`	string	Message ID for pagination
`after`	string	Messages after this ID
`limit`	integer	Results per page (max 100)
`thread_id`	string	Get thread replies only

Response

{
  "data": [
    {
      "id": "msg_001",
      "channel_id": "ch_kitchen",
      "user": {
        "id": "user_001",
        "name": "Chef Mike",
        "avatar_url": "https://..."
      },
      "content": "Prep list for today is posted on the board",
      "type": "text",
      "thread_id": null,
      "reply_count": 2,
      "reactions": [
        {"emoji": "👍", "count": 3}
      ],
      "attachments": [],
      "created_at": "2026-01-24T08:00:00Z",
      "edited_at": null
    }
  ],
  "has_more": true
}

Send Message

Post a message to a channel.

POST /api/v1/chat/channels/{channel_id}/messages

Request Body

{
  "content": "86'd the salmon - we're out until tomorrow",
  "thread_id": null,
  "attachments": [],
  "mentions": ["user_002", "user_003"]
}

Message Types

Type	Description
`text`	Plain text message
`image`	Image attachment
`file`	File attachment
`voice`	Voice message
`system`	System notification

Reply to Thread

Reply to an existing message thread.

POST /api/v1/chat/channels/{channel_id}/messages

Request Body

{
  "content": "Got it, updating the menu board now",
  "thread_id": "msg_001"
}

Edit Message

Edit a message you sent.

PUT /api/v1/chat/channels/{channel_id}/messages/{message_id}

Request Body

{
  "content": "86'd the salmon and halibut - both out until tomorrow"
}

Delete Message

Delete a message.

DELETE /api/v1/chat/channels/{channel_id}/messages/{message_id}

Add Reaction

React to a message.

POST /api/v1/chat/channels/{channel_id}/messages/{message_id}/reactions

Request Body

{
  "emoji": "👍"
}

Presence

Get Presence

Get online status of users.

GET /api/v1/chat/presence

Query Parameters

Parameter	Type	Description
`user_ids`	string[]	Specific users to check
`channel_id`	string	Get presence for channel members

Response

{
  "data": [
    {
      "user_id": "user_001",
      "status": "online",
      "last_seen": null,
      "status_text": "In kitchen",
      "status_emoji": "👨‍🍳"
    },
    {
      "user_id": "user_002",
      "status": "away",
      "last_seen": "2026-01-24T17:45:00Z"
    }
  ]
}

Status Values

Status	Description
`online`	Currently active
`away`	Idle/away
`dnd`	Do not disturb
`offline`	Not connected

Update Presence

Set your status.

PUT /api/v1/chat/presence

Request Body

{
  "status": "dnd",
  "status_text": "On break",
  "status_emoji": "☕",
  "clear_after_minutes": 30
}

Direct Messages

Create DM

Start a direct message conversation.

POST /api/v1/chat/dm

Request Body

{
  "user_id": "user_002"
}

Response

{
  "channel_id": "dm_user001_user002",
  "type": "dm",
  "user": {
    "id": "user_002",
    "name": "Sous Chef Ana"
  }
}

Read Receipts

Mark as Read

Mark messages as read.

POST /api/v1/chat/channels/{channel_id}/read

Request Body

{
  "last_read_message_id": "msg_005"
}

Search

Search Messages

Search across messages.

GET /api/v1/chat/search

Query Parameters

Parameter	Type	Description
`q`	string	Search query
`channel_id`	string	Limit to channel
`from_user_id`	string	Filter by sender
`after`	datetime	After this date
`before`	datetime	Before this date

Response

{
  "data": [
    {
      "message": {
        "id": "msg_001",
        "content": "86'd the salmon...",
        "channel_id": "ch_kitchen"
      },
      "highlights": ["86'd the <em>salmon</em>"]
    }
  ],
  "total": 15
}

WebSocket Events

Connect to wss://api.olympuscloud.ai/ws/chat for real-time events.

Events Received

Event	Description
`message.new`	New message in subscribed channel
`message.edited`	Message was edited
`message.deleted`	Message was deleted
`reaction.added`	Reaction added to message
`presence.updated`	User presence changed
`typing.start`	User started typing
`typing.stop`	User stopped typing
`channel.updated`	Channel settings changed

Error Responses

Status	Code	Description
400	`message_too_long`	Message exceeds 4000 chars
403	`not_channel_member`	Not a member of channel
403	`cannot_edit`	Cannot edit others' messages
404	`channel_not_found`	Channel does not exist
429	`rate_limited`	Too many messages

Olympus Chat Guide - Full platform guide
Staff Chat Guide - User guide
WebSocket Events - Real-time events

Overview​

Channel Endpoints​

List Channels​

Channel Types​

Create Channel​

Get Channel​

Message Endpoints​

List Messages​

Send Message​

Message Types​

Reply to Thread​

Edit Message​

Delete Message​

Add Reaction​

Presence​

Get Presence​

Status Values​

Update Presence​

Direct Messages​

Create DM​

Read Receipts​

Mark as Read​

Search​

Search Messages​

WebSocket Events​

Events Received​

Error Responses​

Related Documentation​

Overview

Channel Endpoints

List Channels

Channel Types

Create Channel

Get Channel

Message Endpoints

List Messages

Send Message

Message Types

Reply to Thread

Edit Message

Delete Message

Add Reaction

Presence

Get Presence

Status Values

Update Presence

Direct Messages

Create DM

Read Receipts

Mark as Read

Search

Search Messages

WebSocket Events

Events Received

Error Responses

Related Documentation