HubSpot Conversations API

openapi: 3.0.1
info:
  title: HubSpot Conversations
  description: Basepom for all HubSpot Projects
  version: v3
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  x-hubspot-related-documentation:
  - name: Inbox & Messages Guide
    url: https://developers.hubspot.com/docs/guides/api/conversations/inbox-and-messages
servers:
- url: https://api.hubapi.com
tags:
- name: Actors
- name: Basic
- name: Channel accounts
- name: Channels
- name: Inboxes
- name: Messages
- name: Threads
paths:
  /conversations/conversations/v3/threads/{threadId}/assignee:
    put:
      tags:
      - Basic
      operationId: put-/conversations/conversations/v3/threads/{threadId}/assignee_/conversations/conversations/v3/threads/{threadId}/assignee
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicThreadAssignRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicThread'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.write
      x-hubspot-user-level-auth:
        internalOnly: false
    delete:
      tags:
      - Basic
      operationId: delete-/conversations/conversations/v3/threads/{threadId}/assignee_/conversations/conversations/v3/threads/{threadId}/assignee
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/actors/batch/read:
    post:
      tags:
      - Actors
      summary: Get a group of actors
      description: Resolve a set of `ActorId`s to the underlying actors/participants.
      operationId: post-/conversations/v3/conversations/actors/batch/read
      parameters:
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputString'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePublicActor'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponsePublicActorWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
  /conversations/v3/conversations/actors/{actorId}:
    get:
      tags:
      - Actors
      summary: Get a single actor
      description: Retrieve details of a single actor using the actor ID.
      operationId: get-/conversations/v3/conversations/actors/{actorId}
      parameters:
      - name: actorId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicActor'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
  /conversations/v3/conversations/channel-accounts:
    get:
      tags:
      - Channel accounts
      summary: Get channel accounts
      description: Retrieve a list of channel accounts, with optional filters and sorting.
      operationId: get-/conversations/v3/conversations/channel-accounts
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: channelId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: defaultPageLength
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: inboxId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalPublicChannelAccount'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/channel-accounts/{channelAccountId}:
    get:
      tags:
      - Channel accounts
      summary: Get a single channel account
      description: Retrieve details of a single channel account using the channel account ID.
      operationId: get-/conversations/v3/conversations/channel-accounts/{channelAccountId}
      parameters:
      - name: channelAccountId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicChannelAccount'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/channels:
    get:
      tags:
      - Channels
      summary: Get channels
      description: Retrieve a list of channels, with optional filters and sorting.
      operationId: get-/conversations/v3/conversations/channels
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: defaultPageLength
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalPublicChannel'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
  /conversations/v3/conversations/channels/{channelId}:
    get:
      tags:
      - Channels
      summary: Get a single channel
      description: Retrieve details of a single channel using the channel ID.
      operationId: get-/conversations/v3/conversations/channels/{channelId}
      parameters:
      - name: channelId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicChannel'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
  /conversations/v3/conversations/inboxes:
    get:
      tags:
      - Inboxes
      summary: Get conversations inboxes
      description: Retrieve a list of conversations inboxes, with optional filters and sorting.
      operationId: get-/conversations/v3/conversations/inboxes
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: defaultPageLength
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalPublicInbox'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
  /conversations/v3/conversations/inboxes/{inboxId}:
    get:
      tags:
      - Inboxes
      summary: Get a single conversations inbox
      description: Retrieve details of a single conversations inbox using the inbox ID.
      operationId: get-/conversations/v3/conversations/inboxes/{inboxId}
      parameters:
      - name: inboxId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicInbox'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/threads:
    get:
      tags:
      - Threads
      summary: Get threads
      description: Retrieve a list of threads, with optional filters and sorting.
      operationId: get-/conversations/v3/conversations/threads
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: associatedContactId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: associatedTicketId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: association
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - TICKET
      - name: inboxId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int32
      - name: latestMessageTimestampAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: threadStatus
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - CLOSED
          - OPEN
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponsePublicThreadForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/threads/{threadId}:
    get:
      tags:
      - Threads
      summary: Get a single thread
      description: Retrieve a single thread by its ID
      operationId: get-/conversations/v3/conversations/threads/{threadId}
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: association
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - TICKET
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicThread'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
    delete:
      tags:
      - Threads
      summary: Archives a thread
      description: Archives a single thread. The thread will be permanently deleted 30 days after placed
        in an archived state.
      operationId: delete-/conversations/v3/conversations/threads/{threadId}
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.write
      x-hubspot-user-level-auth:
        internalOnly: false
    patch:
      tags:
      - Threads
      summary: Update a thread
      description: Updates a single thread. Either a thread's status can be updated, or the thread can
        be restored.
      operationId: patch-/conversations/v3/conversations/threads/{threadId}
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicThreadUpdateRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicThread'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/threads/{threadId}/messages:
    get:
      tags:
      - Threads
      summary: Get message history for a thread
      description: Retrieve the message history for a specific thread.
      operationId: get-/conversations/v3/conversations/threads/{threadId}/messages
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponsePublicMessageForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
    post:
      tags:
      - Threads
      summary: Send a message to a thread
      description: Send a new message on a thread at the current timestamp.
      operationId: post-/conversations/v3/conversations/threads/{threadId}/messages
      parameters:
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicMessageEgg'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMessage'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/threads/{threadId}/messages/{messageId}:
    get:
      tags:
      - Messages
      summary: Get a single message
      description: Retrieve a single message from a thread using the message ID.
      operationId: get-/conversations/v3/conversations/threads/{threadId}/messages/{messageId}
      parameters:
      - name: messageId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMessage'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content:
    get:
      tags:
      - Messages
      summary: Get the original content of a single message
      description: Returns the complete original text and rich text bodies of a message. This will be
        different from the text and rich text in the message itself if the message's `truncationStatus`
        is anything other than `NOT_TRUNCATED`.
      operationId: get-/conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content
      parameters:
      - name: messageId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: threadId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMessageContent'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - conversations.read
      x-hubspot-user-level-auth:
        internalOnly: false
