openapi: 3.0.3
info:
  title: Chat Automation API
  description: Complete API documentation for Chat Automation backend services
  version: 1.0.0
  contact:
    name: API Support
    email: support@chatautomation.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:5000/api/v1
    description: Development server
  - url: https://api.chatautomation.com/v1
    description: Production server

# Security Schemes
security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login endpoint

  # Common Schemas
  schemas:
    SuccessResponse:
      type: object
      properties:
        STATUS:
          type: string
          enum: [success]
        MESSAGE:
          type: string
        DATA:
          type: object
        TIMESTAMP:
          type: string
          format: date-time
        CODE:
          type: string
        HTTP_STATUS:
          type: integer

    ErrorResponse:
      type: object
      properties:
        STATUS:
          type: string
          enum: [error]
        MESSAGE:
          type: string
        CODE:
          type: string
        HTTP_STATUS:
          type: integer
        TIMESTAMP:
          type: string
          format: date-time
        DATA:
          type: object

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        user_name:
          type: string
        role:
          type: string
        account_type:
          type: string
        created_at:
          type: string
          format: date-time

    Business:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        industry:
          type: string
        phone:
          type: string
        email:
          type: string
        website:
          type: string
        address:
          type: string
        created_at:
          type: string
          format: date-time

    Campaign:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        message_content:
          type: string
        status:
          type: string
          enum: [draft, running, completed, paused]
        scheduled_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time

    Contact:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        phone:
          type: string
        email:
          type: string
        tags:
          type: array
          items:
            type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time

    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        conversation_id:
          type: string
        contact_id:
          type: string
        message_type:
          type: string
        content:
          type: string
        direction:
          type: string
          enum: [inbound, outbound]
        status:
          type: string
        created_at:
          type: string
          format: date-time

    AIAgent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        agent_type:
          type: string
        ai_provider:
          type: string
        model_name:
          type: string
        system_prompt:
          type: string
        persona:
          type: string
        temperature:
          type: number
        max_tokens:
          type: integer
        is_active:
          type: boolean
        is_default:
          type: boolean
        created_at:
          type: string
          format: date-time

    Team:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        business_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    TeamMember:
      type: object
      properties:
        id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        role:
          type: string
        permissions:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time

