{
  "openapi": "3.1.0",
  "info": {
    "title": "Thikaa API",
    "description": "Official API for Thikaa - #1 AI & LLM Chatbot Platform in MENA. Automate customer conversations across WhatsApp, TikTok, Facebook, Instagram, and Telegram.",
    "version": "1.0.0",
    "contact": {
      "name": "Thikaa Support",
      "email": "support@thikaa.com",
      "url": "https://thikaa.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://thikaa.com/terms"
    },
    "x-logo": {
      "url": "https://thikaa.com/assets/img/main-logo.png"
    }
  },
  "servers": [
    {
      "url": "https://thikaa.com/api/v1",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "Messages",
      "description": "Send and receive messages across channels"
    },
    {
      "name": "Conversations",
      "description": "Manage customer conversations"
    },
    {
      "name": "Leads",
      "description": "Lead capture and management"
    },
    {
      "name": "Appointments",
      "description": "Booking and scheduling"
    },
    {
      "name": "Bots",
      "description": "Chatbot management"
    },
    {
      "name": "Webhooks",
      "description": "Webhook configuration"
    }
  ],
  "paths": {
    "/messages/send": {
      "post": {
        "tags": ["Messages"],
        "summary": "Send a message",
        "description": "Send a message to a customer on any connected channel (WhatsApp, Facebook, Instagram, Telegram, TikTok)",
        "operationId": "sendMessage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/conversations": {
      "get": {
        "tags": ["Conversations"],
        "summary": "List conversations",
        "description": "Get all conversations with pagination and filtering",
        "operationId": "listConversations",
        "parameters": [
          {
            "name": "channel",
            "in": "query",
            "description": "Filter by channel",
            "schema": {
              "type": "string",
              "enum": ["whatsapp", "facebook", "instagram", "telegram", "tiktok", "email", "web"]
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string",
              "enum": ["open", "closed", "pending"]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationList"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/conversations/{id}": {
      "get": {
        "tags": ["Conversations"],
        "summary": "Get conversation",
        "description": "Get a single conversation with all messages",
        "operationId": "getConversation",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            }
          },
          "404": {
            "description": "Conversation not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/leads": {
      "get": {
        "tags": ["Leads"],
        "summary": "List leads",
        "description": "Get all captured leads",
        "operationId": "listLeads",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of leads",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadList"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      },
      "post": {
        "tags": ["Leads"],
        "summary": "Create lead",
        "description": "Create a new lead manually",
        "operationId": "createLead",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLeadRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lead"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/appointments": {
      "get": {
        "tags": ["Appointments"],
        "summary": "List appointments",
        "description": "Get all appointments with optional date filtering",
        "operationId": "listAppointments",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start date (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End date (ISO 8601)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["pending", "confirmed", "cancelled", "completed"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of appointments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppointmentList"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      },
      "post": {
        "tags": ["Appointments"],
        "summary": "Create appointment",
        "description": "Book a new appointment",
        "operationId": "createAppointment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAppointmentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Appointment created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Appointment"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/appointments/{id}": {
      "patch": {
        "tags": ["Appointments"],
        "summary": "Update appointment",
        "description": "Update an existing appointment",
        "operationId": "updateAppointment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAppointmentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Appointment updated"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      },
      "delete": {
        "tags": ["Appointments"],
        "summary": "Cancel appointment",
        "description": "Cancel an appointment",
        "operationId": "cancelAppointment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Appointment cancelled"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/bots": {
      "get": {
        "tags": ["Bots"],
        "summary": "List bots",
        "description": "Get all chatbots in the account",
        "operationId": "listBots",
        "responses": {
          "200": {
            "description": "List of bots",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BotList"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/bots/{id}/toggle": {
      "post": {
        "tags": ["Bots"],
        "summary": "Toggle bot",
        "description": "Enable or disable a chatbot",
        "operationId": "toggleBot",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bot status updated"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/webhooks": {
      "get": {
        "tags": ["Webhooks"],
        "summary": "List webhooks",
        "description": "Get configured webhook endpoints",
        "operationId": "listWebhooks",
        "responses": {
          "200": {
            "description": "List of webhooks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookList"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      },
      "post": {
        "tags": ["Webhooks"],
        "summary": "Create webhook",
        "description": "Register a new webhook endpoint",
        "operationId": "createWebhook",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ]
      }
    },
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Health check",
        "description": "Check API health status",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key from your Thikaa dashboard"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "SendMessageRequest": {
        "type": "object",
        "required": ["channel", "to", "message"],
        "properties": {
          "channel": {
            "type": "string",
            "enum": ["whatsapp", "facebook", "instagram", "telegram", "tiktok"],
            "description": "Messaging channel"
          },
          "to": {
            "type": "string",
            "description": "Recipient identifier (phone number, user ID)"
          },
          "message": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["text", "image", "document", "template"],
                "default": "text"
              },
              "text": {
                "type": "string",
                "description": "Message text content"
              },
              "media_url": {
                "type": "string",
                "format": "uri",
                "description": "URL for media messages"
              },
              "template": {
                "type": "object",
                "description": "Template details for WhatsApp templates"
              }
            }
          }
        }
      },
      "MessageResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["sent", "delivered", "read", "failed"]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "channel": {
            "type": "string"
          },
          "contact": {
            "$ref": "#/components/schemas/Contact"
          },
          "status": {
            "type": "string",
            "enum": ["open", "closed", "pending"]
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ConversationList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Conversation"
            }
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "avatar": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": ["inbound", "outbound"]
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Lead": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "LeadList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Lead"
            }
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "CreateLeadRequest": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "Appointment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "customer_name": {
            "type": "string"
          },
          "customer_phone": {
            "type": "string"
          },
          "customer_email": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "format": "time"
          },
          "duration_minutes": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "confirmed", "cancelled", "completed"]
          },
          "notes": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AppointmentList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Appointment"
            }
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "CreateAppointmentRequest": {
        "type": "object",
        "required": ["customer_name", "date", "time"],
        "properties": {
          "customer_name": {
            "type": "string"
          },
          "customer_phone": {
            "type": "string"
          },
          "customer_email": {
            "type": "string",
            "format": "email"
          },
          "service": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "format": "time"
          },
          "duration_minutes": {
            "type": "integer",
            "default": 30
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "UpdateAppointmentRequest": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "format": "time"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "confirmed", "cancelled", "completed"]
          },
          "notes": {
            "type": "string"
          }
        }
      },
      "Bot": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "channels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BotList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Bot"
            }
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "active": {
            "type": "boolean"
          }
        }
      },
      "WebhookList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Webhook"
            }
          }
        }
      },
      "CreateWebhookRequest": {
        "type": "object",
        "required": ["url", "events"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "conversation.started",
                "conversation.ended",
                "message.received",
                "message.sent",
                "lead.captured",
                "appointment.booked",
                "appointment.cancelled"
              ]
            }
          },
          "secret": {
            "type": "string",
            "description": "Secret for webhook signature verification"
          }
        }
      }
    }
  },
  "x-webhooks": {
    "message.received": {
      "post": {
        "summary": "Message received",
        "description": "Triggered when a new message is received from a customer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "example": "message.received"
                  },
                  "data": {
                    "$ref": "#/components/schemas/Message"
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      }
    },
    "lead.captured": {
      "post": {
        "summary": "Lead captured",
        "description": "Triggered when a new lead is captured via chatbot",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "example": "lead.captured"
                  },
                  "data": {
                    "$ref": "#/components/schemas/Lead"
                  },
                  "timestamp": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}