openapi: 3.0.1
info:
  title: Symphony Agent Add Message API
  description: 'This document refers to Symphony API calls to send and receive messages

    and content. They need the on-premise Agent installed to perform

    decryption/encryption of content.


    - sessionToken and keyManagerToken can be obtained by calling the

    authenticationAPI on the symphony back end and the key manager

    respectively. Refer to the methods described in authenticatorAPI.yaml.

    - Actions are defined to be atomic, ie will succeed in their entirety

    or fail and have changed nothing.

    - If it returns a 40X status then it will have sent no message to any

    stream even if a request to some subset of the requested streams

    would have succeeded.

    - If this contract cannot be met for any reason then this is an error

    and the response code will be 50X.

    - MessageML is a markup language for messages. See reference here:

    https://rest-api.symphony.com/docs/messagemlv2

    - **Real Time Events**: The following events are returned when reading

    from a real time messages and events stream ("datafeed"). These

    events will be returned for datafeeds created with the v5 endpoints.

    To know more about the endpoints, refer to Create Messages/Events

    Stream and Read Messages/Events Stream. Unless otherwise specified,

    all events were added in 1.46.

    '
  version: 22.9.1
servers:
- url: /
tags:
- name: Message
paths:
  /v4/message/import:
    post:
      tags:
      - Message
      summary: Import Messages From Other Systems Into Symphony
      description: 'Sends a message to be imported into the system.

        Allows you to override the timestamp and author of the message with your desired values.

        The requesting user must have the Content Management role.

        The user that the message is intended to have come from must also be present in the conversation.

        The intended message timestamp must be a valid time from the past. It cannot be a future timestamp.

        Optionally the original message ID can be specified to identify the imported message for the purpose of repeat imports.

        '
      parameters:
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V4MessageImportList'
        required: true
      responses:
        '200':
          description: Message sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4ImportResponseList'
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
      x-codegen-request-body-name: messageList
  /v4/message/blast:
    post:
      tags:
      - Message
      summary: Post a Message to Multiple Existing Streams
      description: 'Post a new message to the given list of streams. The stream can be a chatroom,

        an IM or a multiparty IM.


        You may include an attachment on the message.


        The message can be provided as MessageMLV2 or PresentationML. Both formats support Freemarker templates.


        The optional parameter "data" can be used to provide a JSON payload containing entity data.

        If the message contains explicit references to entity data (in "data-entity-id" element attributes),

        this parameter is required.


        If the message is in MessageML and fails schema validation a client error results


        This endpoint is idempotent, it means that a 200 response will be returned even if the message has not been

        delivered to some streams. Check the `errors` map from the response in order to see on which stream(s) the

        message has not been delivered.


        The maximum number of streams where the message can be sent is limitted to 100.


        Regarding authentication, you must either use the sessionToken which was created for delegated app access

        or both the sessionToken and keyManagerToken together.

        '
      parameters:
      - name: sessionToken
        in: header
        description: Authorization token used to make delegated calls.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - sids
              properties:
                sids:
                  type: array
                  description: A comma-separated list of Stream IDs
                  items:
                    type: string
                message:
                  type: string
                  description: The message payload in MessageML.
                data:
                  type: string
                  description: Optional message data in EntityJSON.
                version:
                  type: string
                  description: 'Optional message version in the format "major.minor". If empty, defaults to the latest supported version.

                    '
                attachment:
                  type: string
                  description: Optional file attachment.
                  format: binary
                preview:
                  type: string
                  description: Optional attachment preview.
                  format: binary
      responses:
        '200':
          description: Blast message sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4MessageBlastResponse'
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '451':
          description: Compliance Issues found in message or file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
  /v1/message/{id}:
    get:
      tags:
      - Message
      summary: Get a Message by ID
      parameters:
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Message ID as a URL-safe string
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4Message'
        '204':
          description: No Messages.
          content: {}
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
  /v1/message/search:
    get:
      tags:
      - Message
      summary: Symphony Search Messages
      description: "Search messages according to the specified criteria. The \"query\" parameter takes a search query defined as\n\"field:value\" pairs combined by the operator \"AND\" (e.g. \"text:foo AND autor:bar\"). Supported fields are\n (case-insensitive): \"text\", \"author\", \"hashtag\", \"cashtag\", \"mention\", \"signal\", \"fromDate\", \"toDate\",\n \"streamId\", \"streamType\".\n \"text\" search requires a \"streamId\" to be specified.\n \"streamType\" accepts one of the following values: \"chat\" (IMs and MIMs), \"im\", \"mim\", \"chatroom\", \"post\".\n \"signal\" queries can only be combined with \"fromDate\", \"toDate\", \"skip\" and \"limit\" parameters.\n"
      parameters:
      - name: query
        in: query
        description: The search query. See above for the query syntax.
        required: true
        schema:
          type: string
      - name: skip
        in: query
        description: No. of results to skip.
        schema:
          type: integer
      - name: limit
        in: query
        description: Max no. of results to return. If no value is provided, 50 is the default.
        schema:
          type: integer
      - name: scope
        in: query
        description: 'Describes where content should be searched for that query.

          It can exclusively apply to Symphony content or to one Connector.

          '
        schema:
          type: string
      - name: sortDir
        in: query
        description: 'Messages sort direction : ASC or DESC (default to DESC)

          '
        schema:
          type: string
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4MessageList'
        '204':
          description: No Messages.
          content: {}
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
    post:
      tags:
      - Message
      summary: Symphony Search Messages
      description: Search messages according to the specified criteria.
      parameters:
      - name: skip
        in: query
        description: No. of results to skip.
        schema:
          type: integer
      - name: limit
        in: query
        description: Max no. of results to return. If no value is provided, 50 is the default.
        schema:
          type: integer
      - name: scope
        in: query
        description: 'Describes where content should be searched for that query.

          It can exclusively apply to Symphony content or to one Connector.

          '
        schema:
          type: string
      - name: sortDir
        in: query
        description: 'Messages sort direction : ASC or DESC (default to DESC)

          '
        schema:
          type: string
      - name: sessionToken
        in: header
        description: Session authentication token.
        required: true
        schema:
          type: string
      - name: keyManagerToken
        in: header
        description: Key Manager authentication token.
        required: true
        schema:
          type: string
      requestBody:
        description: The search query. See above for the query syntax.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageSearchQuery'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V4MessageList'
        '204':
          description: No Messages.
          content: {}
        '400':
          description: Client error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '401':
          description: 'Unauthorized: Session tokens invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '403':
          description: 'Forbidden: Caller lacks necessary entitlement.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
        '500':
          description: Server error, see response body for further details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Error'
      x-codegen-request-body-name: query
