HubSpot Messages API

openapi: 3.1.0
info:
  title: HubSpot Analytics Events Access Tokens Messages API
  description: "The HubSpot Analytics Events API allows you to retrieve event completion data \nfrom your HubSpot account. Use this API to query event instances associated with \nCRM objects, filter by event types, and analyze user behavior and engagement patterns.\n\n## Key Features\n- Retrieve event instances for CRM objects\n- Filter events by type, date range, and object\n- Paginate through large result sets\n- Query available event types\n"
  version: 3.0.0
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.hubapi.com
  description: HubSpot Production API Server
tags:
- name: Messages
  description: Operations for sending, receiving, and managing messages within conversation threads.
paths:
  /conversations/v3/conversations/threads/{threadId}/messages:
    get:
      tags:
      - Messages
      operationId: listThreadMessages
      summary: Hubspot List Thread Messages
      description: 'Retrieve all messages in a conversation thread. Messages are returned

        in chronological order with pagination support.

        '
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - conversations.read
      - PrivateApp: []
      parameters:
      - name: threadId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the thread
        example: '987654321'
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: Maximum number of messages per page
        example: 20
      - name: after
        in: query
        schema:
          type: string
        description: Pagination cursor for the next page
        example: NTI1Cg%3D%3D
      responses:
        '200':
          description: Successfully retrieved the list of messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCollection'
              examples:
                Success:
                  $ref: '#/components/examples/MessageCollectionExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      tags:
      - Messages
      operationId: sendMessage
      summary: Hubspot Send a Message
      description: 'Send a new message to a conversation thread. The message will be delivered

        through the specified channel to the thread participants.

        '
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - conversations.write
      - PrivateApp: []
      parameters:
      - name: threadId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the thread to send the message to
        example: '987654321'
      requestBody:
        required: true
        description: Message content and delivery configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              SendTextMessage:
                $ref: '#/components/examples/SendMessageRequestExample'
      responses:
        '201':
          description: Successfully sent the message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Success:
                  $ref: '#/components/examples/MessageExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /conversations/v3/conversations/threads/{threadId}/messages/{messageId}:
    get:
      tags:
      - Messages
      operationId: getMessageById
      summary: Hubspot Retrieve a Message
      description: 'Retrieve a specific message by its unique identifier within a thread.

        Returns the complete message details including sender, recipients, and attachments.

        '
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: 'return "Success"

          '
      security:
      - OAuth2:
        - conversations.read
      - PrivateApp: []
      parameters:
      - name: threadId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the thread containing the message
        example: '987654321'
      - name: messageId
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier of the message to retrieve
        example: msg_123456
      responses:
        '200':
          description: Successfully retrieved the message details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Success:
                  $ref: '#/components/examples/MessageExample'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ErrorDetail:
      type: object
      description: Detailed information about a specific error.
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Invalid thread ID format
        code:
          type: string
          description: Error code
          example: INVALID_FORMAT
        subCategory:
          type: string
          description: Error subcategory
          example: PARAMETER_ERROR
        in:
          type: string
          description: Location where error occurred
          example: path
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
      required:
      - message
    MessageRecipient:
      type: object
      description: Recipient information for a message.
      properties:
        actorId:
          type: string
          description: Actor ID of the recipient
          example: actor_101
    SendMessageRequest:
      type: object
      description: Request payload for sending a message to a thread.
      properties:
        type:
          type: string
          enum:
          - MESSAGE
          - COMMENT
          description: Type of message to send
          example: MESSAGE
        text:
          type: string
          description: Plain text content of the message
          example: Thank you for reaching out. How can I help you today?
        richText:
          type: string
          description: Rich text (HTML) content
          example: <p>Thank you for reaching out. How can I help you today?</p>
        senderActorId:
          type: string
          description: Actor ID of the sender
          example: actor_agent_123
        channelId:
          type: string
          description: Channel to send on
          example: channel_789
        channelAccountId:
          type: string
          description: Channel account to use
          example: account_123
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/MessageRecipient'
          description: Message recipients
          example:
          - actorId: actor_101
      required:
      - type
      - text
      - senderActorId
    MessageCollection:
      type: object
      description: Paginated collection of messages
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Array of message records
          example:
          - id: msg_123456
            type: MESSAGE
            text: Hello, I need help with my order.
            richText: <p>Hello, I need help with my order.</p>
            direction: INCOMING
            channelId: channel_789
            channelAccountId: account_123
            senders:
            - id: actor_101
              actorId: actor_101
              name: John Customer
              email: john@example.com
              type: VISITOR
            recipients:
            - id: actor_101
              actorId: actor_101
              name: John Customer
              email: john@example.com
              type: VISITOR
            status: {}
            createdAt: '2024-01-20T10:30:00Z'
            truncationStatus: NOT_TRUNCATED
            attachments:
            - id: attach_001
              type: application/pdf
              url: https://api.hubapi.com/files/v3/files/attach_001
              filename: invoice.pdf
              size: 102400
        paging:
          $ref: '#/components/schemas/Paging'
      required:
      - results
    Error:
      type: object
      description: Standard error response structure.
      properties:
        category:
          type: string
          description: Error category
          example: VALIDATION_ERROR
        correlationId:
          type: string
          format: uuid
          description: Unique tracking identifier for support requests
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message:
          type: string
          description: Human-readable error message
          example: Invalid input parameters
        subCategory:
          type: string
          description: Error subcategory
          example: INVALID_PARAMETER
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            key: value
        links:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
          example:
          - message: Invalid thread ID format
            code: INVALID_FORMAT
            subCategory: PARAMETER_ERROR
            in: path
            context:
              key: value
      required:
      - category
      - correlationId
      - message
    MessageStatus:
      type: object
      description: Delivery status information for a message
      properties:
        statusType:
          type: string
          enum:
          - SENT
          - DELIVERED
          - READ
          - FAILED
          description: Current delivery status type
          example: DELIVERED
    Paging:
      type: object
      description: Pagination information for list responses.
      properties:
        next:
          $ref: '#/components/schemas/PagingNext'
    Message:
      type: object
      description: Represents a message within a conversation thread.
      properties:
        id:
          type: string
          description: Unique identifier for the message
          example: msg_123456
        type:
          type: string
          enum:
          - MESSAGE
          - COMMENT
          - WELCOME_MESSAGE
          description: Type of message
          example: MESSAGE
        text:
          type: string
          description: Plain text content of the message
          example: Hello, I need help with my order.
        richText:
          type: string
          description: Rich text (HTML) content of the message
          example: <p>Hello, I need help with my order.</p>
        direction:
          type: string
          enum:
          - INCOMING
          - OUTGOING
          description: Direction of the message (incoming or outgoing)
          example: INCOMING
        channelId:
          type: string
          description: ID of the communication channel
          example: channel_789
        channelAccountId:
          type: string
          description: ID of the channel account
          example: account_123
        senders:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
          description: List of message senders
          example:
          - id: actor_101
            actorId: actor_101
            name: John Customer
            email: john@example.com
            type: VISITOR
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
          description: List of message recipients
          example:
          - id: actor_101
            actorId: actor_101
            name: John Customer
            email: john@example.com
            type: VISITOR
        status:
          $ref: '#/components/schemas/MessageStatus'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the message was created
          example: '2024-01-20T10:30:00Z'
        truncationStatus:
          type: string
          description: Whether the message was truncated
          example: NOT_TRUNCATED
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: Message attachments
          example:
          - id: attach_001
            type: application/pdf
            url: https://api.hubapi.com/files/v3/files/attach_001
            filename: invoice.pdf
            size: 102400
      required:
      - id
      - type
      - createdAt
    Attachment:
      type: object
      description: Represents a file attachment on a message.
      properties:
        id:
          type: string
          description: Unique identifier for the attachment
          example: attach_001
        type:
          type: string
          description: MIME type of the attachment
          example: application/pdf
        url:
          type: string
          format: uri
          description: URL to access the attachment
          example: https://api.hubapi.com/files/v3/files/attach_001
        filename:
          type: string
          description: Original filename
          example: invoice.pdf
        size:
          type: integer
          description: File size in bytes
          example: 102400
    PagingNext:
      type: object
      description: Pagination cursor information for retrieving the next page.
      properties:
        after:
          type: string
          description: Cursor token for the next page
          example: NTI1Cg%3D%3D
        link:
          type: string
          description: API link to the next page
          example: /conversations/v3/conversations/inboxes?after=NTI1Cg%3D%3D
    Actor:
      type: object
      description: Represents a participant in a conversation (visitor, agent, or bot).
      properties:
        id:
          type: string
          description: Unique identifier for the actor
          example: actor_101
        actorId:
          type: string
          description: Actor ID reference
          example: actor_101
        name:
          type: string
          description: Display name of the actor
          example: John Customer
        email:
          type: string
          format: email
          description: Email address of the actor
          example: john@example.com
        type:
          type: string
          description: Type of actor (e.g., VISITOR, AGENT, BOT)
          example: VISITOR
      required:
      - id
  responses:
    ErrorResponse:
      description: An error occurred while processing the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ValidationError:
              $ref: '#/components/examples/ErrorExample'
  examples:
    MessageCollectionExample:
      summary: Paginated list of messages
      value:
        results:
        - id: msg_123456
          type: MESSAGE
          text: Hello, I need help with my order.
          direction: INCOMING
          createdAt: '2024-01-20T10:30:00Z'
        - id: msg_123457
          type: MESSAGE
          text: Hi! I'd be happy to help. What's your order number?
          direction: OUTGOING
          createdAt: '2024-01-20T10:32:00Z'
        paging:
          next:
            after: NTI1Cg%3D%3D
            link: /conversations/v3/conversations/threads/987654321/messages?after=NTI1Cg%3D%3D
    ErrorExample:
      summary: Validation error response
      value:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        message: Invalid input parameters
        context:
          invalidFields:
          - threadId
    MessageExample:
      summary: A complete message record
      value:
        id: msg_123456
        type: MESSAGE
        text: Hello, I need help with my order.
        direction: INCOMING
        channelId: channel_789
        channelAccountId: account_123
        senders:
        - id: actor_101
          name: John Customer
          email: john@example.com
          type: VISITOR
        status:
          statusType: DELIVERED
        createdAt: '2024-01-20T10:30:00Z'
    SendMessageRequestExample:
      summary: Example request to send a message
      value:
        type: MESSAGE
        text: Thank you for reaching out. How can I help you today?
        senderActorId: actor_agent_123
        channelId: channel_789
        channelAccountId: account_123
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            analytics.read: Read analytics data