Authenticated API

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

Support API

Customer support operations including ticketing, live chat, escalation, and help desk management.

Overview

Attribute	Value
Base Path	`/api/v1/support`
Authentication	Bearer Token
Required Roles	`pos_staff`, `server`, `manager`, `restaurant_manager`, `restaurant_staff`, `kitchen`, `host`, `bartender`, `cashier`, `drive_thru_staff`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Support Sessions

Start Session

Initiate a support chat session.

POST /api/v1/support/sessions

Request Body

{
  "customer_id": "cust_abc",
  "channel": "chat",
  "initial_message": "I need help with my order",
  "context": {
    "order_id": "ord_xyz",
    "page": "order_tracking"
  },
  "priority": "normal"
}

Response

{
  "session_id": "sess_001",
  "status": "active",
  "channel": "chat",
  "customer": {
    "id": "cust_abc",
    "name": "John Doe",
    "email": "john@example.com"
  },
  "assigned_agent": {
    "id": "agent_001",
    "name": "Support Agent Sarah",
    "avatar_url": "https://..."
  },
  "queue_position": 0,
  "estimated_wait_minutes": 0,
  "websocket_url": "wss://support.olympuscloud.ai/ws/sess_001",
  "created_at": "2026-01-24T19:30:00Z"
}

Get Session

GET /api/v1/support/sessions/{session_id}

Response

{
  "session_id": "sess_001",
  "status": "active",
  "channel": "chat",
  "customer": {...},
  "assigned_agent": {...},
  "messages": [
    {
      "id": "msg_001",
      "sender": "customer",
      "content": "I need help with my order",
      "timestamp": "2026-01-24T19:30:00Z"
    },
    {
      "id": "msg_002",
      "sender": "agent",
      "content": "Hi John! I'd be happy to help. Let me look up your order.",
      "timestamp": "2026-01-24T19:30:30Z"
    }
  ],
  "context": {
    "order_id": "ord_xyz",
    "order_status": "preparing"
  },
  "duration_seconds": 180,
  "created_at": "2026-01-24T19:30:00Z"
}

Session Status Values

Status	Description
`queued`	Waiting for agent
`active`	In progress
`on_hold`	Temporarily on hold
`transferred`	Being transferred
`resolved`	Issue resolved
`closed`	Session ended

Send Message

POST /api/v1/support/sessions/{session_id}/messages

Request Body

{
  "content": "Here's the status of your order...",
  "type": "text",
  "attachments": []
}

Transfer Session

Transfer to another agent or team.

POST /api/v1/support/sessions/{session_id}/transfer

Request Body

{
  "target_type": "team",
  "target_id": "team_billing",
  "reason": "Billing issue - needs specialist",
  "notes": "Customer has a refund question"
}

End Session

POST /api/v1/support/sessions/{session_id}/end

Request Body

{
  "resolution": "resolved",
  "resolution_notes": "Provided order status and ETA",
  "tags": ["order_status", "quick_resolution"]
}

Tickets

List Tickets

GET /api/v1/support/tickets

Query Parameters

Parameter	Type	Description
`status`	string	Ticket status filter
`priority`	string	`low`, `normal`, `high`, `urgent`
`assigned_to`	string	Filter by agent
`customer_id`	string	Filter by customer
`category`	string	Ticket category

Response

