API Documentation

Introduction

General information about Timo API

Base URLs

The Timo API is available in both sandbox and production environments for testing and production use.

💡 Environments:
Production
http://api.lavaka.io/api/
Development
http://localhost:8000/api/

Authentication

To authenticate API requests, include your API key in the Authorization header. You receive your API key during onboarding.

Authorization: Bearer ${apiKey}

To obtain a JWT token, make a POST request to the token endpoint:

curl -X POST http://api.lavaka.io/api/auth/token \ -H "Content-Type: application/json" \ -d '{"username": "your-username", "password": "your-password"}'

Endpoints Overview

The Timo API relies on three main concepts: Hotels, Service Requests, and WhatsApp Messages. This section outlines the workflow for generating a direct debit payment.

Hotels

Hotels represent the properties managed in the system. Each hotel has departments, staff, and service categories.

Service Requests

Service requests are created when guests request services through WhatsApp. Each request is routed to the appropriate department.

WhatsApp Integration

WhatsApp messages are received via webhook and processed by the AI orchestrator to create service requests.

System

System Status

Real-time system health and status information

Loading status...
Getting Started

Quick Start Guide

Get up and running with Timo API quickly

Local Development (Fastest - SQLite)

# Terminal 1 - Backend cd backend python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt # Create .env file cat > .env << EOF DB_SQLITE=true DJANGO_DEBUG=true DJANGO_SECRET_KEY=dev-secret-key-change-me WHATSAPP_VERIFY_TOKEN=change-me USE_REDIS=false EOF # Run migrations and start server python manage.py migrate python manage.py runserver 8000
# Terminal 2 - Frontend cd frontend npm install npm run dev

Access:

  • Frontend: http://localhost:3069
  • Backend API: http://localhost:8000
  • Admin Panel: http://localhost:8000/admin

Docker Setup (PostgreSQL + Redis)

cd infrastructure docker compose up -d

This starts PostgreSQL, Redis, Django backend, Celery worker, and Celery beat.

First Time Setup

  1. Create superuser: python manage.py createsuperuser
  2. Create a Hotel in admin panel
  3. Create a Department for that hotel
  4. Create ServiceCategory and ServiceItem

Test API Connection

# Health check curl http://localhost:8000/api/health # Get JWT token curl -X POST http://localhost:8000/api/auth/token \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "your-password"}'
Configuration

Environment Variables

Required and optional environment configuration

Required (Development)

DB_SQLITE=true # Use SQLite for local dev DJANGO_DEBUG=true # Enable debug mode DJANGO_SECRET_KEY=your-secret-key # Django secret key WHATSAPP_VERIFY_TOKEN=change-me # WhatsApp webhook verification USE_REDIS=false # Disable Redis (uses dummy cache)

Database (Production)

POSTGRES_DB=timo POSTGRES_USER=timo POSTGRES_PASSWORD=your-password POSTGRES_HOST=localhost POSTGRES_PORT=5432

Redis (Optional)

USE_REDIS=true REDIS_URL=redis://localhost:6379/1 CELERY_BROKER_URL=redis://localhost:6379/3 CELERY_RESULT_BACKEND=redis://localhost:6379/3

CORS

CORS_ALLOW_ALL_ORIGINS=false CORS_ALLOWED_ORIGINS=https://chat.lavaka.io

WhatsApp (Twilio)

WHATSAPP_PROVIDER=twilio TWILIO_ACCOUNT_SID=your-account-sid TWILIO_AUTH_TOKEN=your-auth-token TWILIO_WHATSAPP_NUMBER=whatsapp:+14155238886

OpenAI

OPENAI_API_KEY=sk-proj-your-key OPENAI_MODEL=gpt-4o-mini OPENAI_EMBEDDING_MODEL=text-embedding-3-small
Deployment

Deployment Guide

Deploy Timo API to production

Production URLs

  • Public API: https://api.lavaka.io
  • Webhook URL: https://api.lavaka.io/api/whatsapp/webhook
  • Health Check: https://api.lavaka.io/api/health

VPS Setup (Quick)

cd /home/wiz/timo ./INITIALIZE_VPS.sh

This script sets up PostgreSQL, Redis, nginx, SSL, and systemd services.

Development vs Production Toggle

# Switch to dev mode ~/toggle-backend.sh dev sudo systemctl start timo-dev # Switch back to production sudo systemctl stop timo-dev ~/toggle-backend.sh prod

