Cisco Webex Messages API

openapi: 3.1.0
info:
  title: Cisco Webex Admin Audit Events Messages API
  description: Access admin audit events for tracking administrative actions performed in Webex Control Hub. Available to full administrators for compliance monitoring and security auditing purposes.
  version: 1.0.0
  contact:
    name: Cisco Webex Developer Support
    url: https://developer.webex.com/support
  license:
    name: Cisco Webex API Terms of Service
    url: https://developer.webex.com/terms-of-service
servers:
- url: https://webexapis.com/v1
  description: Webex Production API
security:
- bearerAuth: []
tags:
- name: Messages
  description: Operations for sending and managing messages
paths:
  /messages:
    get:
      operationId: listMessages
      summary: Cisco Webex List Messages
      description: Lists all messages in a room. Each message includes content and metadata about the message. The list sorts the messages in descending order by creation date.
      tags:
      - Messages
      parameters:
      - name: roomId
        in: query
        required: true
        description: Unique identifier for the room to list messages from.
        schema:
          type: string
      - name: parentId
        in: query
        description: List messages that are replies to the specified parent message.
        schema:
          type: string
      - name: mentionedPeople
        in: query
        description: List messages where the specified person is mentioned. Use 'me' for the authenticated user.
        schema:
          type: string
      - name: before
        in: query
        description: List messages sent before a date and time in ISO 8601 format.
        schema:
          type: string
          format: date-time
      - name: beforeMessage
        in: query
        description: List messages sent before a specified message ID.
        schema:
          type: string
      - name: max
        in: query
        description: Maximum number of messages to return (default 50, max 1000).
        schema:
          type: integer
          default: 50
          maximum: 1000
      responses:
        '200':
          description: Successful response with list of messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createMessage
      summary: Cisco Webex Create a Message
      description: Posts a plain text, rich text, or card message to a room. Messages can include file attachments and adaptive cards. The files parameter is limited to one file per message.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '200':
          description: Message created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
  /messages/direct:
    get:
      operationId: listDirectMessages
      summary: Cisco Webex List Direct Messages
      description: Lists all messages in a 1:1 (direct) room with another person. The authenticated user must be a member of the direct conversation.
      tags:
      - Messages
      parameters:
      - name: personId
        in: query
        description: Person ID of the other participant in the direct conversation.
        schema:
          type: string
      - name: personEmail
        in: query
        description: Email address of the other participant in the direct conversation.
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Successful response with list of direct messages.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
  /messages/{messageId}:
    get:
      operationId: getMessageDetails
      summary: Cisco Webex Get Message Details
      description: Shows details for a message by message ID. Specify the message ID in the URI. The returned message includes all content and metadata.
      tags:
      - Messages
      parameters:
      - name: messageId
        in: path
        required: true
        description: Unique identifier for the message.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with message details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: Message not found.
    put:
      operationId: editMessage
      summary: Cisco Webex Edit a Message
      description: Updates a message you have posted. Supports editing plain text and markdown content. Cannot edit messages with files or attachments. Maximum of 10 edits per message.
      tags:
      - Messages
      parameters:
      - name: messageId
        in: path
        required: true
        description: Unique identifier for the message.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditMessageRequest'
      responses:
        '200':
          description: Message updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Message not found.
    delete:
      operationId: deleteMessage
      summary: Cisco Webex Delete a Message
      description: Deletes a message by message ID. The deleted message will no longer be visible in the room. Moderators can delete any message; others can only delete their own.
      tags:
      - Messages
      parameters:
      - name: messageId
        in: path
        required: true
        description: Unique identifier for the message.
        schema:
          type: string
      responses:
        '204':
          description: Message deleted successfully.
        '404':
          description: Message not found.
components:
  schemas:
    EditMessageRequest:
      type: object
      required:
      - roomId
      properties:
        roomId:
          type: string
          description: The room ID of the message.
        text:
          type: string
          description: Updated plain text content (max 7439 bytes).
          maxLength: 7439
        markdown:
          type: string
          description: Updated markdown content (max 7439 bytes).
          maxLength: 7439
    Message:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the message.
        parentId:
          type: string
          description: The parent message ID if this is a reply.
        roomId:
          type: string
          description: The room ID of the message.
        roomType:
          type: string
          description: The type of room.
          enum:
          - direct
          - group
        text:
          type: string
          description: The plain text content of the message.
        markdown:
          type: string
          description: The message content in markdown format.
        html:
          type: string
          description: The rendered HTML content of the message.
        files:
          type: array
          description: Public URLs for files attached to the message.
          items:
            type: string
            format: uri
        personId:
          type: string
          description: The person ID of the message author.
        personEmail:
          type: string
          format: email
          description: The email address of the message author.
        mentionedPeople:
          type: array
          description: People IDs of those mentioned in the message.
          items:
            type: string
        mentionedGroups:
          type: array
          description: Group names mentioned in the message.
          items:
            type: string
        attachments:
          type: array
          description: Card attachments on the message.
          items:
            type: object
            properties:
              contentType:
                type: string
                description: The content type of the attachment.
              content:
                type: object
                description: Adaptive card content.
        isVoiceClip:
          type: boolean
          description: Whether the message is a voice clip.
        created:
          type: string
          format: date-time
          description: The date and time the message was created.
        updated:
          type: string
          format: date-time
          description: The date and time the message was last updated.
    CreateMessageRequest:
      type: object
      properties:
        roomId:
          type: string
          description: The room ID for the message.
        toPersonId:
          type: string
          description: Person ID to send a 1:1 message to.
        toPersonEmail:
          type: string
          format: email
          description: Email address to send a 1:1 message to.
        parentId:
          type: string
          description: The parent message ID to reply to.
        text:
          type: string
          description: Plain text message content (max 7439 bytes).
          maxLength: 7439
        markdown:
          type: string
          description: Markdown-formatted message content (max 7439 bytes).
          maxLength: 7439
        files:
          type: array
          description: Public URL to a file attachment (one per message).
          items:
            type: string
            format: uri
          maxItems: 1
        attachments:
          type: array
          description: Card attachments with adaptive card content.
          items:
            type: object
            properties:
              contentType:
                type: string
              content:
                type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Webex API access token. Obtain via OAuth 2.0 authorization flow. Requires audit:events_read scope.