openapi: 3.0.3
info:
  title: MG Node Bot API
  version: 1.0.0
  description: MG Node Bot API
servers:
  - url: https://mg.rcrm-tech.ru/api/bot/v1
tags:
  - name: Bot
  - name: Channel
  - name: Chat
  - name: Command
  - name: Customer
  - name: Dialog
  - name: File
  - name: User
  - name: Message
  - name: WS
paths:
  /bots:
    get:
      summary: Retrieve list of bots
      description: Retrieves a list of all available bots with optional filtering
      security:
        - bot_token: []
      tags:
        - Bot
      operationId: ListBots
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SelfQuery'
        - $ref: '#/components/parameters/BotActiveQuery'
        - $ref: '#/components/parameters/BotRoleQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
      responses:
        '200':
          $ref: '#/components/responses/BotsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /my/info:
    patch:
      summary: Update current bot profile
      description: Updates the information of the currently authenticated bot
      security:
        - bot_token: []
      tags:
        - Bot
      operationId: UpdateBot
      requestBody:
        $ref: '#/components/requestBodies/UpdateBotRequest'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /channels:
    get:
      summary: Retrieve available channels
      description: Returns a list of channels with optional filters
      security:
        - bot_token: []
      tags:
        - Channel
      operationId: ListChannels
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/ChannelTypeQuery'
        - $ref: '#/components/parameters/ChannelActiveQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
      responses:
        '200':
          $ref: '#/components/responses/ChannelsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /chats:
    get:
      summary: Retrieve chat list
      description: Returns a filtered list of chats available to the bot
      security:
        - bot_token: []
      tags:
        - Chat
      operationId: ListChats
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/ChannelIDQuery'
        - $ref: '#/components/parameters/ChannelTypeSingleQuery'
        - $ref: '#/components/parameters/CustomerIDQuery'
        - $ref: '#/components/parameters/CustomerExternalIDQuery'
        - $ref: '#/components/parameters/IncludeMassCommunicationQuery'
      responses:
        '200':
          $ref: '#/components/responses/ChatsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /my/commands:
    get:
      summary: List available bot commands
      description: Returns a list of bot commands filtered by optional parameters
      operationId: ListCommands
      tags:
        - Command
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/CommandNameQuery'
      responses:
        '200':
          $ref: '#/components/responses/CommandsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /my/commands/{command_name}:
    put:
      summary: Create or update a command
      description: Creates a new command or updates an existing one with the specified name
      operationId: CreateOrUpdateCommand
      tags:
        - Command
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/CommandNamePath'
      requestBody:
        $ref: '#/components/requestBodies/CreateOrUpdateCommandRequest'
      responses:
        '200':
          $ref: '#/components/responses/CommandCreateResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Remove a bot command
      description: Deletes the command associated with the given name
      operationId: DeleteCommand
      tags:
        - Bot
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/CommandNamePath'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /customers:
    get:
      summary: Get customers list
      description: Returns a list of customers
      security:
        - bot_token: []
      tags:
        - Customer
      operationId: ListCustomers
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/ChannelIDQuery'
        - $ref: '#/components/parameters/ChannelTypeSingleQuery'
        - $ref: '#/components/parameters/ExternalIDQuery'
      responses:
        '200':
          $ref: '#/components/responses/CustomersListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs:
    get:
      summary: Retrieve list of dialogs
      description: Returns a list of dialogs with optional filters
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: ListDialogs
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/ChatIDQuery'
        - $ref: '#/components/parameters/UserIDQuery'
        - $ref: '#/components/parameters/BotIDQuery'
        - $ref: '#/components/parameters/DialogActiveQuery'
        - $ref: '#/components/parameters/AssignQuery'
        - $ref: '#/components/parameters/IncludeMassCommunicationQuery'
      responses:
        '200':
          $ref: '#/components/responses/DialogsListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs/{dialog_id}/assign:
    patch:
      summary: Assign a responsible user to a dialog
      description: Sets or updates the user responsible for handling the specified dialog
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: AssignDialogResponsible
      parameters:
        - $ref: '#/components/parameters/DialogIdPath'
      requestBody:
        $ref: '#/components/requestBodies/DialogResponsibleRequest'
      responses:
        '200':
          $ref: '#/components/responses/DialogAssignResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs/{dialog_id}/unassign:
    patch:
      summary: Unassign responsible user from dialog
      description: Removes the currently assigned responsible user from the specified dialog
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: UnassignDialogResponsible
      parameters:
        - $ref: '#/components/parameters/DialogIdPath'
      responses:
        '200':
          $ref: '#/components/responses/DialogUnassignResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs/{dialog_id}/close:
    delete:
      summary: Close a dialog
      description: Marks the specified dialog as closed, preventing further updates or messages
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: CloseDialog
      parameters:
        - $ref: '#/components/parameters/DialogIdPath'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs/{dialog_id}/tags/add:
    patch:
      summary: Add tags to a dialog
      description: Appends tags to the specified dialog
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: DialogAddTags
      parameters:
        - $ref: '#/components/parameters/DialogIdPath'
      requestBody:
        $ref: '#/components/requestBodies/DialogAddTagsRequest'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /dialogs/{dialog_id}/tags/delete:
    patch:
      summary: Remove tags from a dialog
      description: Removes tags from the specified dialog
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: DialogDeleteTags
      parameters:
        - $ref: '#/components/parameters/DialogIdPath'
      requestBody:
        $ref: '#/components/requestBodies/DialogDeleteTagsRequest'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /chats/{chat_id}/dialogs:
    post:
      summary: Create a dialog
      description: Creates a new dialog within the specified chat
      security:
        - bot_token: []
      tags:
        - Dialog
      operationId: CreateDialog
      parameters:
        - $ref: '#/components/parameters/ChatIdPath'
      requestBody:
        $ref: '#/components/requestBodies/CreateDialogRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreateDialogResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /files/{id}:
    get:
      summary: Get direct file URL by ID
      description: Returns a direct URL for downloading a previously uploaded file using its unique identifier
      security:
        - bot_token: []
      tags:
        - File
      operationId: GetFileUrl
      parameters:
        - $ref: '#/components/parameters/FileIdPath'
      responses:
        '200':
          $ref: '#/components/responses/FullFileResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /files/upload:
    post:
      summary: Upload a new file
      description: Uploads a new file to the server using multipart/form-data
      security:
        - bot_token: []
      tags:
        - File
      operationId: UploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Binary file data to upload (e.g. image, document, video)
      responses:
        '200':
          $ref: '#/components/responses/UploadResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /files/upload_by_url:
    post:
      summary: Upload a file from a URL
      description: Downloads a file from the provided URL and uploads it to the server
      security:
        - bot_token: []
      tags:
        - File
      operationId: UploadFileByUrl
      requestBody:
        $ref: '#/components/requestBodies/UploadFileByUrlRequest'
      responses:
        '200':
          $ref: '#/components/responses/UploadResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /files/{id}/meta:
    put:
      summary: Update metadata of a previously uploaded file
      description: Updates metadata of the specified file by its identifier
      security:
        - bot_token: []
      tags:
        - File
      operationId: UpdateFileMetadata
      parameters:
        - $ref: '#/components/parameters/FileIdPath'
      requestBody:
        $ref: '#/components/requestBodies/UpdateFileMetadataRequest'
      responses:
        '200':
          $ref: '#/components/responses/UploadResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /members:
    get:
      summary: Retrieves a list of chat members
      description: Returns a list of chat members filtered by optional parameters
      security:
        - bot_token: []
      tags:
        - User
      operationId: ListMembers
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/ChatIDQuery'
        - $ref: '#/components/parameters/UserIDQuery'
        - $ref: '#/components/parameters/MemberStateQuery'
      responses:
        '200':
          $ref: '#/components/responses/ChatMemberListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /users:
    get:
      summary: Retrieves a list of users
      description: Returns a list of users filtered by optional parameters
      security:
        - bot_token: []
      tags:
        - User
      operationId: ListUsers
      parameters:
        - $ref: '#/components/parameters/IDQuery'
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/UserActiveQuery'
        - $ref: '#/components/parameters/UserOnlineQuery'
        - $ref: '#/components/parameters/ExternalIDQuery'
      responses:
        '200':
          $ref: '#/components/responses/UserListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /messages:
    get:
      summary: Get message list
      description: Returns a list of messages filtered by various criteria
      security:
        - bot_token: []
      tags:
        - Message
      operationId: ListMessages
      parameters:
        - $ref: '#/components/parameters/SinceQuery'
        - $ref: '#/components/parameters/UntilQuery'
        - $ref: '#/components/parameters/SinceIDQuery'
        - $ref: '#/components/parameters/UntilIDQuery'
        - $ref: '#/components/parameters/LimitQuery'
        - $ref: '#/components/parameters/MessageIDArrayQuery'
        - $ref: '#/components/parameters/ChatIDQuery'
        - $ref: '#/components/parameters/UserIDQuery'
        - $ref: '#/components/parameters/CustomerIDQuery'
        - $ref: '#/components/parameters/BotIDQuery'
        - $ref: '#/components/parameters/DialogIDQuery'
        - $ref: '#/components/parameters/ChannelIDQuery'
        - $ref: '#/components/parameters/ChannelTypeSingleQuery'
        - $ref: '#/components/parameters/MessageTypeQuery'
        - $ref: '#/components/parameters/IncludeMassCommunicationQuery'
        - $ref: '#/components/parameters/MessageScopeQuery'
      responses:
        '200':
          $ref: '#/components/responses/MessageListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Send new message
      description: Send a new message to a specified transport channel
      security:
        - bot_token: []
      tags:
        - Message
      operationId: SendMessage
      requestBody:
        $ref: '#/components/requestBodies/SendMessageRequest'
      responses:
        '200':
          $ref: '#/components/responses/SendMessageResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /messages/{message_id}:
    patch:
      summary: Edit a message by ID
      description: Updates the contents or metadata of an existing message
      tags:
        - Message
      operationId: EditMessage
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/MessageIdPath'
      requestBody:
        $ref: '#/components/requestBodies/EditMessageRequest'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete a message by ID
      description: Deletes a message with the given ID. This operation is irreversible.
      tags:
        - Message
      operationId: DeleteMessage
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/MessageIdPath'
      responses:
        '200':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /ws:
    get:
      summary: WebSocket connection for real-time updates
      description: This URL is used to establish a connection via WebSocket. Using this connection, the bot can receive data for each type of event it is subscribed to. The list of events is passed as a string, with values separated by commas.
      tags:
        - WS
      operationId: WebSocketConnection
      security:
        - bot_token: []
      parameters:
        - $ref: '#/components/parameters/WSEventsQuery'
        - $ref: '#/components/parameters/WSOptionsQuery'
      responses:
        '101':
          $ref: '#/components/responses/EmptyResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    bot_token:
      description: Token for authorization
      type: apiKey
      in: header
      name: X-Bot-Token
  parameters:
    IDQuery:
      description: Unique identifier of the object
      in: query
      name: id
      schema:
        format: int
        minimum: 1
        type: integer
    SelfQuery:
      description: Filter to include only the current bot
      in: query
      name: self
      allowEmptyValue: true
      schema:
        $ref: '#/components/schemas/Boolean'
    BotActiveQuery:
      description: Filters bots by activity status
      in: query
      name: active
      schema:
        $ref: '#/components/schemas/Boolean'
    BotRoleQuery:
      description: Filters bots by one or more assigned roles
      in: query
      name: role
      schema:
        type: array
        items:
          $ref: '#/components/schemas/Role'
    SinceQuery:
      description: Lower limit of the date of the last object update
      in: query
      name: since
      schema:
        format: date-time
        type: string
    UntilQuery:
      description: Upper limit of the date of the last object update
      in: query
      name: until
      schema:
        format: date-time
        type: string
    SinceIDQuery:
      description: Lower bound for object identifiers
      in: query
      name: since_id
      schema:
        type: integer
        format: int64
        minimum: 1
    UntilIDQuery:
      description: Upper bound for object identifiers
      in: query
      name: until_id
      schema:
        type: integer
        format: int64
        minimum: 1
    LimitQuery:
      description: The number of elements in the response. Default value is 100
      in: query
      name: limit
      schema:
        format: int
        maximum: 1000
        minimum: 1
        type: integer
    ChannelIDQuery:
      description: Filter by channel ID
      in: query
      name: channel_id
      schema:
        type: integer
        minimum: 1
    ChannelTypeSingleQuery:
      description: Filter by channel type
      in: query
      name: channel_type
      schema:
        $ref: '#/components/schemas/ChannelType'
    CustomerIDQuery:
      description: Filter by customer ID
      in: query
      name: customer_id
      schema:
        type: integer
        minimum: 1
    CustomerExternalIDQuery:
      description: Filter by external customer ID
      in: query
      name: customer_external_id
      schema:
        type: string
        minLength: 1
    IncludeMassCommunicationQuery:
      description: Whether to include mass communication chats/messages
      in: query
      name: include_mass_communication
      schema:
        $ref: '#/components/schemas/Boolean'
    CommandNameQuery:
      description: Filter commands by name
      in: query
      name: name
      schema:
        type: string
        maxLength: 32
    ExternalIDQuery:
      description: Filter by external identifier
      in: query
      name: external_id
      schema:
        type: string
    ChatIDQuery:
      description: Filter by chat identifier
      in: query
      name: chat_id
      schema:
        type: integer
        minimum: 1
    UserIDQuery:
      description: Filter by user ID
      in: query
      name: user_id
      schema:
        type: integer
        minimum: 1
    BotIDQuery:
      description: Filter by bot ID
      in: query
      name: bot_id
      schema:
        type: integer
        minimum: 1
    DialogActiveQuery:
      description: Filter by activity flag
      in: query
      name: active
      schema:
        $ref: '#/components/schemas/Boolean'
    AssignQuery:
      description: Filter by assignment status
      in: query
      name: assign
      schema:
        $ref: '#/components/schemas/Boolean'
    MemberStateQuery:
      description: Filter by member state
      in: query
      name: state
      schema:
        type: string
        enum:
          - active
          - kicked
          - leaved
    UserActiveQuery:
      description: Filter users by activity status
      in: query
      name: active
      schema:
        $ref: '#/components/schemas/Boolean'
    UserOnlineQuery:
      description: Filter users by online status
      in: query
      name: online
      schema:
        $ref: '#/components/schemas/Boolean'
    MessageIDArrayQuery:
      description: Filter by a list of message IDs
      in: query
      name: id
      schema:
        type: array
        items:
          type: integer
          format: int64
    DialogIDQuery:
      description: Filter by dialog ID
      in: query
      name: dialog_id
      schema:
        type: integer
        minimum: 1
        format: int64
    MessageTypeQuery:
      description: Filter by message type
      in: query
      name: type
      schema:
        $ref: '#/components/schemas/MessageType'
    MessageScopeQuery:
      description: Filter by message scope (public or private)
      in: query
      name: scope
      schema:
        type: string
        enum:
          - public
          - private
    WSEventsQuery:
      description: Comma-separated list of events to subscribe to via WebSocket
      in: query
      name: events
      schema:
        type: string
        example: message_new,message_updated,message_restored,message_deleted,dialog_opened,dialog_closed,dialog_assign,chat_created,chat_updated,chats_deleted,user_joined_chat,user_left_chat,user_updated,user_online_updated,channel_updated,customer_updated,bot_updated
        minLength: 1
    WSOptionsQuery:
      description: Additional WebSocket connection parameters (include_mass_communication — allow receiving events for messages sent via mass mailing actions)
      in: query
      name: options
      schema:
        type: string
        example: include_mass_communication
    ChannelActiveQuery:
      description: Filters channels by activity status
      in: query
      name: active
      schema:
        $ref: '#/components/schemas/Boolean'
    ChannelTypeQuery:
      description: Filters channels by one or more specified types
      in: query
      name: types
      schema:
        items:
          $ref: '#/components/schemas/ChannelType'
        type: array
    CommandNamePath:
      description: Unique identifier of the bot command. Used to reference a specific command in the system
      in: path
      name: command_name
      required: true
      schema:
        type: string
        maxLength: 32
    DialogIdPath:
      description: Unique identifier of the dialog
      in: path
      name: dialog_id
      required: true
      schema:
        type: integer
        format: int64
        example: 1
    ChatIdPath:
      description: Unique identifier of the chat
      in: path
      name: chat_id
      required: true
      schema:
        type: integer
        format: int64
        example: 1
    FileIdPath:
      description: Unique identifier (UUID) of the file
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
        example: e33e5398-814a-47d6-902a-466ba120ce45
    MessageIdPath:
      description: Unique identifier of the message
      in: path
      name: message_id
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
        example: 100
  requestBodies:
    UpdateBotRequest:
      description: Bot update request
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: Bot name
                example: Demo bot
                type: string
                maxLength: 255
              avatar_url:
                description: URL of bot avatar
                example: https://avatar.demo/demo-avatar
                type: string
                format: uri
              roles:
                $ref: '#/components/schemas/Roles'
    CreateOrUpdateCommandRequest:
      description: Request body for creating or updating a bot command
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/CreateCommandRequestBody'
              - $ref: '#/components/schemas/UpdateCommandRequestBody'
    DialogResponsibleRequest:
      description: Request to assign a responsible user and bot to a dialog
      content:
        application/json:
          schema:
            type: object
            properties:
              bot_id:
                type: integer
                format: int64
                example: 1
                description: Unique identifier of the bot assigned to the dialog
              user_id:
                type: integer
                format: int64
                example: 1
                description: Unique identifier of the user in chats to assign as responsible
    DialogAddTagsRequest:
      description: Request to add tags to a dialog
      content:
        application/json:
          schema:
            type: object
            required:
              - tags
            properties:
              tags:
                type: array
                minLength: 1
                description: List of tags to add
                items:
                  type: object
                  required:
                    - name
                  properties:
                    color_code:
                      allOf:
                        - $ref: '#/components/schemas/ColorCode'
                      description: Optional color code for the tag
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: Name of the tag
    DialogDeleteTagsRequest:
      description: Request to delete tags from a dialog
      content:
        application/json:
          schema:
            type: object
            required:
              - tags
            properties:
              tags:
                type: array
                minLength: 1
                items:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: Name of the tag to delete
    CreateDialogRequest:
      description: Request to create a new dialog
      content:
        application/json:
          schema:
            type: object
            properties:
              bot_id:
                type: integer
                format: int64
                minimum: 1
                example: 32
                nullable: true
                description: ID of the bot who starts the dialog
              user_id:
                type: integer
                format: int64
                minimum: 1
                example: 43
                nullable: true
                description: Unique identifier of the user in chats who starts the dialog
    UploadFileByUrlRequest:
      description: Request payload for uploading a file from a remote URL
      content:
        application/json:
          schema:
            type: object
            required:
              - url
            properties:
              url:
                type: string
                format: uri
                description: The URL of the file to download and upload
                example: https://file.demo/demo-file
    UpdateFileMetadataRequest:
      description: Request payload for updating metadata of a file
      content:
        application/json:
          schema:
            type: object
            required:
              - transcription
            properties:
              transcription:
                type: string
                description: Updated transcription text associated with the file
                example: Example updated transcription
              transcription_status:
                $ref: '#/components/schemas/FileTranscriptionStatus'
    SendMessageRequest:
      description: Request payload for sending a new message
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendMessageRequestBody'
    EditMessageRequest:
      description: Request payload for editing an existing message
      content:
        application/json:
          schema:
            type: object
            description: Represents the payload of a message, including content, attachments, and related metadata depending on the message type
            properties:
              content:
                type: string
                description: Message text content (required for text messages only)
                example: Hello!
                maxLength: 2000
              items:
                type: array
                description: File attachments (required for file, audio and image messages)
                items:
                  type: object
                  description: File attachment
                  required:
                    - id
                  properties:
                    caption:
                      type: string
                      description: Caption for the file
                      example: demo caption
                    id:
                      type: string
                      format: uuid
                      description: Unique identifier of the file
                      example: e33e5398-814a-47d6-902a-466ba120ce45
              note:
                type: string
                description: Note or description for the file (required for file, audio and image messages)
                example: demo note
              order:
                description: Order data (required for order messages only)
                allOf:
                  - $ref: '#/components/schemas/MessageOrder'
              product:
                description: Product data (required for product messages only)
                allOf:
                  - $ref: '#/components/schemas/MessageProduct'
              transport_attachments:
                description: Attachments specific to a transport layer
                nullable: true
                allOf:
                  - $ref: '#/components/schemas/MessageTransportAttachments'
              quote_message_id:
                type: integer
                format: int64
                description: ID of the quoted message (required for text messages only)
                example: 42
  responses:
    EmptyResponse:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties: {}
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            properties:
              errors:
                description: List of errors
                items:
                  type: string
                type: array
            type: object
    BotsListResponse:
      description: List of bots
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Bot'
    ChannelsListResponse:
      description: Array of channel objects
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ChannelListResponseItem'
    ChatsListResponse:
      description: Array of chat objects
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ChatsListResponseItem'
    CommandsResponse:
      description: List of commands
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Command'
    CommandCreateResponse:
      description: Response after creating a command
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandCreate'
    CustomersListResponse:
      description: List of customers
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Customer'
    DialogsListResponse:
      description: List of dialogs
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DialogListResponseItem'
    DialogAssignResponse:
      description: Result of dialog assignment operation
      content:
        application/json:
          schema:
            type: object
            required:
              - responsible
              - is_reassign
            properties:
              is_reassign:
                type: boolean
                nullable: false
                example: true
                description: Indicates if the assignment is a reassignment
              left_user_id:
                type: integer
                format: int64
                nullable: true
                description: Unique identifier of the user in chats who left the dialog, if applicable
              previous_responsible:
                allOf:
                  - $ref: '#/components/schemas/Responsible'
                nullable: true
                description: Previously responsible user before reassignment
              responsible:
                allOf:
                  - $ref: '#/components/schemas/Responsible'
                nullable: false
                description: Currently responsible user for the dialog
    DialogUnassignResponse:
      description: Result of dialog unassignment operation
      content:
        application/json:
          schema:
            type: object
            properties:
              previous_responsible:
                allOf:
                  - $ref: '#/components/schemas/Responsible'
                nullable: true
                description: Previously responsible user before unassignment
    CreateDialogResponse:
      description: Result of dialog creation
      content:
        application/json:
          schema:
            type: object
            required:
              - id
              - created_at
            properties:
              created_at:
                description: Date and time in RFC 3339 format with microseconds
                example: 2006-01-02T15:04:05.999999Z07:00
                type: string
                format: date-time
              id:
                type: integer
                format: int64
                example: 1
                description: Unique identifier of the created dialog
    FullFileResponse:
      description: Successful response containing full file information including the downloadable URL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FileWithUrl'
    UploadResponse:
      description: Successful response containing metadata of the uploaded file
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/File'
    ChatMemberListResponse:
      description: A list of chat members with their states and attributes
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ChatMemberListResponseItem'
    UserListResponse:
      description: A list of users with their profile information
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/UserListResponseItem'
    MessageListResponse:
      description: List of messages
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MessageListResponseItem'
    SendMessageResponse:
      description: List of messages
      content:
        application/json:
          schema:
            type: object
            required:
              - message_id
              - time
            properties:
              message_id:
                type: integer
                format: int64
                example: 1
                description: Unique identifier of the message
              time:
                type: string
                format: date-time
                example: 2006-01-02T15:04:05.999999Z07:00
  schemas:
    Boolean:
      description: Boolean type
      type: string
      enum:
        - '1'
        - '0'
        - 'true'
        - 'false'
    Roles:
      description: Bot role types array
      type: array
      items:
        $ref: '#/components/schemas/Role'
    Role:
      description: Bot role type
      type: string
      enum:
        - responsible
        - distributor
        - hidden
      example: responsible
    Bot:
      description: Bot information
      type: object
      required:
        - id
        - name
        - client_id
        - roles
        - created_at
        - is_active
        - is_self
        - is_system
      properties:
        avatar_url:
          type: string
          format: uri
          example: https://avatar.demo/avatar-url
          description: Public URL of the bot's avatar image
        client_id:
          type: string
          example: demo-bot-id
          description: Unique external client identifier of the bot
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        deactivated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the bot
        is_active:
          type: boolean
          example: true
          description: Indicates whether the bot is currently active
        is_self:
          type: boolean
          example: true
          description: Indicates whether this bot is the one currently authenticated
        is_system:
          type: boolean
          example: false
          description: Indicates whether this bot is a system-level bot
        name:
          type: string
          example: demo-bot
          description: Human-readable name of the bot
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
          description: List of roles assigned to the bot
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
    ChannelType:
      description: Type of channel used for communication
      type: string
      enum:
        - telegram
        - tiktok
        - fbmessenger
        - viber
        - whatsapp
        - skype
        - vk
        - instagram
        - consultant
        - yandex_chat
        - odnoklassniki
        - max
        - ozon
        - wildberries
        - yandex_market
        - mega_market
        - avito
        - drom
        - youla
        - custom
      example: telegram
    ChannelListResponseItem:
      description: Communication channel used by a bot
      type: object
      required:
        - id
        - type
        - created_at
        - activated_at
        - is_active
        - settings
      properties:
        activated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        deactivated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the channel
        is_active:
          type: boolean
          example: true
          description: Indicates whether the channel is currently active
        name:
          type: string
          example: Example Channel
          nullable: true
          description: Optional human-readable name of the channel
        settings:
          allOf:
            - $ref: '#/components/schemas/ChannelSettings'
          description: Configuration settings specific to the channel type
        type:
          allOf:
            - $ref: '#/components/schemas/ChannelType'
          description: Type of the communication channel
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
    ChannelSettings:
      description: Configuration options and capabilities for a specific communication channel
      type: object
      properties:
        text:
          $ref: '#/components/schemas/TextMessageSetting'
        audio:
          $ref: '#/components/schemas/AudioMessageSetting'
        file:
          $ref: '#/components/schemas/FileMessageSetting'
        image:
          $ref: '#/components/schemas/ImageMessageSetting'
        order:
          $ref: '#/components/schemas/OrderMessageSetting'
        product:
          $ref: '#/components/schemas/ProductMessageSetting'
        customer_external_id:
          $ref: '#/components/schemas/CustomerExternalId'
        deferred_phone_template_send:
          description: Send phone template messages through deferred identity resolution
          type: boolean
        sending_policy:
          $ref: '#/components/schemas/SendingPolicy'
        status:
          $ref: '#/components/schemas/StatusSetting'
        suggestions:
          $ref: '#/components/schemas/Suggestions'
        template:
          $ref: '#/components/schemas/TemplateSetting'
        whatsapp:
          $ref: '#/components/schemas/WAChannelProperties'
        reactions:
          $ref: '#/components/schemas/Reactions'
    AudioMessageSetting:
      description: Support settings for audio messages in the channel
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        max_item_size:
          description: Maximum size allowed for a single audio file in bytes
          format: int64
          type: integer
        max_items_count:
          description: Maximum number of audio attachments allowed per message
          format: int
          type: integer
    FileMessageSetting:
      description: File messages support
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        editing:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        max_item_size:
          description: Maximum file size to send
          format: int64
          type: integer
        max_items_count:
          description: Maximum number of file attachments per message
          format: int
          type: integer
        note_max_chars_count:
          description: Maximum number of characters in a file message annotation
          format: uint16
          type: integer
    ImageMessageSetting:
      description: Media messages support
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        editing:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        max_item_size:
          description: Maximum image size to send
          format: int64
          type: integer
        max_items_count:
          description: Maximum number of media attachments per message
          format: int
          type: integer
        note_max_chars_count:
          description: Maximum number of characters in a media message annotation
          format: uint16
          type: integer
    TextMessageSetting:
      description: Text messages support
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        editing:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        max_chars_count:
          description: Maximum number of characters in a text message
          format: uint16
          type: integer
        markup_formats:
          description: Supported text markup formats. Empty or absent list means markup is not supported.
          type: array
          items:
            $ref: '#/components/schemas/MarkupFormat'
    MarkupFormat:
      description: Supported text markup format
      type: string
      enum:
        - bold
        - italic
        - underline
        - strikethrough
        - inline_monospace
        - block_monospace
        - link
      example: bold
    OrderMessageSetting:
      description: Order messages support
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        editing:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
    ProductMessageSetting:
      description: Product messages support
      type: object
      properties:
        creating:
          $ref: '#/components/schemas/ChannelFeature'
        deleting:
          $ref: '#/components/schemas/ChannelFeature'
        editing:
          $ref: '#/components/schemas/ChannelFeature'
        reaction:
          $ref: '#/components/schemas/ChannelFeature'
        quoting:
          $ref: '#/components/schemas/ChannelFeature'
    ChannelFeature:
      description: Support for operation with messages of the given type
      type: string
      enum:
        - none
        - receive
        - send
        - both
      example: both
    CustomerExternalId:
      description: Support for external customer identifiers
      type: string
      enum:
        - any
        - phone
        - uid
      example: phone
    SendingPolicyAfterReplyTimeout:
      description: Types of messages to send after response time expires
      type: string
      enum:
        - 'no'
        - template
      example: 'no'
    SendingPolicyNewCustomer:
      description: Types of messages to send to a new customer
      type: string
      enum:
        - 'no'
        - template
        - text
      example: 'no'
    SendingPolicyOutgoing:
      description: Outgoing message support
      type: string
      enum:
        - allowed
        - restricted
      example: allowed
    SendingPolicy:
      description: Message sending policy
      type: object
      properties:
        after_reply_timeout:
          $ref: '#/components/schemas/SendingPolicyAfterReplyTimeout'
        new_customer:
          $ref: '#/components/schemas/SendingPolicyNewCustomer'
        outgoing:
          $ref: '#/components/schemas/SendingPolicyOutgoing'
    StatusSetting:
      description: Transmitting message status information
      type: object
      properties:
        delivered:
          $ref: '#/components/schemas/ChannelFeature'
        read:
          $ref: '#/components/schemas/ChannelFeature'
    Suggestions:
      description: Support for quick response types
      type: object
      properties:
        email:
          $ref: '#/components/schemas/ChannelFeature'
        phone:
          $ref: '#/components/schemas/ChannelFeature'
        text:
          $ref: '#/components/schemas/ChannelFeature'
        url:
          $ref: '#/components/schemas/ChannelFeature'
    TemplateSetting:
      description: Support for message templates
      type: object
      properties:
        creation:
          description: Support for creating templates in the system
          example: true
          type: boolean
        sending:
          description: Support for sending templates from the system
          example: true
          type: boolean
    WAChannelQuality:
      description: WhatsApp channel quality
      type: string
      enum:
        - high
        - medium
        - low
      example: high
    WAChannelStatus:
      description: WhatsApp channel status
      type: string
      enum:
        - connected
        - flagged
        - offline
        - pending
        - restricted
      example: connected
    WAChannelProperties:
      description: WhatsApp channel properties
      type: object
      properties:
        channel_quality:
          allOf:
            - $ref: '#/components/schemas/WAChannelQuality'
        channel_status:
          allOf:
            - $ref: '#/components/schemas/WAChannelStatus'
        tier:
          format: int
          type: integer
    Reactions:
      description: Support for working with reactions for messages
      type: object
      properties:
        dictionary:
          description: Dictionary of available reactions
          type: array
          items:
            type: string
        max_count:
          description: Maximum number of reactions added from the system
          format: int64
          type: integer
    ChatsListResponseItem:
      description: Represents a chat with additional metadata such as creation and update timestamps
      type: object
      allOf:
        - $ref: '#/components/schemas/Chat'
        - $ref: '#/components/schemas/ChatTimestamps'
    ChatTimestamps:
      description: Represents dates and times of creation and last update of the chat
      type: object
      properties:
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
    Chat:
      description: Represents a communication thread between users and/or a customer within a specific channel
      type: object
      required:
        - id
        - not_read_messages
        - unread
      properties:
        author_id:
          type: integer
          format: int64
          example: 100
          deprecated: true
          description: ID of the user who initiated the chat
        avatar:
          type: string
          example: https://avatar.demo/chat-avatar
          description: URL of the chat's avatar image
        channel:
          allOf:
            - $ref: '#/components/schemas/Channel'
          nullable: true
          description: The communication channel (e.g., Telegram, Viber) associated with this chat
        customer:
          allOf:
            - $ref: '#/components/schemas/Actor'
          nullable: true
          description: The customer participating in the chat, if any
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the chat
        last_activity:
          description: Date and time in RFC 3339 format
          example: 2006-01-02T15:04:05Z07:00
          type: string
          format: date-time
        last_dialog:
          allOf:
            - $ref: '#/components/schemas/Dialog'
          description: The most recent dialog in the chat
        last_message:
          allOf:
            - $ref: '#/components/schemas/Message'
          nullable: true
          description: The latest message in the chat, including system or service messages
        last_user_message:
          allOf:
            - $ref: '#/components/schemas/LastUserMessage'
          nullable: true
          description: The most recent message sent by a user in the chat
        name:
          type: string
          example: Example Chat
          description: Display name of the chat
        not_read_messages:
          type: integer
          format: int64
          example: 12
          description: Number of unread messages in the chat
        reply_deadline:
          description: Date and time in RFC 3339 format
          example: 2006-01-02T15:04:05Z07:00
          type: string
          format: date-time
        unread:
          type: boolean
          example: true
          description: Indicates whether any user has unread messages in this chat
        waiting_level:
          type: string
          enum:
            - warning
            - danger
            - none
          nullable: true
          description: Current urgency level of the chat based on business logic (e.g., SLA violations).
        waiting_level_transition_time:
          description: Date and time in RFC 3339 format
          example: 2006-01-02T15:04:05Z07:00
          type: string
          format: date-time
          nullable: true
    LastUserMessage:
      description: The most recent message sent by a user in the chat
      type: object
      nullable: true
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the last user message
    Actor:
      description: Chat actor
      type: object
      properties:
        id:
          description: Unique identifier of the user in chats
          example: 56
          format: int64
          type: integer
        available:
          description: User status indicator (for user of the user type only)
          example: false
          type: boolean
        avatar:
          description: User avatar
          example: https://avatar.demo/demo-avatar
          format: uri
          type: string
        email:
          description: User email (for customer type user only)
          example: demo@user.demo
          format: email
          type: string
        external_id:
          description: External identifier of a user
          example: eid3459
          type: string
        first_name:
          description: User name (for customer and user types only)
          example: John
          type: string
        is_blocked:
          description: User blocking indicator (for customer type user only)
          example: false
          type: boolean
        is_system:
          description: System user indicator (for bot type user only)
          example: true
          type: boolean
        is_technical_account:
          description: Technical account indicator (for user of the user type only)
          example: false
          type: boolean
        last_name:
          description: User last name (for customer and user types only)
          example: Doe
          type: string
        name:
          description: User nickname
          example: John D.
          type: string
        phone:
          description: User phone number
          example: 541-392-2618
          type: string
        type:
          type: string
          enum:
            - user
            - bot
            - customer
            - channel
          nullable: false
          example: user
        username:
          description: User name (for customer type user only)
          example: john_doe
          type: string
      required:
        - id
        - external_id
        - type
        - name
    Message:
      description: Message object representing a single chat message
      type: object
      required:
        - actions
        - chat_id
        - id
        - is_edit
        - is_read
        - scope
        - status
        - time
        - type
      properties:
        action:
          allOf:
            - $ref: '#/components/schemas/SystemAction'
          description: System-level action represented by the message
          nullable: true
        actions:
          type: array
          description: List of interactive actions associated with the message
          items:
            $ref: '#/components/schemas/MessageAction'
        chat_id:
          type: integer
          format: int64
          description: ID of the chat this message belongs to
          example: 1
        content:
          type: string
          description: Text content of the message
          example: Hi there!
          nullable: true
        dialog:
          allOf:
            - $ref: '#/components/schemas/MessageDialog'
          description: Optional dialog related to the message
          nullable: true
        error:
          allOf:
            - $ref: '#/components/schemas/MessageError'
          description: Error info related to message sending or processing
          nullable: true
        from:
          allOf:
            - $ref: '#/components/schemas/Actor'
          description: Actor who sent the message
        id:
          type: integer
          format: int64
          description: Unique identifier of the message
          example: 1
        is_edit:
          type: boolean
          description: Indicates whether the message was edited
          example: true
        is_read:
          type: boolean
          description: Indicates whether the message was read
          example: true
        items:
          type: array
          description: List of attached files
          items:
            $ref: '#/components/schemas/MessageFile'
        note:
          type: string
          description: Optional internal note or comment for the message
          example: Nice cats
          nullable: true
        order:
          allOf:
            - $ref: '#/components/schemas/MessageOrder'
          description: Optional order data linked to the message
          nullable: true
        product:
          allOf:
            - $ref: '#/components/schemas/MessageProduct'
          description: Optional product data referenced in the message
          nullable: true
        quote:
          allOf:
            - $ref: '#/components/schemas/QuoteMessage'
          description: Quoted message, if this is a reply
          nullable: true
        responsible:
          allOf:
            - $ref: '#/components/schemas/Actor'
          description: User responsible for this message or task
          nullable: true
        scope:
          allOf:
            - $ref: '#/components/schemas/MessageScope'
          description: Scope of the message
        status:
          allOf:
            - $ref: '#/components/schemas/MessageStatus'
          description: Current status of the message
        template_code:
          type: string
          description: Template code for a template message
        time:
          type: string
          format: date-time
          description: Timestamp when the message was created
          example: 2006-01-02T15:04:05Z07:00
          nullable: false
        transport_attachments:
          allOf:
            - $ref: '#/components/schemas/MessageTransportAttachments'
          description: Attachments specific to a transport layer
          nullable: true
        type:
          allOf:
            - $ref: '#/components/schemas/MessageType'
          description: Type of the message
        user:
          allOf:
            - $ref: '#/components/schemas/Actor'
          description: User associated with the message
          nullable: true
    MessageFile:
      description: Attached message file
      type: object
      properties:
        id:
          description: Unique identifier (UUID) of the attached file
          example: c425d178-eb6f-11ec-8ea0-0242ac120002
          format: uuid
          type: string
        caption:
          description: Text description of the media attachment
          example: demo caption
          type: string
        duration:
          description: Audio recording duration (for audio type messages only)
          example: 345
          format: int
          type: integer
        size:
          description: Attachment size (in bytes)
          example: 34534
          format: int
          type: integer
        height:
          description: Image height in pixels (for image type messages only)
          example: 1080
          format: int
          type: integer
        width:
          description: Image width in pixels (for image type messages only)
          example: 1920
          format: int
          type: integer
        histogram:
          allOf:
            - $ref: '#/components/schemas/Histogram'
        kind:
          allOf:
            - $ref: '#/components/schemas/FileType'
        preview_url:
          description: URL of the file to upload
          example: https://url.demo/demo-url
          format: uri
          type: string
        transcription:
          type: string
          description: Transcription of the uploaded file
          example: Sample transcription
        type:
          description: Attachment type
          example: application/pdf
          type: string
    MessageType:
      description: Type of message
      type: string
      enum:
        - text
        - system
        - command
        - order
        - product
        - file
        - image
        - audio
      example: text
    Histogram:
      type: array
      description: Sound diagram (for audio type messages only)
      example:
        - 1
        - 34
        - 23
        - 4
        - 32
        - 34
        - 23
        - 12
        - 93
        - 4
      items:
        format: int
        type: integer
    FileType:
      type: string
      description: File type
      enum:
        - none
        - image
        - video
        - file
        - audio
      example: file
    MessageDialog:
      description: Message dialog
      type: object
      properties:
        id:
          description: Dialog identifier
          example: 9
          format: int64
          type: integer
      required:
        - id
    MessageError:
      description: Message error details (only for messages with status `failed`)
      type: object
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/MessageErrorCode'
        message:
          description: Text description of error
          example: error malformed response
          type: string
      required:
        - code
    MessageErrorCode:
      description: Message error code
      type: string
      enum:
        - unknown
        - network_error
        - malformed_response
        - async_send_timeout
        - general
        - customer_not_exists
        - reply_timed_out
        - spam_suspicion
        - access_restricted
      example: malformed_response
    QuoteMessage:
      description: Quoted message
      type: object
      required:
        - id
        - time
        - type
      properties:
        id:
          description: Identifier of the quoted message
          example: 45
          format: int64
          type: integer
        content:
          description: Message text
          example: quote content
          type: string
        from:
          $ref: '#/components/schemas/Actor'
        items:
          description: Media attachments of the quoted message
          items:
            $ref: '#/components/schemas/MessageFile'
          type: array
        time:
          type: string
          format: date-time
          description: Message sending time
          example: 2006-01-02T15:04:05Z07:00
          nullable: false
        type:
          allOf:
            - $ref: '#/components/schemas/MessageType'
    MessageTransportAttachments:
      description: Transport attachments
      type: object
      properties:
        suggestions:
          description: Quick responses
          items:
            $ref: '#/components/schemas/Suggestion'
          type: array
    Suggestion:
      description: Quick response suggestion
      type: object
      properties:
        payload:
          description: Quick response payload
          example: https://demo-payload.demo
          type: string
        title:
          description: Quick response name
          example: phone number
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/SuggestionType'
    SuggestionType:
      type: string
      description: Quick response type
      enum:
        - text
        - email
        - phone
        - url
      example: phone
    MessageScope:
      description: Message scope
      type: string
      enum:
        - undefined
        - public
        - private
      example: public
    MessageStatus:
      type: string
      description: Message status
      enum:
        - undefined
        - received
        - sending
        - sent
        - failed
        - seen
      example: seen
    MessageProduct:
      description: Describes a product mentioned in a message
      type: object
      properties:
        id:
          description: Product identifier
          example: 56
          format: uint64
          type: integer
        article:
          description: Product description
          example: 324-DFT-495
          maxLength: 128
          type: string
        cost:
          $ref: '#/components/schemas/Cost'
        img:
          description: Product image URL
          example: https://image.demo/demo-image
          format: uri
          maxLength: 2048
          type: string
        name:
          type: string
          description: Product name
          example: demo product
          maxLength: 255
          minLength: 1
        unit:
          description: Units of measure of the product
          maxLength: 16
          type: string
        url:
          description: Product URL
          example: https://product.demo/demo-product
          format: uri
          maxLength: 2048
          type: string
      required:
        - id
        - name
    MessageOrder:
      description: Represents the details of an order within a message
      type: object
      properties:
        external_id:
          description: External identifier of an order
          example: 56
          format: int64
          type: integer
        cost:
          $ref: '#/components/schemas/Cost'
        date:
          description: Order creation date
          example: '2021-12-29T14:18:37.051393Z'
          format: date-time
          type: string
        delivery:
          $ref: '#/components/schemas/MessageOrderDelivery'
        discount:
          $ref: '#/components/schemas/Cost'
        items:
          description: Array of order items
          items:
            $ref: '#/components/schemas/MessageOrderItem'
          type: array
        number:
          description: Order number
          example: '23546'
          maxLength: 255
          type: string
        payments:
          description: Payments array
          items:
            $ref: '#/components/schemas/MessageOrderPayment'
          type: array
        status:
          allOf:
            - $ref: '#/components/schemas/MessageOrderStatus'
        url:
          description: Order URL
          example: https://url.demo/demo-url
          format: uri
          maxLength: 2048
          type: string
    Cost:
      description: Represents a monetary value with its corresponding currency
      type: object
      properties:
        currency:
          description: Currency code
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: Numerical value of the cost
          example: 256
          format: double
          minimum: 0
          type: number
      required:
        - currency
        - value
    MessageOrderDelivery:
      description: Order delivery information
      type: object
      properties:
        address:
          description: Delivery address
          example: 2641 Webster St Berkeley, California(CA), 94705
          type: string
        comment:
          description: Delivery comment
          example: demo delivery comment
          type: string
        name:
          description: Delivery method name
          example: dhl
          type: string
        price:
          $ref: '#/components/schemas/Cost'
    MessageOrderItem:
      description: Order product
      type: object
      properties:
        external_id:
          description: External identifier of a product
          example: 45
          format: int64
          type: integer
        img:
          description: Product image
          example: https://order-image.demo/demo-order-image
          format: uri
          maxLength: 2048
          type: string
        name:
          description: Product name
          example: demo order item
          maxLength: 255
          type: string
        price:
          $ref: '#/components/schemas/Cost'
        quantity:
          allOf:
            - $ref: '#/components/schemas/Quantity'
        url:
          description: Product URL
          example: https://order-item.demo/demo-order-item
          format: uri
          maxLength: 2048
          type: string
    MessageOrderPayment:
      description: Order payment information
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Cost'
        name:
          description: Payment name
          example: paid
          type: string
        status:
          $ref: '#/components/schemas/MessageOrderPaymentStatus'
    MessageOrderPaymentStatus:
      description: Order payment status
      type: object
      properties:
        name:
          description: Payment name
          example: demo-payment-status
          type: string
        payed:
          description: Payment execution indicator
          example: true
          type: boolean
    Quantity:
      description: Quantity
      type: object
      properties:
        unit:
          description: Units of measure
          example: pcs
          maxLength: 16
          type: string
        value:
          description: Quantitative value
          example: 5
          format: double
          minimum: 0
          type: number
    MessageOrderStatus:
      description: Order status
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/MessageOrderStatusCode'
        name:
          description: Status name
          example: approval
          maxLength: 255
          type: string
    MessageOrderStatusCode:
      description: Status code
      type: string
      enum:
        - new
        - approval
        - assembling
        - delivery
        - complete
        - cancel
      example: approval
    MessageAction:
      description: Defines possible actions that can be performed on a message
      type: string
      enum:
        - edit
        - delete
        - quote
      example: edit
    Dialog:
      description: Dialog object
      type: object
      required:
        - id
        - created_at
      properties:
        id:
          type: integer
          format: int64
          example: 1
        created_at:
          description: Date and time in RFC 3339 format
          example: 2006-01-02T15:04:05Z07:00
          type: string
          format: date-time
        closed_at:
          description: Date and time in RFC 3339 format
          example: 2006-01-02T15:04:05Z07:00
          type: string
          format: date-time
          nullable: true
        assigned_at:
          type: string
          format: date-time
          nullable: true
          example: 2006-01-02T15:04:05Z07:00
        responsible:
          allOf:
            - $ref: '#/components/schemas/Actor'
          nullable: true
        utm:
          allOf:
            - $ref: '#/components/schemas/Utm'
          nullable: true
    Utm:
      description: UTM parameters for tracking marketing campaigns
      type: object
      properties:
        campaign:
          description: Campaign
          example: spring_sale
          maxLength: 255
          minLength: 1
          type: string
        content:
          description: Ad content
          example: textlink
          maxLength: 255
          minLength: 1
          type: string
        medium:
          description: Medium
          example: cpc
          maxLength: 255
          minLength: 1
          type: string
        source:
          description: Source
          example: Google
          maxLength: 255
          minLength: 1
          type: string
        term:
          description: Keyword
          example: running
          maxLength: 255
          minLength: 1
          type: string
    SystemAction:
      description: System action of the message (for system type messages only)
      type: string
      enum:
        - dialog_opened
        - dialog_closed
        - user_joined
        - user_left
        - dialog_assign
        - customer_blocked
        - customer_unblocked
        - dialog_unassign
        - dialog_tag_added
        - dialog_tag_removed
      example: user_joined
    Channel:
      description: Represents a communication channel used by a bot
      type: object
      required:
        - id
        - avatar
        - type
        - transport_id
        - settings
        - is_active
      properties:
        avatar:
          type: string
          format: uri
          example: https://avatar.demo/demo-avatar
          description: URI of the channel's custom avatar image
          nullable: false
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the channel
        is_active:
          type: boolean
          example: true
          description: Indicates whether the channel is currently active
        name:
          type: string
          example: Example Channel
          nullable: true
          description: Optional human-readable name of the channel
        settings:
          allOf:
            - $ref: '#/components/schemas/ChannelSettings'
          description: Configuration settings specific to the channel type
        transport_id:
          type: integer
          format: int64
          nullable: false
          example: 12
          description: Identifier of the underlying transport system used by the channel
        type:
          allOf:
            - $ref: '#/components/schemas/ChannelType'
          description: Type of the communication channel
    Command:
      type: object
      description: Represents a single bot command with metadata.
      required:
        - created_at
        - description
        - id
        - name
      properties:
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        description:
          type: string
          example: demo-description
          description: Human-readable description of the command.
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the command.
        name:
          type: string
          example: demo-name
          description: Unique command name, used for execution or identification
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
    CommandCreate:
      description: Represents a created command with metadata
      allOf:
        - $ref: '#/components/schemas/Command'
        - type: object
          properties:
            created_at:
              description: Date and time in RFC 3339 format
              example: 2006-01-02T15:04:05Z07:00
              type: string
              format: date-time
            updated_at:
              description: Date and time in RFC 3339 format
              example: 2006-01-02T15:04:05Z07:00
              type: string
              format: date-time
          required:
            - created_at
    Customer:
      description: Customer object
      type: object
      required:
        - id
        - created_at
        - is_blocked
      properties:
        id:
          type: integer
          format: int64
          example: 1
        external_id:
          type: string
          nullable: true
          example: e3456
        channel_id:
          type: integer
          format: int64
          nullable: true
          example: 5
        username:
          type: string
          nullable: true
          example: demo_user
        first_name:
          type: string
          nullable: true
          example: Thomas
        last_name:
          type: string
          nullable: true
          example: Smith
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        revoked_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        avatar_url:
          type: string
          nullable: true
          example: https://avatar.demo/demo-avatar
        profile_url:
          type: string
          nullable: true
          example: https://profile.demo/demo-profile
        country:
          type: string
          nullable: true
          example: US
        language:
          type: string
          nullable: true
          example: US
        phone:
          type: string
          nullable: true
          example: 928-970-2685
        email:
          type: string
          nullable: true
          example: demo@customer.demo
        is_blocked:
          type: boolean
          nullable: false
          example: true
        utm:
          allOf:
            - $ref: '#/components/schemas/Utm'
          nullable: true
    Responsible:
      description: Entity responsible for the dialog (user or bot)
      type: object
      required:
        - id
        - type
      properties:
        assigned_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        external_id:
          type: string
          nullable: true
          description: External identifier for the responsible entity
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the responsible entity
        type:
          type: string
          enum:
            - user
            - bot
          description: Type of the responsible entity
    Tag:
      description: Tag assigned to a dialog or entity
      type: object
      required:
        - name
        - color_code
      properties:
        color_code:
          allOf:
            - $ref: '#/components/schemas/ColorCode'
          description: Color code associated with the tag
        name:
          type: string
          example: Important
          description: Name of the tag
    ColorCode:
      description: Code of tag color
      type: string
      enum:
        - light-red
        - light-blue
        - light-green
        - light-orange
        - light-gray
        - light-grayish-blue
        - red
        - blue
        - green
        - orange
        - gray
        - grayish-blue
      example: grayish-blue
    DialogListResponseItem:
      description: Dialog item in the list response
      type: object
      required:
        - chat_id
        - created_at
        - id
        - is_active
        - is_assigned
      properties:
        begin_message_id:
          type: integer
          format: int64
          nullable: true
          example: 32
          description: ID of the first message in the dialog
        bot_id:
          type: integer
          format: int64
          nullable: true
          example: 20
          description: ID of the bot assigned to the dialog, if any
        chat_id:
          type: integer
          format: int64
          example: 3
          description: ID of the chat this dialog belongs to
        closed_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        ending_message_id:
          type: integer
          format: int64
          nullable: true
          example: 39
          description: ID of the last message in the dialog
        id:
          type: integer
          format: int64
          example: 1
          description: Unique identifier of the dialog
        is_active:
          type: boolean
          example: false
          description: Indicates if the dialog is currently active
        is_assigned:
          type: boolean
          example: true
          description: Indicates if the dialog is assigned to someone
        responsible:
          allOf:
            - $ref: '#/components/schemas/Responsible'
          description: Current responsible entity for the dialog
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: List of tags associated with the dialog
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        utm:
          allOf:
            - $ref: '#/components/schemas/Utm'
          description: UTM parameters associated with the dialog
    FileWithUrl:
      description: Uploaded file metadata with a temporary access URL
      type: object
      allOf:
        - $ref: '#/components/schemas/File'
        - type: object
          properties:
            url:
              description: Direct URL for downloading or accessing the uploaded file
              example: https://file.demo/demo-file
              type: string
              format: uri
    File:
      description: Metadata and processing status of an uploaded file
      type: object
      required:
        - id
        - type
        - size
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the file
          example: e33e5398-814a-47d6-902a-466ba120ce45
        size:
          type: integer
          description: Size of the file in bytes
          example: 102384
        transcription:
          type: string
          description: Optional text transcription of the file content, if applicable
          example: Demo transcription
          nullable: true
        transcription_status:
          allOf:
            - $ref: '#/components/schemas/FileTranscriptionStatus'
          description: Status of the file transcription process
        type:
          $ref: '#/components/schemas/FileType'
    FileTranscriptionStatus:
      type: string
      description: Current status of the file transcription process
      enum:
        - in_progress
        - ready
        - error
      example: ready
    ChatMemberListResponseItem:
      type: object
      description: Chat member object containing user ID, chat ID, membership state and timestamps
      required:
        - chat_id
        - created_at
        - id
        - is_author
        - state
        - user_id
      properties:
        chat_id:
          type: integer
          format: int64
          description: ID of the chat the user is a member of
          example: 123
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        id:
          type: integer
          format: int64
          description: Unique ID of the chat membership record
          example: 123
        is_author:
          type: boolean
          deprecated: true
          description: Indicates whether the user is the author of the chat
          example: false
        state:
          type: string
          description: Membership state of the user in the chat
          enum:
            - active
            - kicked
            - leaved
          example: active
        user_id:
          type: integer
          format: int64
          description: Unique identifier of the user in chats
          example: 123
    UserListResponseItem:
      type: object
      description: User object containing profile data, activity status and timestamps
      required:
        - id
        - created_at
        - available
        - is_online
        - connected
        - is_active
        - is_technical_account
      properties:
        avatar_url:
          type: string
          format: uri
          description: URL of the user's avatar
          example: https://avatar.demo/demo-avatar
        available:
          type: boolean
          description: Indicates if the user is available for communication
          example: true
        connected:
          type: boolean
          description: Indicates if the user has ever connected to the system
          example: true
        created_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
        external_id:
          type: string
          description: External identifier of the user (e.g. from external system)
          example: user_324
        first_name:
          type: string
          description: First name of the user
          example: John
        id:
          type: integer
          format: int64
          description: Internal user ID
          example: 1
        is_active:
          type: boolean
          description: Flag indicating if the user is marked as active
          example: true
        is_online:
          type: boolean
          description: Flag indicating if the user is currently online
          example: true
        is_technical_account:
          type: boolean
          description: Indicates if the user is a technical (system) account
          example: false
        last_name:
          type: string
          description: Last name of the user
          example: Doe
        revoked_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        updated_at:
          description: Date and time in RFC 3339 format with microseconds
          example: 2006-01-02T15:04:05.999999Z07:00
          type: string
          format: date-time
          nullable: true
        username:
          type: string
          description: Username or login name of the user
          example: demo-username
    MessageListResponseItem:
      description: Represents a message item in a message list
      type: object
      allOf:
        - $ref: '#/components/schemas/Message'
        - type: object
          required:
            - created_at
          properties:
            channel_id:
              type: integer
              format: int64
              example: 1
              description: ID of the channel where the message was sent
            channel_sent_at:
              description: Date and time in RFC 3339 format with microseconds
              example: 2006-01-02T15:04:05.999999Z07:00
              type: string
              format: date-time
              nullable: true
            created_at:
              description: Date and time in RFC 3339 format with microseconds
              example: 2006-01-02T15:04:05.999999Z07:00
              type: string
              format: date-time
            updated_at:
              description: Date and time in RFC 3339 format with microseconds
              example: 2006-01-02T15:04:05.999999Z07:00
              type: string
              format: date-time
              nullable: true
    SendMessageRequestBody:
      type: object
      description: Represents the payload of a message, including content, attachments, and related metadata depending on the message type
      required:
        - chat_id
        - scope
      properties:
        chat_id:
          type: integer
          format: int64
          description: ID of the chat where the message is being sent
          example: 123
        content:
          type: string
          description: Message text content (required for text messages only)
          example: Hello!
        items:
          type: array
          description: File attachments (required for file, audio and image messages)
          items:
            type: object
            description: File attachment
            required:
              - id
            properties:
              caption:
                type: string
                description: Caption for the file
                example: demo caption
              id:
                type: string
                format: uuid
                description: Unique identifier of the file
                example: e33e5398-814a-47d6-902a-466ba120ce45
        note:
          type: string
          description: Note or description for the file (required for file, audio and image messages)
          example: demo note
        order:
          description: Order data (required for order messages only)
          allOf:
            - $ref: '#/components/schemas/MessageOrder'
        product:
          description: Product data (required for product messages only)
          allOf:
            - $ref: '#/components/schemas/MessageProduct'
        quote_message_id:
          type: integer
          format: int64
          description: ID of the quoted message (required for text messages only)
          example: 42
        scope:
          allOf:
            - $ref: '#/components/schemas/MessageScope'
          description: Scope of the message (e.g., user, system)
          example: user
        type:
          allOf:
            - $ref: '#/components/schemas/MessageType'
          description: Type of the message (e.g. text, file, order, product)
          example: text
        transport_attachments:
          allOf:
            - $ref: '#/components/schemas/MessageTransportAttachments'
          nullable: true
        mass_communication:
          type: boolean
          description: Marks the message as part of a mass mailing. A message sent with this flag does not open a dialog in the chat and does not update the chat’s last_activity. Chats initiated by such messages, as well as the WebSocket events related to them, are returned only when include_mass_communication is explicitly enabled (use the include_mass_communication query parameter for REST lists and the include_mass_communication option for WebSocket connections)
    UpdateCommandRequestBody:
      description: Represents a request body for updating a new command
      type: object
      properties:
        name:
          description: Unique identifier for the command
          example: Demo command name
          type: string
        description:
          description: Human-readable description of the command's purpose or behavior
          example: Demo command description
          type: string
          maxLength: 64
    CreateCommandRequestBody:
      description: Represents a request body for creating a new command
      type: object
      properties:
        name:
          description: Unique identifier for the command
          example: Demo command name
          type: string
        description:
          description: Human-readable description of the command's purpose or behavior
          example: Demo command description
          type: string
          maxLength: 64
      required:
        - description