Dokploy Deployment

  1. Set build path to /backend
  2. Use Dockerfile build type
  3. Configure environment variables (see Environment tab)
  4. Set domain: api.lavaka.io
  5. Health check path: /api/health

Verification

# Check status ~/toggle-backend.sh status # Test endpoints curl https://api.lavaka.io/api/health curl http://localhost:8000/api/health # Dev curl http://localhost:8001/api/health # Prod
API Documentation

Client Onboarding

Streamlined process for onboarding new hotel clients

Overview

The client onboarding system provides a complete solution for setting up new hotel clients. It automatically creates:

  • Hotel record with unique code and locale settings
  • Admin user account with secure password
  • Default departments (Housekeeping, Maintenance, Room Service, Front Desk, Concierge)
  • Welcome email with login credentials
💡 Access: This endpoint is only accessible to super_admin and dev users.

Web-Based Onboarding Form

The easiest way to onboard clients is through the web interface:

  1. Log in as super_admin or dev user
  2. Navigate to Super Admin → Onboard Client (or go to /onboard-client)
  3. Fill out the form with client information
  4. Submit - the system handles everything automatically

Form Fields

Hotel Information

  • Hotel Name (required) - Full name of the hotel
  • Hotel Code (optional) - Auto-generated from hotel name if blank
  • Default Locale - Language preference (en, es, fr, de)

Admin User Information

  • Admin Email (required) - Email for login and notifications
  • Admin Username (optional) - Auto-generated as {hotel_code}_admin
  • First Name / Last Name (optional) - Admin user's name
  • Password (optional) - Auto-generated secure password if enabled

Options

  • Generate Password - Auto-generate secure 16-character password
  • Create Default Departments - Pre-create standard departments
  • Send Email - Send welcome email with credentials

API Endpoint

You can also onboard clients programmatically via the API:

POST http://api.lavaka.io/api/hotels/onboard-client/ 🔒 Auth Required

Onboard a new client - creates hotel + admin user + sends email

Request Example

curl -X POST http://api.lavaka.io/api/hotels/onboard-client/ \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "hotel_name": "Grand Plaza Hotel", "admin_email": "admin@grandplaza.com", "generate_password": true, "create_default_departments": true, "send_email": true }'

Request Body