# API Paths
paths:
  # Authentication Routes
  /auth/register:
    post:
      tags:
        - Authentication
      summary: Register a new user
      description: Create a new user account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
                - user_name
                - email_address
                - password
                - business_name
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                user_name:
                  type: string
                email_address:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                business_name:
                  type: string
                phone:
                  type: string
                industry:
                  type: string
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login user
      description: Authenticate user and return JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_name
                - password
              properties:
                user_name:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  STATUS:
                    type: string
                    enum: [success]
                  MESSAGE:
                    type: string
                  DATA:
                    type: object
                    properties:
                      token:
                        type: string
                      user:
                        $ref: '#/components/schemas/User'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/change-password:
    post:
      tags:
        - Authentication
      summary: Change user password
      description: Change the authenticated user's password
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - old_password
                - new_password
              properties:
                old_password:
                  type: string
                new_password:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: Password changed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /auth/register-member:
    post:
      tags:
        - Authentication
      summary: Register team member
      description: Register a new team member for existing business
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
                - user_name
                - email_address
                - password
                - business_id
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                user_name:
                  type: string
                email_address:
                  type: string
                  format: email
                password:
                  type: string
                  minLength: 8
                business_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Team member registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Business Routes
  /business:
    post:
      tags:
        - Business
      summary: Create new business
      description: Create a new business account
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - user_id
              properties:
                name:
                  type: string
                description:
                  type: string
                industry:
                  type: string
                phone:
                  type: string
                email:
                  type: string
                  format: email
                website:
                  type: string
                address:
                  type: string
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Business created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /business/{id}:
    get:
      tags:
        - Business
      summary: Get business by ID
      description: Retrieve business details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Business retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Business
      summary: Update business
      description: Update business information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Business'
      responses:
        '200':
          description: Business updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Business
      summary: Delete business
      description: Delete a business account
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Business deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Campaign Routes
  /campaigns:
    get:
      tags:
        - Campaigns
      summary: Get all campaigns
      description: Retrieve all campaigns for a business
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaigns retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Campaigns
      summary: Create new campaign
      description: Create a new marketing campaign
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - business_id
                - user_id
              properties:
                name:
                  type: string
                description:
                  type: string
                message_content:
                  type: string
                scheduled_at:
                  type: string
                  format: date-time
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /campaigns/{id}:
    get:
      tags:
        - Campaigns
      summary: Get campaign by ID
      description: Retrieve campaign details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Campaigns
      summary: Update campaign
      description: Update campaign information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Campaign'
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Campaigns
      summary: Delete campaign
      description: Delete a campaign
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Campaign deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /campaigns/{id}/broadcast:
    post:
      tags:
        - Campaigns
      summary: Broadcast campaign
      description: Send campaign messages to all contacts
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
              properties:
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Campaign broadcast completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # AI Agents Routes
  /ai-agents:
    get:
      tags:
        - AI Agents
      summary: Get all AI agents
      description: Retrieve all AI agents for a business
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: AI agents retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - AI Agents
      summary: Create new AI agent
      description: Create a new AI agent
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - system_prompt
                - business_id
                - user_id
              properties:
                name:
                  type: string
                description:
                  type: string
                agent_type:
                  type: string
                  enum: [customer_support, sales, lead_qualifier, faq, general, custom]
                ai_provider:
                  type: string
                  enum: [openai, anthropic, google]
                model_name:
                  type: string
                system_prompt:
                  type: string
                persona:
                  type: string
                temperature:
                  type: number
                  minimum: 0
                  maximum: 2
                max_tokens:
                  type: integer
                  minimum: 1
                top_p:
                  type: number
                  minimum: 0
                  maximum: 1
                frequency_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                presence_penalty:
                  type: number
                  minimum: -2
                  maximum: 2
                language:
                  type: string
                fallback_behavior:
                  type: string
                  enum: [handoff, generic_response, silence, notify_agent]
                handoff_keywords:
                  type: array
                  items:
                    type: string
                confidence_threshold:
                  type: number
                  minimum: 0
                  maximum: 1
                is_active:
                  type: boolean
                is_default:
                  type: boolean
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: AI agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ai-agents/{id}:
    get:
      tags:
        - AI Agents
      summary: Get AI agent by ID
      description: Retrieve AI agent details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: AI agent retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - AI Agents
      summary: Update AI agent
      description: Update AI agent configuration
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIAgent'
      responses:
        '200':
          description: AI agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - AI Agents
      summary: Delete AI agent
      description: Delete an AI agent
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: AI agent deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ai-agents/{id}/toggle:
    patch:
      tags:
        - AI Agents
      summary: Toggle AI agent status
      description: Toggle agent active/default status
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - field
              properties:
                field:
                  type: string
                  enum: [is_active, is_default]
      responses:
        '200':
          description: Agent status toggled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ai-agents/{id}/chat:
    post:
      tags:
        - AI Agents
      summary: Chat with AI agent
      description: Send message to AI agent and get response
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_message
                - user_id
              properties:
                conversation_id:
                  type: string
                user_message:
                  type: string
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: AI response generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  STATUS:
                    type: string
                    enum: [success]
                  MESSAGE:
                    type: string
                  DATA:
                    type: object
                    properties:
                      reply:
                        type: string
                      handoff:
                        type: boolean
                      confidence:
                        type: number

  # Knowledge Base Routes
  /ai-knowledge-base:
    get:
      tags:
        - Knowledge Base
      summary: Get knowledge base entries
      description: Retrieve knowledge base entries for an agent
      security:
        - BearerAuth: []
      parameters:
        - name: agent_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: content_type
          in: query
          schema:
            type: string
            enum: [faq, product, policy, general]
        - name: is_active
          in: query
          schema:
            type: boolean
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Knowledge base entries retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Knowledge Base
      summary: Create knowledge base entry
      description: Add new entry to AI agent knowledge base
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
                - content_type
                - answer
                - user_id
              properties:
                agent_id:
                  type: string
                  format: uuid
                content_type:
                  type: string
                  enum: [faq, product, policy, general]
                question:
                  type: string
                answer:
                  type: string
                keywords:
                  type: array
                  items:
                    type: string
                context_metadata:
                  type: object
                priority:
                  type: integer
                is_active:
                  type: boolean
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Knowledge base entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ai-knowledge-base/{id}:
    get:
      tags:
        - Knowledge Base
      summary: Get knowledge base entry by ID
      description: Retrieve specific knowledge base entry
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Knowledge base entry retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Knowledge Base
      summary: Update knowledge base entry
      description: Update existing knowledge base entry
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                answer:
                  type: string
                keywords:
                  type: array
                  items:
                    type: string
                context_metadata:
                  type: object
                priority:
                  type: integer
                is_active:
                  type: boolean
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Knowledge base entry updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Knowledge Base
      summary: Delete knowledge base entry
      description: Remove entry from knowledge base
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Knowledge base entry deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ai-agents/{agent_id}/knowledge-base/bulk:
    post:
      tags:
        - Knowledge Base
      summary: Bulk import knowledge base entries
      description: Import multiple knowledge base entries at once
      security:
        - BearerAuth: []
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - entries
                - user_id
              properties:
                entries:
                  type: array
                  items:
                    type: object
                    properties:
                      content_type:
                        type: string
                        enum: [faq, product, policy, general]
                      question:
                        type: string
                      answer:
                        type: string
                      keywords:
                        type: array
                        items:
                          type: string
                      context_metadata:
                        type: object
                      priority:
                        type: integer
                      is_active:
                        type: boolean
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Knowledge base entries imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Contacts Routes
  /contacts:
    get:
      tags:
        - Contacts
      summary: Get all contacts
      description: Retrieve all contacts for a business
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: search
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Contacts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Contacts
      summary: Create new contact
      description: Add new contact to the system
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - phone
                - business_id
                - user_id
              properties:
                name:
                  type: string
                phone:
                  type: string
                email:
                  type: string
                  format: email
                tags:
                  type: array
                  items:
                    type: string
                status:
                  type: string
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Contact created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /contacts/{id}:
    get:
      tags:
        - Contacts
      summary: Get contact by ID
      description: Retrieve contact details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Contacts
      summary: Update contact
      description: Update contact information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Contacts
      summary: Delete contact
      description: Remove contact from the system
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Contact deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Messages Routes
  /messages:
    get:
      tags:
        - Messages
      summary: Get all messages
      description: Retrieve messages with optional filtering
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: conversation_id
          in: query
          schema:
            type: string
        - name: contact_id
          in: query
          schema:
            type: string
            format: uuid
        - name: direction
          in: query
          schema:
            type: string
            enum: [inbound, outbound]
        - name: status
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Messages
      summary: Send outbound message
      description: Send message to contact
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contact_id
                - content
                - business_id
                - user_id
              properties:
                contact_id:
                  type: string
                  format: uuid
                content:
                  type: string
                message_type:
                  type: string
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /messages/{id}:
    get:
      tags:
        - Messages
      summary: Get message by ID
      description: Retrieve message details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Message retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Messages
      summary: Update message
      description: Update message status or content
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: Message updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Conversations Routes
  /conversations:
    get:
      tags:
        - Conversations
      summary: Get all conversations
      description: Retrieve all conversations for a business
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Conversations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Conversations
      summary: Create new conversation
      description: Start new conversation with contact
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contact_id
                - business_id
                - user_id
              properties:
                contact_id:
                  type: string
                  format: uuid
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Conversation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /conversations/{id}:
    get:
      tags:
        - Conversations
      summary: Get conversation by ID
      description: Retrieve conversation details with messages
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Conversation retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Conversations
      summary: Update conversation
      description: Update conversation status or metadata
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                assigned_agent_id:
                  type: string
                  format: uuid
                priority:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Conversation updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Teams Routes
  /teams:
    get:
      tags:
        - Teams
      summary: Get all teams
      description: Retrieve all teams for a business
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Teams retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Teams
      summary: Create new team
      description: Create a new team for business
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - business_id
                - user_id
              properties:
                name:
                  type: string
                description:
                  type: string
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Team created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /teams/{id}:
    get:
      tags:
        - Teams
      summary: Get team by ID
      description: Retrieve team details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Team retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Teams
      summary: Update team
      description: Update team information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
      responses:
        '200':
          description: Team updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Teams
      summary: Delete team
      description: Remove team from the system
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Team deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Team Members Routes
  /team-members:
    get:
      tags:
        - Team Members
      summary: Get all team members
      description: Retrieve all team members
      security:
        - BearerAuth: []
      parameters:
        - name: team_id
          in: query
          schema:
            type: string
            format: uuid
        - name: business_id
          in: query
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Team members retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Team Members
      summary: Add team member
      description: Add user to team
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - team_id
                - user_id
                - role
              properties:
                team_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
                role:
                  type: string
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Team member added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /team-members/{id}:
    get:
      tags:
        - Team Members
      summary: Get team member by ID
      description: Retrieve team member details
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Team member retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Team Members
      summary: Update team member
      description: Update team member role or permissions
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamMember'
      responses:
        '200':
          description: Team member updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    delete:
      tags:
        - Team Members
      summary: Remove team member
      description: Remove user from team
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Team member removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Dashboard Routes
  /dashboard/overview:
    get:
      tags:
        - Dashboard
      summary: Get dashboard overview
      description: Retrieve dashboard statistics and metrics
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Dashboard overview retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Metrics Routes
  /metrics/overview:
    get:
      tags:
        - Metrics
      summary: Get metrics overview
      description: Retrieve business metrics and analytics
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: period
          in: query
          schema:
            type: string
            enum: [today, week, month, year]
            default: month
      responses:
        '200':
          description: Metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Media Routes
  /media:
    get:
      tags:
        - Media
      summary: Get media files
      description: Retrieve uploaded media files
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: type
          in: query
          schema:
            type: string
            enum: [image, video, audio, document]
      responses:
        '200':
          description: Media files retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    post:
      tags:
        - Media
      summary: Upload media file
      description: Upload media file to server
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
                - business_id
                - user_id
              properties:
                file:
                  type: string
                  format: binary
                business_id:
                  type: string
                  format: uuid
                user_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Media uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  # Webhooks Routes
  /webhooks/whatsapp:
    post:
      tags:
        - Webhooks
      summary: WhatsApp webhook
      description: Handle incoming WhatsApp webhook events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook processed successfully

  # Users Routes
  /users:
    get:
      tags:
        - Users
      summary: Get users
      description: Retrieve users with optional filtering
      security:
        - BearerAuth: []
      parameters:
        - name: business_id
          in: query
          schema:
            type: string
            format: uuid
        - name: role
          in: query
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /users/{id}:
    get:
      tags:
        - Users
      summary: Get user by ID
      description: Retrieve user details by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

    put:
      tags:
        - Users
      summary: Update user
      description: Update user information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

# Tags
tags:
  - name: Authentication
    description: User authentication and authorization endpoints
  - name: Business
    description: Business management endpoints
  - name: Campaigns
    description: Marketing campaign management endpoints
  - name: AI Agents
    description: AI agent configuration and interaction endpoints
  - name: Knowledge Base
    description: AI agent knowledge base management endpoints
  - name: Contacts
    description: Contact management endpoints
  - name: Messages
    description: Message management and sending endpoints
  - name: Conversations
    description: Conversation management endpoints
  - name: Teams
    description: Team management endpoints
  - name: Team Members
    description: Team member management endpoints
  - name: Dashboard
    description: Dashboard and overview endpoints
  - name: Metrics
    description: Analytics and metrics endpoints
  - name: Media
    description: Media file management endpoints
  - name: Webhooks
    description: External webhook handling endpoints
  - name: Users
    description: User management endpoints
