REST API

Jack provides a REST API for managing conversations, guests, tasks, and more. All endpoints use JSON.

Base URL

https://your-jack-domain.com/api/v1

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Conversation not found"
  }
}

Conversations

List conversations

GET /conversations
GET /conversations?status=open&channel=whatsapp&limit=20

Query parameters:

• status — open, closed, pending
• channel — whatsapp, sms, email, web
• assignee — Staff ID or "unassigned"
• limit — Results per page (default: 20)
• page — Page number

Get conversation

GET /conversations/:id

Get messages

GET /conversations/:id/messages

Send message

POST /conversations/:id/messages
{
  "content": "Hello! How can I help you today?",
  "type": "text"
}

Update conversation

PATCH /conversations/:id
{
  "status": "closed",
  "assignee": "staff-123"
}

Guests

List guests

GET /guests
GET /guests?search=john&tag=vip

Get guest

GET /guests/:id

Create guest

POST /guests
{
  "name": "John Smith",
  "email": "[email protected]",
  "phone": "+15551234567"
}

Update guest

PATCH /guests/:id
{
  "tags": ["vip", "returning"],
  "notes": "Prefers quiet room"
}

Tasks

List tasks

GET /tasks
GET /tasks?status=open&priority=urgent&department=housekeeping

Get task

GET /tasks/:id

Create task

POST /tasks
{
  "title": "Extra towels for room 302",
  "description": "Guest requested 2 extra bath towels",
  "department": "housekeeping",
  "priority": "normal",
  "guestId": "guest-123"
}

Update task

PATCH /tasks/:id
{
  "status": "completed",
  "notes": "Delivered at 3:45 PM"
}

Knowledge Base

List entries

GET /knowledge
GET /knowledge?category=policy

Get entry

GET /knowledge/:id

Create entry

POST /knowledge
{
  "title": "Pool Hours",
  "content": "The pool is open daily from 6 AM to 10 PM...",
  "category": "amenity"
}

Update entry

PUT /knowledge/:id
{
  "title": "Pool Hours (Updated)",
  "content": "The pool is open daily from 7 AM to 9 PM..."
}

Delete entry

DELETE /knowledge/:id

Staff

List staff

GET /staff

Get staff member

GET /staff/:id

Create staff (Admin only)

POST /staff
{
  "name": "Jane Doe",
  "email": "[email protected]",
  "role": "staff",
  "department": "front-desk"
}

Settings

Get settings

GET /settings/:key

Update settings (Admin only)

PUT /settings/:key
{
  "value": { ... }
}

Pagination

List endpoints support pagination:

GET /conversations?page=2&limit=50

Response includes metadata:

{
  "success": true,
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 50,
    "total": 150,
    "pages": 3
  }
}

Rate Limits

API requests are rate-limited:

• Standard: 100 requests per minute
• Bulk operations: 10 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200

Error Codes