Mews Messages API

openapi: 3.2.0
info:
  title: Connector Messages API
  description: General-purpose API that enables partners of Mews to access data and services in Mews Operations
  termsOfService: https://www.mews.com/en/terms-conditions/partners
  contact:
    name: Partner success
    email: partnersuccess@mews.com
  version: v1
servers:
- url: https://api.mews.com
tags:
- name: Messages
paths:
  /api/connector/v1/messages/getAll:
    post:
      tags:
      - Messages
      summary: Get all messages
      description: Get all messages belonging to the specified Message threads. Messages can only be returned for message threads you have created. Note this operation uses Pagination and supports Portfolio Access Tokens.
      operationId: messages_getAll
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageFilterParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              MessageThreadIds:
              - 7f9325f6-ef44-4911-89a8-ae51010a5aa4
              - 8d02142f-31cf-4115-90bf-ae5200c7a1ba
              CreatedUtc:
                StartUtc: '2022-03-03T00:00:00Z'
                EndUtc: '2022-03-14T00:00:00Z'
              EnterpriseIds:
              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
              - 4d0201db-36f5-428b-8d11-4f0a65e960cc
              Limitation:
                Count: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResult'
              example:
                Messages:
                - Id: 4bfe4675-98a9-4428-9ea9-ae5300dbaa93
                  MessageThreadId: 7f9325f6-ef44-4911-89a8-ae51010a5aa4
                  Text: Text of the message
                  Sender:
                    Discriminator: Application
                    Value: null
                  CreatedUtc: '2022-03-09T13:19:46Z'
                Cursor: 7f9325f6-ef44-4911-89a8-ae51010a5aa4
        '400':
          description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '401':
          description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '403':
          description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '408':
          description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '204':
          description: Server has successfully fulfilled the request and there is no additional information to send back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '429':
          description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '500':
          description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
  /api/connector/v1/messages/add:
    post:
      tags:
      - Messages
      summary: Add messages
      description: Add the specified messages to the specified Message threads. You can only add messages to message threads that you have created.
      operationId: messages_add
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipleMessageAddParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              Messages:
              - MessageThreadId: 7f9325f6-ef44-4911-89a8-ae51010a5aa4
                Text: Text of the message
                Identifier: Message 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddedMessageResult'
              example:
                Messages:
                - Identifier: Message 1
                  Message:
                    Id: 4bfe4675-98a9-4428-9ea9-ae5300dbaa93
                    MessageThreadId: 7f9325f6-ef44-4911-89a8-ae51010a5aa4
                    Text: Text of the message
                    Sender:
                      Discriminator: Application
                      Value: null
                    CreatedUtc: '2022-03-09T13:19:46Z'
        '400':
          description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '401':
          description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '403':
          description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '408':
          description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '204':
          description: Server has successfully fulfilled the request and there is no additional information to send back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '429':
          description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '500':
          description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