components:
  schemas:
    V4ImportResponseList:
      type: array
      items:
        $ref: '#/components/schemas/V4ImportResponse'
    V4MessageImportList:
      type: array
      description: 'An ordered list of historic messages to be imported.

        A list of import responses will be returned in the same order.

        '
      items:
        $ref: '#/components/schemas/V4ImportedMessage'
    V4MessageBlastResponse:
      type: object
      required:
      - messages
      - errors
      properties:
        messages:
          type: array
          default: []
          description: List of messages successfully sent
          items:
            $ref: '#/components/schemas/V4Message'
        errors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Error'
          description: List of streams where the messages ingestion has failed
      description: Wrapper response for a single message sent to multiple streams
    V4AttachmentInfo:
      required:
      - id
      - name
      - size
      - images
      type: object
      properties:
        id:
          type: string
          description: The attachment ID.
        name:
          type: string
          description: The file name.
        size:
          type: integer
          description: Size in bytes.
          format: int64
        images:
          type: array
          items:
            $ref: '#/components/schemas/V4ThumbnailInfo'
    V4Message:
      type: object
      properties:
        messageId:
          type: string
          description: Id of the message
        parentMessageId:
          type: string
          description: Id of the parent message, set when the message is a reply to another message or a forwarded message. Since Agent 20.14.
          x-since: 20.14
        timestamp:
          type: integer
          description: Timestamp of the message in milliseconds since Jan 1 1970
          format: int64
        message:
          type: string
          description: Message content in MessageMLV2
          format: MessageMLV2
        sharedMessage:
          $ref: '#/components/schemas/V4Message'
        data:
          type: string
          description: Message data in EntityJSON
          format: JSON
        attachments:
          type: array
          default: []
          description: Message attachments
          items:
            $ref: '#/components/schemas/V4AttachmentInfo'
        user:
          $ref: '#/components/schemas/V4User'
        stream:
          $ref: '#/components/schemas/V4Stream'
        externalRecipients:
          type: boolean
          description: Indicates if the message have external recipients. Only present on real time messaging.
        diagnostic:
          type: string
          description: 'Details if event failed to parse for any reason.  The contents of this field may not be useful,

            depending on the nature of the error. Only present when error occurs.

            '
        userAgent:
          type: string
          description: 'User agent string for client that sent the message.  Allows callers to identify which client sent the

            origin message (e.g. API Agent, SFE Client, mobile, etc)

            '
        originalFormat:
          type: string
          description: 'Indicates the format in which the message was originally sent.  This could have been either:

            - com.symphony.markdown - Markdown OR Message ML V1

            - com.symphony.messageml.v2 - Message ML V2

            '
        disclaimer:
          type: string
          description: 'Message that may be sent along with a regular message if configured for the POD,

            usually the first message sent in a room that day.

            '
        sid:
          type: string
          description: 'Unique session identifier from where the message was created.

            '
          example: fa691cd3-484a-4109-aeb2-57c05b78c95b
        replacing:
          type: string
          description: Id of the message that the current message is replacing (present only if set)
        replacedBy:
          type: string
          description: Id of the message that the current message is being replaced with (present only if set)
        initialTimestamp:
          type: integer
          description: "Timestamp of when the initial message has been created in milliseconds since \nJan 1 1970 (present only if set)\n"
          format: int64
        initialMessageId:
          type: string
          description: Id the the initial message that has been updated (present only if set)
        silent:
          type: boolean
          description: When false the user/s will receive the message update as unread (true by default)
          x-since: 20.14
      description: A representation of a message sent by a user of Symphony
    V4ThumbnailInfo:
      type: object
      properties:
        id:
          type: string
          description: The thumbnail ID.
        dimension:
          type: string
          description: The thumbnail pixel size.
    V2Error:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: object
    V4Stream:
      type: object
      properties:
        streamId:
          type: string
          description: Id of stream
        streamType:
          type: string
          description: "Stream type, possible values are:\n  - IM\n  - MIM\n  - ROOM\n  - POST\n"
        roomName:
          type: string
          description: Applicable only to rooms
        members:
          type: array
          description: Applicable only to IM Created
          items:
            $ref: '#/components/schemas/V4User'
        external:
          type: boolean
        crossPod:
          type: boolean
        recipientTenantIds:
          type: array
          description: 'List of tenant identifiers (aka pod identifiers) involved in the conversation. It contains more than one

            item if the conversation is external. Field is only present for real time messaging.

            '
          items:
            type: integer
            format: int32
          x-since: 24.2
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    V4ImportResponse:
      type: object
      properties:
        messageId:
          type: string
          description: 'If the message was successfully imported then the message ID in the system

            of the newly created message.

            '
        originatingSystemId:
          type: string
          description: The ID of the system through which the message was originally sent.
        originalMessageId:
          type: string
          description: The ID of the message in the original system.
        diagnostic:
          type: string
          description: 'A diagnostic message containing an error message in the event that the

            message import failed. May also be present in the case of a successful

            call if there is useful narrative to return.

            '
    V4ImportedMessage:
      required:
      - intendedMessageFromUserId
      - intendedMessageTimestamp
      - message
      - originatingSystemId
      - streamId
      type: object
      properties:
        message:
          type: string
          description: Message text in MessageMLV2
          format: MessageML
        data:
          type: string
          description: Entity data in EntityJSON
          format: JSON
        intendedMessageTimestamp:
          type: integer
          description: 'The timestamp representing the time when the message was sent in the original system

            in milliseconds since Jan 1st 1970.

            '
          format: int64
        intendedMessageFromUserId:
          type: integer
          description: The long integer userid of the Symphony user who you intend to show sent the message.
          format: int64
        originatingSystemId:
          type: string
          description: The ID of the system through which the message was originally sent.
        originalMessageId:
          type: string
          description: The ID of the message in the original system.
        streamId:
          type: string
        attachments:
          type: array
          description: List of message attachments. Since Agent 20.14.
          items:
            $ref: '#/components/schemas/V4ImportedMessageAttachment'
          x-since: 20.14
        previews:
          type: array
          description: List of attachments previews. Since Agent 20.14.
          items:
            $ref: '#/components/schemas/V4ImportedMessageAttachment'
          x-since: 20.14
      description: 'A historic message to be imported into the system.

        The importing user must have the Content Management role.

        Also, the importing user must be a member of the conversation it is importing into.

        The user that the message is intended to have come from must also be present in the conversation.

        The intended message timestamp must be a valid time from the past. It cannot be a future timestamp.

        By design, imported messages do not stream to datafeed or firehose endpoints.

        '
    V4ImportedMessageAttachment:
      type: object
      properties:
        filename:
          type: string
          description: Attachment filename
          example: car.png
        content:
          type: string
          description: Attachment content as Base64 encoded string
    V4User:
      type: object
      properties:
        userId:
          type: integer
          description: Id of user
          format: int64
        firstName:
          type: string
          description: First name of user
        lastName:
          type: string
          description: Last name of user
        displayName:
          type: string
          description: User display name
        email:
          type: string
          description: Email of user
        username:
          type: string
          description: Applicable only to internal users
    V4MessageList:
      type: array
      items:
        $ref: '#/components/schemas/V4Message'
    MessageSearchQuery:
      type: object
      properties:
        text:
          type: string
          description: Search for messages containing this text. Requires streamId to be specified.
        streamId:
          type: string
          description: Search for messages sent to this stream
        streamType:
          type: string
          description: 'Search for messages sent to this type of streams. Accepted values are CHAT, IM, MIM, ROOM, POST.

            '
        author:
          type: integer
          description: Search for messages sent by this user ID
          format: int64
        hashtag:
          type: string
          description: Search for messages containing this hashtag
        cashtag:
          type: string
          description: Search for messages containing this cashtag
        mention:
          type: integer
          description: Search for messages mentioning this user ID
          format: int64
        signal:
          type: string
          description: 'Search for messages matching this signal. Can only be combined with date filtering and paging parameters.

            '
        fromDate:
          type: integer
          description: Search for messages sent on or after this timestamp
          format: int64
        toDate:
          type: integer
          description: Search for messages sent before this timestamp
          format: int64