components:
  schemas:
    AgentActor:
      required:
      - id
      - type
      type: object
      properties:
        avatar:
          type: string
        email:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          default: AGENT
          enum:
          - AGENT
      x-hubspot-sub-type-impl: true
    BatchInputString:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          items:
            type: string
    BatchResponsePublicActor:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          format: date-time
        links:
          type: object
          additionalProperties:
            type: string
        requestedAt:
          type: string
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicActor'
        startedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    BatchResponsePublicActorWithErrors:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          format: date-time
        errors:
          type: array
          items:
            $ref: '#/components/schemas/StandardError'
        links:
          type: object
          additionalProperties:
            type: string
        numErrors:
          type: integer
          format: int32
        requestedAt:
          type: string
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicActor'
        startedAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    BotActor:
      required:
      - id
      - type
      type: object
      properties:
        avatar:
          type: string
        id:
          type: string
        name:
          type: string
        type:
          type: string
          default: BOT
          enum:
          - BOT
      x-hubspot-sub-type-impl: true
    CollectionResponsePublicMessageForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/PublicConversationsMessage'
            - $ref: '#/components/schemas/PublicComment'
            - $ref: '#/components/schemas/PublicWelcomeMessage'
            - $ref: '#/components/schemas/PublicAssignmentMessage'
            - $ref: '#/components/schemas/PublicThreadStatusChange'
            - $ref: '#/components/schemas/PublicThreadInboxChange'
    CollectionResponsePublicThreadForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicThread'
    CollectionResponseWithTotalPublicChannel:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicChannel'
        total:
          type: integer
          format: int32
    CollectionResponseWithTotalPublicChannelAccount:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicChannelAccount'
        total:
          type: integer
          format: int32
    CollectionResponseWithTotalPublicInbox:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/PublicInbox'
        total:
          type: integer
          format: int32
    ContactAddress:
      type: object
      properties:
        city:
          type: string
        country:
          type: string
        countryCode:
          type: string
        state:
          type: string
        street:
          type: string
        type:
          type: string
          enum:
          - HOME
          - WORK
        zip:
          type: string
    ContactEmail:
      required:
      - email
      type: object
      properties:
        email:
          type: string
        type:
          type: string
          enum:
          - HOME
          - WORK
    ContactName:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        middleName:
          type: string
        prefix:
          type: string
        suffix:
          type: string
    ContactOrg:
      type: object
      properties:
        company:
          type: string
        department:
          type: string
        title:
          type: string
    ContactPhone:
      required:
      - phone
      type: object
      properties:
        phone:
          type: string
        type:
          type: string
          enum:
          - CELL
          - HOME
          - MAIN
          - WORK
    C

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-conversations-conversations-api-openapi.yml