{
  "data": [
    {
      "id": "ticket_001",
      "number": "TKT-2026-0042",
      "subject": "Refund request for cancelled order",
      "status": "open",
      "priority": "high",
      "category": "refund",
      "customer": {
        "id": "cust_abc",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "assigned_to": {
        "id": "agent_001",
        "name": "Agent Sarah"
      },
      "created_at": "2026-01-24T15:00:00Z",
      "updated_at": "2026-01-24T18:00:00Z",
      "first_response_at": "2026-01-24T15:30:00Z",
      "sla": {
        "response_due": "2026-01-24T16:00:00Z",
        "resolution_due": "2026-01-25T15:00:00Z",
        "status": "within_sla"
      }
    }
  ]
}

Ticket Status Values

Status	Description
`new`	Newly created
`open`	Being worked on
`pending`	Awaiting customer
`on_hold`	Temporarily paused
`solved`	Resolution provided
`closed`	Ticket closed

Create Ticket

POST /api/v1/support/tickets

Request Body

{
  "subject": "Missing item from order",
  "description": "My order #ORD-123 was missing the side salad",
  "customer_id": "cust_abc",
  "priority": "normal",
  "category": "order_issue",
  "tags": ["missing_item"],
  "related_order_id": "ord_xyz",
  "attachments": []
}

Get Ticket

GET /api/v1/support/tickets/{ticket_id}

Response

{
  "id": "ticket_001",
  "number": "TKT-2026-0042",
  "subject": "Refund request for cancelled order",
  "description": "I cancelled my order but haven't received the refund yet...",
  "status": "open",
  "priority": "high",
  "category": "refund",
  "customer": {...},
  "assigned_to": {...},
  "comments": [
    {
      "id": "comment_001",
      "author": {
        "type": "customer",
        "name": "John Doe"
      },
      "content": "How long does a refund take?",
      "public": true,
      "timestamp": "2026-01-24T16:00:00Z"
    },
    {
      "id": "comment_002",
      "author": {
        "type": "agent",
        "name": "Agent Sarah"
      },
      "content": "Refunds typically process within 3-5 business days...",
      "public": true,
      "timestamp": "2026-01-24T16:30:00Z"
    }
  ],
  "activities": [
    {"action": "created", "timestamp": "2026-01-24T15:00:00Z"},
    {"action": "assigned", "agent": "Agent Sarah", "timestamp": "2026-01-24T15:15:00Z"},
    {"action": "replied", "timestamp": "2026-01-24T16:30:00Z"}
  ],
  "related": {
    "order_id": "ord_xyz",
    "session_id": "sess_001"
  }
}

Update Ticket

PUT /api/v1/support/tickets/{ticket_id}

Request Body

{
  "status": "pending",
  "priority": "normal",
  "assigned_to": "agent_002",
  "tags": ["refund", "escalated"]
}

Add Comment

POST /api/v1/support/tickets/{ticket_id}/comments

Request Body

{
  "content": "I've processed your refund. It should appear in 3-5 business days.",
  "public": true,
  "attachments": []
}

Add Internal Note

POST /api/v1/support/tickets/{ticket_id}/notes

Request Body

{
  "content": "Customer has been patient. Expedite refund if possible.",
  "mention_agent_ids": ["agent_002"]
}

Quick Actions

List Quick Actions

Get available quick actions.

GET /api/v1/support/quick-actions

Response

{
  "actions": [
    {
      "id": "action_refund",
      "name": "Process Refund",
      "description": "Initiate refund for an order",
      "required_context": ["order_id"],
      "permissions": ["refund:write"]
    },
    {
      "id": "action_resend_order",
      "name": "Resend Order",
      "description": "Resend confirmation email",
      "required_context": ["order_id"]
    },
    {
      "id": "action_add_credit",
      "name": "Add Store Credit",
      "description": "Add credit to customer account",
      "required_context": ["customer_id", "amount"]
    }
  ]
}

Execute Quick Action

POST /api/v1/support/quick-actions/{action_id}/execute

Request Body

{
  "session_id": "sess_001",
  "context": {
    "order_id": "ord_xyz",
    "refund_amount": 25.99,
    "reason": "missing_item"
  }
}

Response

{
  "success": true,
  "result": {
    "refund_id": "ref_001",
    "amount": 25.99,
    "status": "processing"
  },
  "message": "Refund of $25.99 initiated successfully"
}

Escalation

Escalate Session

POST /api/v1/support/sessions/{session_id}/escalate

Request Body

{
  "level": "supervisor",
  "reason": "Customer requesting manager",
  "urgency": "high"
}

Escalate Ticket

POST /api/v1/support/tickets/{ticket_id}/escalate

Request Body

{
  "escalation_type": "tier_2",
  "reason": "Technical issue beyond tier 1 scope",
  "notes": "Customer experiencing repeated payment failures"
}

Knowledge Base

Search Knowledge Base

GET /api/v1/support/kb/search

Query Parameters

Parameter	Type	Description
`q`	string	Search query
`category`	string	Filter by category
`limit`	integer	Number of results

Response

{
  "results": [
    {
      "id": "article_001",
      "title": "How to request a refund",
      "excerpt": "To request a refund, follow these steps...",
      "category": "refunds",
      "relevance_score": 0.95,
      "url": "https://help.example.com/articles/refunds"
    }
  ],
  "suggested_response": "Based on your question, here's how to process a refund..."
}

Get Suggested Articles

POST /api/v1/support/kb/suggest

Request Body

{
  "session_id": "sess_001",
  "message": "Customer asking about refund timeline"
}

Agent Management

Get Agent Status

GET /api/v1/support/agents/{agent_id}/status

Response

{
  "agent_id": "agent_001",
  "name": "Sarah Smith",
  "status": "available",
  "active_sessions": 3,
  "max_sessions": 5,
  "skills": ["billing", "technical", "orders"],
  "languages": ["en", "es"],
  "metrics_today": {
    "sessions_handled": 25,
    "avg_response_time_seconds": 45,
    "satisfaction_score": 4.8,
    "resolution_rate": 92
  }
}

Agent Status Values

Status	Description
`available`	Ready for sessions
`busy`	At capacity
`away`	Temporarily away
`offline`	Not available

Update Agent Status

PUT /api/v1/support/agents/{agent_id}/status

Request Body

{
  "status": "away",
  "reason": "lunch_break",
  "return_time": "2026-01-24T13:00:00Z"
}

Analytics

Get Support Metrics

GET /api/v1/support/analytics

Query Parameters

Parameter	Type	Description
`start_date`	date	Period start
`end_date`	date	Period end
`group_by`	string	`hour`, `day`, `week`

Response

{
  "period": {
    "start": "2026-01-24",
    "end": "2026-01-24"
  },
  "summary": {
    "total_sessions": 150,
    "total_tickets": 45,
    "avg_response_time_seconds": 38,
    "avg_resolution_time_minutes": 12,
    "satisfaction_score": 4.6,
    "first_contact_resolution": 78
  },
  "by_channel": [
    {"channel": "chat", "sessions": 120, "satisfaction": 4.7},
    {"channel": "email", "sessions": 25, "satisfaction": 4.4},
    {"channel": "phone", "sessions": 5, "satisfaction": 4.5}
  ],
  "by_category": [
    {"category": "order_status", "count": 45, "avg_resolution_min": 5},
    {"category": "refund", "count": 25, "avg_resolution_min": 15},
    {"category": "technical", "count": 15, "avg_resolution_min": 25}
  ],
  "sla_compliance": {
    "response_sla_met": 95,
    "resolution_sla_met": 88
  }
}

Webhooks

Event	Description
`support.session_started`	New chat session
`support.session_ended`	Session closed
`support.ticket_created`	New ticket
`support.ticket_updated`	Ticket modified
`support.escalation`	Session/ticket escalated
`support.sla_breach`	SLA threshold exceeded

Error Responses

Status	Code	Description
400	`no_agents_available`	No agents online
404	`session_not_found`	Session ID not found
404	`ticket_not_found`	Ticket ID not found
409	`session_closed`	Session already ended

AI Support Widget - AI support configuration
Premium Support - Premium support tiers
Knowledge Base - KB management

Overview​

Support Sessions​

Start Session​

Get Session​

Session Status Values​

Send Message​

Transfer Session​

End Session​

Tickets​

List Tickets​

Ticket Status Values​

Create Ticket​

Get Ticket​

Update Ticket​

Add Comment​

Add Internal Note​

Quick Actions​

List Quick Actions​

Execute Quick Action​

Escalation​

Escalate Session​

Escalate Ticket​

Knowledge Base​

Search Knowledge Base​

Get Suggested Articles​

Agent Management​

Get Agent Status​

Agent Status Values​

Update Agent Status​

Analytics​

Get Support Metrics​

Webhooks​

Error Responses​

Related Documentation​

Overview

Support Sessions

Start Session

Get Session

Session Status Values

Send Message

Transfer Session

End Session

Tickets

List Tickets

Ticket Status Values

Create Ticket

Get Ticket

Update Ticket

Add Comment

Add Internal Note

Quick Actions

List Quick Actions

Execute Quick Action

Escalation

Escalate Session

Escalate Ticket

Knowledge Base

Search Knowledge Base

Get Suggested Articles

Agent Management

Get Agent Status

Agent Status Values

Update Agent Status

Analytics

Get Support Metrics

Webhooks

Error Responses

Related Documentation