openapi: 3.2.0
info:
  title: Zoca Chat API
  contact: {}
  x-refined-note:
  - x-apievangelist-note differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Chat across 2 of this provider''s published API definitions: zoca-platform-openapi.yml, zoca-tasks-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.zoca.ai
  description: Production
- url: https://tasks.zoca.ai
  description: Production
tags:
- name: Chat
paths:
  /chat/conversations:
    get:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Returns conversation(s) based on filters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid parameters
      summary: Get conversations list or single conversation details
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/message:
    get:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Returns message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid parameters
        '404':
          description: Message not found
      summary: Get message by ID or messages by conversation
      tags:
      - Chat
    post:
      operationId: t_value
      parameters: []
      responses:
        '201':
          description: Message created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid message data
      summary: Create a new message in a conversation
      tags:
      - Chat
    put:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Message updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/t'
        '400':
          description: Invalid update data
        '404':
          description: Message not found
      summary: Update message text or soft delete
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/reaction:
    post:
      operationId: t_value
      parameters: []
      responses:
        '201':
          description: Reaction added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/t'
        '400':
          description: Invalid reaction data
        '404':
          description: Message not found
      summary: Add reaction to a message
      tags:
      - Chat
    put:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Reaction updated successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/e'
        '400':
          description: Invalid update data
        '404':
          description: Reaction not found
      summary: Update or soft delete a reaction
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/message-receipt:
    post:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Messages marked as read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid receipt data
      summary: Mark messages as read in a conversation
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/password:
    put:
      operationId: t_value
      parameters:
      - name: password
        required: true
        in: query
        schema:
          type: string
      - name: email
        required: true
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Password validation result with tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Missing or invalid parameters
      summary: Validate member password and get auth tokens
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/conversation-properties:
    put:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Properties updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid update data
        '404':
          description: Conversation or member not found
      summary: Update conversation properties (isRead, isPinned)
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/conversations/{conversationId}/members/{memberId}:
    put:
      operationId: t_value
      parameters:
      - name: memberId
        required: true
        in: path
        schema:
          format: uuid
          type: string
      - name: conversationId
        required: true
        in: path
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Member added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid UUID format
        '404':
          description: Conversation or member not found
      summary: Add member to conversation
      tags:
      - Chat
    delete:
      operationId: t_value
      parameters:
      - name: memberId
        required: true
        in: path
        schema:
          format: uuid
          type: string
      - name: conversationId
        required: true
        in: path
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Member removed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid UUID format
        '404':
          description: Conversation or member not found
      summary: Remove member from conversation
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/members/bulk-add-conversations:
    post:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Member added to conversations with detailed results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e'
        '400':
          description: Invalid request data
      summary: Add a member to multiple conversations
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/navigation-templates:
    get:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Returns navigation templates dictionary
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    navigation:
                      type: string
      summary: Get navigation templates for chat interface
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/message-template:
    post:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Message template upserted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  templateName:
                    type: string
                  messageText:
                    type: string
        '400':
          description: Invalid request data
      summary: Upsert message template
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /chat/website-onboarding-request-status:
    get:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Website onboarding request status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  isServicesAdded:
                    type: boolean
                  hasWebsiteOnboarding:
                    type: boolean
                  hasWebsiteEdits:
                    type: boolean
                  websiteOnboardingRequestId:
                    type: string
                  conversationId:
                    type: string
        '400':
          description: Invalid request data
        '404':
          description: Entity or conversation not found
      summary: Get website onboarding request status for entity
      tags:
      - Chat
    servers:
    - url: https://api.zoca.ai
      description: Production
  /tasks/api/v1/chat/schedule-message:
    post:
      operationId: t_value
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/e_2'
      responses:
        '201':
          description: Message scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/e_2'
        '400':
          description: Invalid request data
        '500':
          description: Internal server error
      summary: Schedule a message to be sent later
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
  /tasks/api/v1/chat/scheduled-messages:
    get:
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: List of scheduled messages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/e_2'
        '500':
          description: Internal server error
      summary: Get scheduled messages with optional filters
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
  /tasks/api/v1/chat/process-scheduled-message:
    post:
      description: This endpoint is called by the worker to process scheduled messages. It will either send the message or abort it based on intervening messages.
      operationId: t_value
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/e_2'
      responses:
        '200':
          description: Message processed successfully
        '500':
          description: Internal server error
      summary: Process a scheduled message (called by worker)
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
  /tasks/api/v1/chat/check-intervening-messages:
    post:
      description: Checks if there are any messages between the scheduled time and creation time
      operationId: t_value
      parameters: []
      responses:
        '200':
          description: Returns whether intervening messages exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasInterveningMessages:
                    type: boolean
        '500':
          description: Internal server error
      summary: Check if there are intervening messages
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
  /tasks/api/v1/chat/cancel-scheduled-message:
    post:
      description: Cancels a scheduled message that has not been sent yet (status PENDING)
      operationId: t_value
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/e_2'
      responses:
        '200':
          description: Message cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  messageId:
                    type: string
        '400':
          description: Message not found or already processed
        '500':
          description: Internal server error
      summary: Cancel a scheduled message
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
  /tasks/api/v1/chat/message/bulk:
    post:
      operationId: t_value
      parameters: []
      requestBody:
        required: true
        description: Either provide an array of CreateMessageDto objects or a BulkCreateMessagesDto with s3Url
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  s3Url:
                    type: string
                    description: S3 URL containing CSV file with bulk messages
                    example: s3://bucket-name/path/to/messages.csv
                required:
                - s3Url
              - type: array
                items:
                  type: object
                  properties:
                    conversationID:
                      type: string
                      format: uuid
                    text:
                      type: string
                    from:
                      type: string
                      format: uuid
                    parentMessageId:
                      type: string
                      format: uuid
                    attachments:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                          url:
                            type: string
                          type:
                            type: string
                            enum:
                            - PDF
                            - AUDIO
                            - VIDEO
                            - GIFS
                            - OTHERS
                          metadata:
                            type: object
                  required:
                  - conversationID
                  - from
      responses:
        '201':
          description: Messages queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  jobId:
                    type: string
        '400':
          description: Invalid message data
      summary: Create multiple messages in bulk
      tags:
      - Chat
      security:
      - access-token: []
    servers:
    - url: https://tasks.zoca.ai
      description: Production
