openapi: 3.1.0
info:
  title: MG Node Transport API Webhook
  version: 1.0.0
  description: MG Node Transport API Webhook
webhooks:
  events:
    post:
      requestBody:
        $ref: '#/components/requestBodies/WebhookRequest'
      responses:
        '200':
          $ref: '#/components/responses/WebhookResponse'
components:
  schemas:
    BaseWebhookRequestData:
      description: Base structure for webhook request data
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookType'
        meta:
          $ref: '#/components/schemas/WebhookRequestMeta'
      required:
        - type
        - meta
    WebhookRequestData:
      description: Common structure for webhook request data
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WebhookType'
        meta:
          $ref: '#/components/schemas/WebhookRequestMeta'
        data:
          type: object
      discriminator:
        propertyName: type
        mapping:
          message_sent: '#/components/schemas/WebhookMessageSent'
          message_updated: '#/components/schemas/WebhookMessageUpdated'
          message_deleted: '#/components/schemas/WebhookMessageDeleted'
          message_read: '#/components/schemas/WebhookMessageRead'
          template_create: '#/components/schemas/WebhookTemplateCreate'
          template_update: '#/components/schemas/WebhookTemplateUpdate'
          template_delete: '#/components/schemas/WebhookTemplateDelete'
          reaction_add: '#/components/schemas/WebhookMessageReactionAdd'
          reaction_delete: '#/components/schemas/WebhookMessageReactionDelete'
      oneOf:
        - $ref: '#/components/schemas/WebhookMessageSent'
        - $ref: '#/components/schemas/WebhookMessageUpdated'
        - $ref: '#/components/schemas/WebhookMessageDeleted'
        - $ref: '#/components/schemas/WebhookMessageRead'
        - $ref: '#/components/schemas/WebhookTemplateCreate'
        - $ref: '#/components/schemas/WebhookTemplateUpdate'
        - $ref: '#/components/schemas/WebhookTemplateDelete'
        - $ref: '#/components/schemas/WebhookMessageReactionAdd'
        - $ref: '#/components/schemas/WebhookMessageReactionDelete'
      required:
        - type
        - meta
        - data
    WebhookType:
      description: Type of webhook event
      type: string
      enum:
        - message_sent
        - message_updated
        - message_deleted
        - message_read
        - template_create
        - template_update
        - template_delete
        - reaction_add
        - reaction_delete
    WebhookRequestMeta:
      description: Metadata for webhook request
      type: object
      properties:
        timestamp:
          type: number
      required:
        - timestamp
    WebhookMessageSent:
      description: Webhook event for a message being sent
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - message_sent
            data:
              $ref: '#/components/schemas/WebhookMessageSentData'
          required:
            - data
    WebhookMessageUpdated:
      description: Webhook event for a message being updated
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - message_updated
            data:
              $ref: '#/components/schemas/WebhookMessageUpdatedData'
          required:
            - data
    WebhookMessageDeleted:
      description: Webhook event for a message being deleted
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - message_deleted
            data:
              $ref: '#/components/schemas/WebhookMessageDeletedData'
          required:
            - data
    WebhookMessageRead:
      description: Webhook event for a message being read
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - message_read
            data:
              $ref: '#/components/schemas/WebhookMessageReadData'
          required:
            - data
    WebhookTemplateCreate:
      description: Webhook event for a template being created
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - template_create
            data:
              $ref: '#/components/schemas/WebhookTemplateCreateData'
          required:
            - data
    WebhookTemplateUpdate:
      description: Webhook event for a template being updated
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - template_update
            data:
              $ref: '#/components/schemas/WebhookTemplateUpdateData'
          required:
            - data
    WebhookTemplateDelete:
      description: Webhook event for a template being deleted
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - template_delete
            data:
              $ref: '#/components/schemas/WebhookTemplateDeleteData'
          required:
            - data
    WebhookMessageReactionAdd:
      description: Webhook event for a reaction being added to a message
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - reaction_add
            data:
              $ref: '#/components/schemas/WebhookMessageReactionAddData'
          required:
            - data
    WebhookMessageReactionDelete:
      description: Webhook event for a reaction being deleted from a message
      allOf:
        - $ref: '#/components/schemas/BaseWebhookRequestData'
        - type: object
          properties:
            type:
              type: string
              enum:
                - reaction_delete
            data:
              $ref: '#/components/schemas/WebhookMessageReactionDeleteData'
          required:
            - data
    WebhookMessageMeta:
      type: object
      description: Metadata for webhook events
      properties:
        external_user_id:
          description: External identifier of the user
          example: user123
          type: string
        external_chat_id:
          description: External identifier of the chat
          example: chat456
          type: string
        channel_id:
          description: Channel identifier
          example: 789
          format: int64
          type: integer
      required:
        - external_user_id
        - external_chat_id
        - channel_id
    WebhookMessageSentData:
      description: Webhook event data for a message being sent
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - type: object
          properties:
            id:
              description: Unique identifier of the message in MessageGateway. May be absent for deferred message sends before MessageGateway message acknowledgement.
              example: 123456789
              type: number
            type:
              $ref: '#/components/schemas/MessageType'
            content:
              description: Message content
              example: Hello, world!
              type: string
            quote_external_id:
              description: External identifier of the quoted message
              example: quote123
              type: string
            quote_content:
              description: Content of the quoted message
              example: This is a quoted message.
              type: string
            in_app_id:
              description: System identifier for the message
              example: 12345
              format: int32
              type: integer
            user:
              $ref: '#/components/schemas/WebhookUserData'
            bot:
              $ref: '#/components/schemas/WebhookBotData'
            customer:
              $ref: '#/components/schemas/WebhookCustomerData'
            product:
              $ref: '#/components/schemas/MessageProduct'
            order:
              $ref: '#/components/schemas/MessageOrder'
            items:
              description: List of media attachments in the message
              items:
                $ref: '#/components/schemas/WebhookMessageFile'
              type: array
            template:
              $ref: '#/components/schemas/WebhookTemplateInfo'
            attachments:
              $ref: '#/components/schemas/MessageTransportAttachments'
          required:
            - type
            - content
            - quote_external_id
            - quote_content
    WebhookMessageUpdatedData:
      description: Webhook event data for a message being updated
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/MessageType'
            external_message_id:
              type: string
              description: External identifier of the message
              example: msg123
            content:
              description: Message content
              example: Hello, world!
              type: string
            attachments:
              $ref: '#/components/schemas/MessageTransportAttachments'
            product:
              $ref: '#/components/schemas/MessageProduct'
            order:
              $ref: '#/components/schemas/MessageOrder'
          required:
            - type
            - external_message_id
            - content
    WebhookMessageDeletedData:
      description: Webhook event for a message being deleted
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - type: object
          properties:
            external_message_id:
              type: string
              description: External identifier of the message
              example: msg123
          required:
            - external_message_id
    WebhookMessageReadData:
      description: Webhook event for a message being read
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - type: object
          properties:
            external_message_id:
              type: string
              description: External identifier of the message
              example: msg123
          required:
            - external_message_id
    WebhookMessageReactionData:
      description: Webhook event data for message reactions
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - type: object
          properties:
            external_message_id:
              type: string
              description: External identifier of the message
              example: msg123
            new_reaction:
              type: string
              description: New reaction added to the message
              example: 👍
            old_reaction:
              type: string
              description: Old reaction removed from the message
              example: ❤️
            all_reactions:
              type: array
              description: List of all reactions on the message
              items:
                $ref: '#/components/schemas/WebhookReactionItem'
          required:
            - external_message_id
            - all_reactions
    WebhookMessageReactionAddData:
      description: Webhook event data for a reaction being added to a message
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - $ref: '#/components/schemas/WebhookMessageReactionData'
        - type: object
          properties:
            new_reaction:
              type: string
              description: New reaction added to the message
              example: 👍
          required:
            - new_reaction
    WebhookMessageReactionDeleteData:
      description: Webhook event data for a reaction being deleted from a message
      allOf:
        - $ref: '#/components/schemas/WebhookMessageMeta'
        - $ref: '#/components/schemas/WebhookMessageReactionData'
    WebhookTemplateCreateData:
      description: Webhook event data for a template being created
      allOf:
        - $ref: '#/components/schemas/WebhookTemplateContent'
        - type: object
          properties:
            channel_id:
              type: number
              description: Channel identifier
              example: 789
          required:
            - channel_id
    WebhookTemplateUpdateData:
      description: Webhook event data for a template being updated
      allOf:
        - $ref: '#/components/schemas/WebhookTemplateContent'
        - type: object
          properties:
            channel_id:
              type: number
              description: Channel identifier
              example: 789
            code:
              type: string
              description: Template code
              example: template123
          required:
            - channel_id
            - code
    WebhookTemplateDeleteData:
      description: Webhook event data for a template being deleted
      allOf:
        - $ref: '#/components/schemas/WebhookTemplateContent'
        - type: object
          properties:
            channel_id:
              type: number
              description: Channel identifier
              example: 789
            code:
              type: string
              description: Template code
              example: template123
            lang:
              type: string
              description: Language code for the template
              example: en
          required:
            - channel_id
            - code
            - lang
    WebhookEmptyResponse:
      description: Empty response for webhook events that do not require a response
    WebhookSendMessageResponseData:
      description: Response data for sending a message via webhook
      type: object
      properties:
        external_message_id:
          type: string
          description: External identifier of the message
          example: msg123
        external_chat_id:
          type: string
          description: External identifier of the chat
          example: chat456
        external_customer_id:
          type: string
          description: External identifier of the customer
          example: cust789
        error:
          $ref: '#/components/schemas/WebhookMessageSendingError'
        async:
          type: boolean
          description: Indicates if the message was sent asynchronously
          example: true
      required:
        - async
    WebhookTemplateCreateResponseData:
      description: Response data for creating a template via webhook
      type: object
      properties:
        code:
          type: string
          description: Template code
          example: template123
      required:
        - code
    WebhookMessageSendingError:
      description: Represents an error that occurred while sending a message
      type: object
      properties:
        code:
          $ref: '#/components/schemas/MessageErrorCode'
        message:
          type: string
          description: Error message
          example: An error occurred while sending the message
        external_code:
          type: string
          description: External error code, if available
          example: ERR123
      required:
        - code
        - message
    WebhookReactionItem:
      description: Represents a reaction item in the webhook
      type: object
      properties:
        reaction:
          type: string
    WebhookUserData:
      type: object
      description: Represents user data in the webhook
      properties:
        id:
          description: User identifier
          example: 101
          format: int64
          type: integer
        first_name:
          description: User's first name
          example: John
          type: string
        last_name:
          description: User's last name
          example: Doe
          type: string
        avatar:
          description: URL of the user's avatar
          example: https://avatar.demo/user-avatar
          format: uri
          type: string
      required:
        - id
        - first_name
        - last_name
        - avatar
    WebhookBotData:
      type: object
      description: Represents bot data in the webhook
      properties:
        id:
          description: Bot identifier
          example: 202
          format: int64
          type: integer
        name:
          description: Bot name
          example: SupportBot
          type: string
        avatar:
          description: URL of the bot's avatar
          example: https://avatar.demo/bot-avatar
          format: uri
          type: string
      required:
        - id
        - name
        - avatar
    WebhookCustomerData:
      type: object
      description: Represents customer data in the webhook
      properties:
        first_name:
          description: Customer's first name
          example: Jane
          type: string
        last_name:
          description: Customer's last name
          example: Smith
          type: string
        avatar:
          description: URL of the customer's avatar
          example: https://avatar.demo/customer-avatar
          format: uri
          type: string
      required:
        - first_name
        - last_name
        - avatar
    WebhookTemplateContent:
      type: object
      description: Represents the content of a chat template
      properties:
        name:
          description: Template name
          example: Welcome Message
          type: string
        lang:
          description: Language code for the template
          example: en
          type: string
        category:
          description: Category of the template
          example: greetings
          type: string
        body:
          description: Body content of the template
          example: Hello, {{name}}! Welcome to our service.
          type: string
        header:
          $ref: '#/components/schemas/TemplateHeader'
        footer:
          description: Footer content of the template
          example: Thank you for joining us!
          type: string
        buttons:
          $ref: '#/components/schemas/TemplateButtons'
        example:
          $ref: '#/components/schemas/TemplateExample'
      required:
        - name
        - lang
        - category
        - body
    WebhookTemplateInfo:
      description: Represents a chat template information
      type: object
      properties:
        code:
          description: Template code
          example: template123
          type: string
        category:
          $ref: '#/components/schemas/WebhookTemplateCategory'
        args:
          description: Template arguments
          deprecated: true
          items:
            type: string
          type: array
        variables:
          allOf:
            - $ref: '#/components/schemas/WebhookTemplateArguments'
    WebhookTemplateArguments:
      description: Represents the arguments for a template
      type: object
      properties:
        header:
          $ref: '#/components/schemas/WebhookTemplateHeaderArguments'
        body:
          allOf:
            - $ref: '#/components/schemas/WebhookTemplateBodyArguments'
        buttons:
          description: Template button arguments
          items:
            $ref: '#/components/schemas/WebhookTemplateButtonArguments'
          type: array
    WebhookTemplateHeaderArguments:
      description: Represents the arguments for the header section of a template
      type: object
      properties:
        type:
          description: Type of header content
          allOf:
            - $ref: '#/components/schemas/TemplateHeaderContentType'
        args:
          description: Arguments for the header
          items:
            type: string
          type: array
        attachments:
          description: Attachments for the header
          items:
            $ref: '#/components/schemas/TemplateExampleAttachment'
          type: array
      required:
        - type
    WebhookTemplateBodyArguments:
      description: Represents the arguments for the body section of a template
      type: object
      properties:
        args:
          description: Arguments for the body
          type: array
          items:
            type: string
      required:
        - args
    WebhookTemplateButtonArguments:
      description: Represents the arguments for a template button
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TemplateButtonType'
        title:
          description: Title of the button
          example: Click Me
          type: string
        args:
          description: Arguments for the button
          items:
            type: string
          type: array
      required:
        - type
        - title
    WebhookTemplateCategory:
      description: Category of the template
      type: string
      enum:
        - authentication
        - marketing
        - utility
    WebhookMessageFile:
      description: Attached message file
      type: object
      properties:
        id:
          description: 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
        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
    MessageType:
      description: Message type
      type: string
      enum:
        - text
        - system
        - command
        - order
        - product
        - file
        - image
        - audio
      example: text
    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
    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
    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'
    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
    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
    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
    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'
    MessageOrderStatusCode:
      description: Status code
      type: string
      enum:
        - new
        - approval
        - assembling
        - delivery
        - complete
        - cancel
      example: approval
    MessageOrderStatus:
      description: Order status
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/MessageOrderStatusCode'
        name:
          description: Status name
          example: approval
          maxLength: 255
          type: string
    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:
          $ref: '#/components/schemas/MessageOrderStatus'
        url:
          description: Order URL
          example: https://url.demo/demo-url
          format: uri
          maxLength: 2048
          type: string
    TemplateHeaderContentType:
      type: string
      description: Header section type
      enum:
        - text
        - document
        - image
        - video
      example: text
    TemplateExampleAttachment:
      description: Example of a template attachment
      type: object
      properties:
        id:
          description: UID of the uploaded file
          format: uuid
          type: string
        caption:
          description: Original file name
          maxLength: 1024
          minLength: 1
          type: string
      required:
        - id
    TemplateButtonType:
      description: Button type
      type: string
      enum:
        - plain
        - phone
        - url
      example: plain
    SuggestionType:
      type: string
      description: Quick response type
      enum:
        - text
        - email
        - phone
        - url
      example: phone
    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'
    MessageTransportAttachments:
      description: Transport attachments
      properties:
        suggestions:
          description: Quick responses
          items:
            $ref: '#/components/schemas/Suggestion'
          type: array
      type: object
    TemplateHeaderContent:
      description: Template header content
      type: object
      properties:
        type:
          $ref: '#/components/schemas/TemplateHeaderContentType'
        body:
          description: Text content of the header section (for content type `text`)
          type: string
      required:
        - type
    TemplateHeader:
      description: Header section of the template
      type: object
      properties:
        content:
          allOf:
            - $ref: '#/components/schemas/TemplateHeaderContent'
    TemplateButton:
      description: Template button
      type: object
      properties:
        label:
          description: Button name
          type: string
        type:
          $ref: '#/components/schemas/TemplateButtonType'
        phone:
          type: string
          description: Phone number (for button type `phone`)
        url:
          type: string
          format: uri
          description: URL address (for button type `url`)
      required:
        - label
        - type
    TemplateButtons:
      description: List of template buttons
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TemplateButton'
          example:
            - label: Click me
              type: plain
            - label: Call us
              type: phone
              phone: '+1234567890'
            - label: Visit our website
              type: url
              url: https://example.com
    TemplateExample:
      description: Template example
      type: object
      properties:
        attachments:
          description: Template attachments
          items:
            $ref: '#/components/schemas/TemplateExampleAttachment'
          maxLength: 1
          type: array
        body:
          description: Array of example template body values
          example:
            - Max
            - e3459
            - '328'
          items:
            type: string
          type: array
        buttons:
          description: Array of example template button values
          items:
            items:
              type: string
            type: array
          type: array
        header:
          description: Array of example values for the header section of the template
          example:
            - Alex
          items:
            type: string
          type: array
    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
  requestBodies:
    WebhookRequest:
      description: Webhook request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookRequestData'
      required: true
  responses:
    WebhookResponse:
      description: Return a 200 status to indicate that the data was received successfully
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/WebhookEmptyResponse'
              - $ref: '#/components/schemas/WebhookSendMessageResponseData'
              - $ref: '#/components/schemas/WebhookTemplateCreateResponseData'