components:
  schemas:
    Limitation:
      title: Limitation
      required:
      - Count
      type: object
      properties:
        Count:
          type: integer
          format: int32
        Cursor:
          type:
          - string
          - 'null'
          format: uuid
      additionalProperties: false
      description: Limitation on the quantity of data returned.
      x-schema-id: Limitation
    ConnectorApiExceptionResult:
      title: ConnectorApiExceptionResult
      type: object
      properties:
        Message:
          type:
          - string
          - 'null'
        RequestId:
          type:
          - string
          - 'null'
        Details: {}
      additionalProperties: false
      x-schema-id: ConnectorApiExceptionResult
    AddedMessageResult:
      title: AddedMessageResult
      required:
      - Messages
      type: object
      properties:
        Messages:
          type: array
          items:
            $ref: '#/components/schemas/AddedMessage'
          description: Collection of created messages.
      additionalProperties: false
      x-schema-id: AddedMessageResult
    MessageFilterParameters:
      title: MessageFilterParameters
      required:
      - AccessToken
      - Client
      - ClientToken
      - Limitation
      - MessageThreadIds
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
        Limitation:
          allOf:
          - $ref: '#/components/schemas/Limitation'
          description: Limitation on the quantity of data returned and optional Cursor for the starting point of data.
        EnterpriseIds:
          maxItems: 1000
          minItems: 1
          type:
          - array
          - 'null'
          items:
            type: string
            format: uuid
          description: Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token.
        MessageThreadIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of `MessageThread`s from where to return messages.
        CreatedUtc:
          title: Time interval
          allOf:
          - $ref: '#/components/schemas/TimeFilterInterval'
          description: Interval in which the `Message` was created.
          x-max-interval-in-months: 1
      additionalProperties: false
      x-schema-id: MessageFilterParameters
    SenderDiscriminatorEnum:
      title: Sender discriminator
      enum:
      - Enterprise
      - Application
      type: string
      description: '


        Enterprise (The message was created by an employee of the enterprise.)


        Application (The message was created by the third party application.)'
      x-enumNames:
      - Enterprise
      - Application
      x-enumDescriptions:
      - The message was created by an employee of the enterprise.
      - The message was created by the third party application.
    TimeFilterInterval:
      title: Time interval
      type: object
      properties:
        StartUtc:
          type:
          - string
          - 'null'
          format: date-time
        EndUtc:
          type:
          - string
          - 'null'
          format: date-time
      additionalProperties: false
      description: "When a time interval is used for **filtering** (for example in parameters such as `CreatedUtc.StartUtc` / `CreatedUtc.EndUtc`), the following rules apply:\n\n- **Start equals End (equality mode)**  \n  If `StartUtc` and `EndUtc` are exactly the same timestamp, the filter is treated as an equality check for that precise moment in time:\n  \n  ```\n  CreatedUtc == StartUtc\n  ```\n  \n  This does not represent an interval; only records with `CreatedUtc` equal to that exact instant are returned.\n\n- **Start differs from End (interval mode)**  \n  If `StartUtc` and `EndUtc` are different, the filter is evaluated as a half-open interval:\n  \n  ```\n  StartUtc <= CreatedUtc < EndUtc\n  ```\n  \n  In other words, the start is inclusive and the end is exclusive.\n\nMake sure your integration takes inclusive Start / exclusive End behavior of time intervals into account so that no records at the boundaries are omitted."
      x-schema-id: TimeFilterInterval
    SenderCoproduct:
      title: Sender
      required:
      - Discriminator
      type: object
      properties:
        Discriminator:
          title: Sender discriminator
          allOf:
          - $ref: '#/components/schemas/SenderDiscriminatorEnum'
          description: 'The sender of the message.


            Enterprise (The message was created by an employee of the enterprise.)


            Application (The message was created by the third party application.)'
          x-enumNames:
          - Enterprise
          - Application
          x-enumDescriptions:
          - The message was created by an employee of the enterprise.
          - The message was created by the third party application.
        Value:
          description: Additional information about the sender. Currently not used and always `null`.
      additionalProperties: false
      x-schema-id: SenderCoproduct
    AddedMessage:
      title: Added message
      required:
      - Message
      type: object
      properties:
        Identifier:
          type:
          - string
          - 'null'
          description: Identifier of the created message.
        Message:
          title: Message
          allOf:
          - $ref: '#/components/schemas/Message'
          description: Message that was added to the `MessageThread`.
      additionalProperties: false
      x-schema-id: AddedMessage
    MessageResult:
      title: MessageResult
      required:
      - Messages
      type: object
      properties:
        Messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: The filtered messages.
        Cursor:
          type:
          - string
          - 'null'
          description: Unique identifier of the last and hence oldest message returned. This can be used in `Limitation` in a subsequent request to fetch the next batch of older messages.
          format: uuid
      additionalProperties: false
      x-schema-id: MessageResult
    Message:
      title: Message
      required:
      - CreatedUtc
      - Id
      - MessageThreadId
      - Sender
      - Text
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier of the message.
          format: uuid
        MessageThreadId:
          type: string
          description: Unique identifier of the `MessageThread` to which the message belongs to.
          format: uuid
        Text:
          minLength: 1
          type: string
          description: Text of the message.
        Sender:
          title: Sender
          allOf:
          - $ref: '#/components/schemas/SenderCoproduct'
          description: The sender of the message.
        CreatedUtc:
          minLength: 1
          type: string
          description: Creation date and time of the message in UTC timezone in ISO 8601 format.
          format: date-time
      additionalProperties: false
      x-schema-id: Message
    MultipleMessageAddParameters:
      title: MultipleMessageAddParameters
      required:
      - AccessToken
      - Client
      - ClientToken
      - Messages
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
        Messages:
          maxItems: 1000
          type: array
          items:
            $ref: '#/components/schemas/MessageAddParameters'
          description: Messages to be added.
      additionalProperties: false
      x-schema-id: MultipleMessageAddParameters
    MessageAddParameters:
      title: Message parameters
      required:
      - MessageThreadId
      - Text
      type: object
      properties:
        MessageThreadId:
          type: string
          description: Unique identifier of the `MessageThread` to which the message should be added.
          format: uuid
        Text:
          minLength: 1
          type: string
          description: Text of the message.
        Identifier:
          type:
          - string
          - 'null'
          description: Identifier of the message to be created.
      additionalProperties: false
      x-schema-id: MessageAddParameters