components:
  schemas:
    t:
      type: object
      properties:
        id:
          type: number
        planId:
          type: number
        agentEntityId:
          type:
          - object
          - 'null'
          format: uuid
        agentName:
          type: string
        internalAddonName:
          type: string
          description: Chargebee item_price_id (internal addon name)
        externalAddonName:
          type: string
          description: Human-readable addon label shown to end-users
        active:
          type: boolean
          description: true if the location currently holds an active subscription for this addon
        subscriptionId:
          type:
          - object
          - 'null'
        quantity:
          type:
          - object
          - 'null'
        trialEnd:
          type:
          - object
          - 'null'
          description: Unix epoch seconds (Chargebee trial_end)
        addonPricingId:
          type:
          - object
          - 'null'
          description: chargebee.addon_pricing.id for this addon at the location's current cadence. Pass back to PATCH /billing/subscription as `update_items.items[].addonPricingId`.Null when no active addon_pricing row exists - surfaces a config gap and the FE should hide the buy CTA.
        unitPriceCents:
          type:
          - object
          - 'null'
          description: Per-line price the location would be billed at this cadence (cents).
      required:
      - id
      - planId
      - agentEntityId
      - agentName
      - internalAddonName
      - externalAddonName
      - active
      - subscriptionId
      - quantity
      - trialEnd
      - addonPricingId
      - unitPriceCents
    e:
      type: object
      properties:
        id:
          type: number
        entityId:
          type: string
        attribute:
          type: string
        value:
          type:
          - object
          - 'null'
        metadata:
          type:
          - object
          - 'null'
        createdAt:
          type:
          - object
          - 'null'
      required:
      - id
      - entityId
      - attribute
    e_2:
      type: object
      properties:
        scan:
          $ref: '#/components/schemas/e_2'
        businessLat:
          type:
          - number
          - 'null'
        businessLng:
          type:
          - number
          - 'null'
        points:
          type: array
          items:
            $ref: '#/components/schemas/e_2'
        heroMetrics:
          $ref: '#/components/schemas/e_2'
      required:
      - scan
      - businessLat
      - businessLng
      - points
      - heroMetrics
  securitySchemes:
    access-token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      name: Authorization
      description: Enter JWT token in the format Bearer <token>
      in: header
x-refined-from:
- zoca-platform-openapi.yml
- zoca-tasks-openapi.yml