{ "hotel_name": "Grand Plaza Hotel", // Required "hotel_code": "grand_plaza_hotel", // Optional (auto-generated) "default_locale": "en", // Optional (default: "en") "admin_email": "admin@grandplaza.com", // Required "admin_username": "grand_plaza_admin", // Optional (auto-generated) "admin_first_name": "John", // Optional "admin_last_name": "Smith", // Optional "admin_password": "CustomPass123!", // Optional (if generate_password=false) "generate_password": true, // Optional (default: true) "create_default_departments": true, // Optional (default: true) "send_email": true // Optional (default: true) }

Success Response (201)

{ "success": true, "message": "Client onboarded successfully", "hotel": { "id": 1, "name": "Grand Plaza Hotel", "code": "grand_plaza_hotel" }, "admin_user": { "id": 1, "username": "grand_plaza_hotel_admin", "email": "admin@grandplaza.com" }, "email_sent": true, "password": "Xy9#mK2$pL8@nQ4" // Only shown if email wasn't sent }

Error Response (400)

{ "success": false, "errors": { "hotel_code": ["Hotel with code 'grand_plaza_hotel' already exists."], "admin_email": ["A user with this email already exists."] } }

Step-by-Step Process

Step 1: Prepare Client Information

Gather the following information from your client:

  • Hotel name (e.g., "Grand Plaza Hotel")
  • Admin contact email
  • Admin name (optional)
  • Preferred locale/language

Step 2: Onboard Client

Use either the web form or API to create the client account:

# Via Web UI 1. Go to Super Admin → Onboard Client 2. Fill out the form 3. Click "Onboard Client" # Via API POST /api/hotels/onboard-client/ { "hotel_name": "Grand Plaza Hotel", "admin_email": "admin@grandplaza.com" }

Step 3: Share Credentials

After successful onboarding:

  • If email was sent: Client receives welcome email with credentials
  • If email failed: Share the password securely from the response
  • Provide login URL: http:/.lavaka.io/signin

Step 4: Client First Login

The client should:

  1. Log in with provided credentials
  2. Change password immediately
  3. Complete the Setup Wizard to configure their hotel
  4. Create additional staff users as needed

Auto-Generation Rules

Hotel Code

If not provided, hotel code is auto-generated from hotel name:

"Grand Plaza Hotel" → "grand_plaza_hotel" "Sunset Resort & Spa" → "sunset_resort_spa" "Hotel 123" → "hotel_123"

Admin Username

If not provided, username is auto-generated:

Hotel Code: "grand_plaza_hotel" Admin Username: "grand_plaza_hotel_admin"

Password

If generate_password=true, a secure 16-character password is generated:

  • Contains uppercase, lowercase, numbers, and special characters
  • Example: Xy9#mK2$pL8@nQ4
  • Only shown once in response and email

Default Departments

If create_default_departments=true, the following departments are automatically created:

  • Housekeeping
  • Maintenance
  • Room Service
  • Front Desk
  • Concierge

These can be customized or additional departments can be added later via the Setup Wizard or API.

Email Notifications

When send_email=true, a welcome email is sent to the admin user with:

  • Hotel information
  • Account credentials (username and temporary password)
  • Login URL
  • Next steps instructions

Email Configuration

For production, configure email settings in your .env file:

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend EMAIL_HOST=smtp.gmail.com EMAIL_PORT=587 EMAIL_USE_TLS=true EMAIL_HOST_USER=your-email@example.com EMAIL_HOST_PASSWORD=your-app-password DEFAULT_FROM_EMAIL=noreply@timo.dev FRONTEND_URL=https://your-frontend-domain.com
💡 Development: In development mode, emails are sent to the console. Check your Django server logs to see the email content.

Integration with Setup Wizard

After onboarding, clients can complete their hotel configuration:

  1. New hotel appears in the Setup Wizard hotel selection
  2. Super admins see an "Onboard Client" button in the Setup Wizard
  3. Onboarding form redirects to Setup Wizard after completion
  4. Clients can configure departments, staff, service categories, and items

Troubleshooting

Email Not Sending

  • Check email configuration in .env
  • Verify SMTP credentials
  • Check Django logs for email errors
  • In development, emails print to console

Username Already Exists

  • The system validates uniqueness
  • Choose a different username or hotel code
  • Error message will indicate the conflict

Hotel Code Already Exists

  • Hotel codes must be unique
  • Provide a custom hotel code
  • Error message will indicate the conflict

Best Practices

  • Use consistent naming: Follow the {hotel_code}_admin convention for usernames
  • Generate passwords: Always use auto-generated passwords for security
  • Send emails: Enable email notifications to provide credentials securely
  • Create departments: Use default departments to get clients started quickly
  • Document credentials: Keep a secure record of initial credentials
  • Follow up: Ensure clients change passwords and complete setup wizard
API Documentation

API Endpoints

Complete API reference documentation

Authentication

POST http://api.lavaka.io/api/auth/token

Get JWT access and refresh tokens

curl -X POST http://api.lavaka.io/api/auth/token \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "password"}'
POST http://api.lavaka.io/api/auth/refresh

Refresh access token using refresh token

Hotels

POST http://api.lavaka.io/api/hotels/onboard-client/ 🔒 Super Admin

Onboard a new client - creates hotel + admin user + sends email

See Client Onboarding section for detailed documentation.

GET POST http://api.lavaka.io/api/hotels/ 🔒 Auth Required

List all hotels or create a new hotel

GET PUT PATCH DELETE http://api.lavaka.io/api/hotels/{id}/ 🔒 Auth Required

Hotel details, update, or delete

WhatsApp

GET http://api.lavaka.io/api/whatsapp/verify

Webhook verification for WhatsApp

?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE
POST http://api.lavaka.io/api/whatsapp/webhook

Receive WhatsApp messages

Service Requests

GET POST http://api.lavaka.io/api/requests/ 🔒 Auth Required

List or create service requests

Knowledge Base

POST http://api.lavaka.io/api/knowledge/scrape/ 🔒 Auth Required

Scrape hotel website for knowledge base

GET http://api.lavaka.io/api/knowledge/logs/ 🔒 Auth Required

Get scraping logs

System

GET http://api.lavaka.io/api/health

System health check (JSON)

GET http://api.lavaka.io/api/sitemap

Complete API endpoint map

GET http://api.lavaka.io/api/cors-debug

CORS configuration debug