# HubspotConversationsApi

import StarterToolInfo from "@/app/_components/starter-tool-info";
import ToolInfo from "@/app/_components/tool-info";
import Badges from "@/app/_components/badges";
import TabbedCodeBlock from "@/app/_components/tabbed-code-block";
import TableOfContents from "@/app/_components/table-of-contents";
import ToolFooter from "@/app/_components/tool-footer";
import { Callout } from "nextra/components";

<ToolInfo
  description="Tools that enable LLMs to interact directly with the Hubspot Conversations API"
  author="Arcade"
  authType="OAuth2"
  versions={["0.1.0"]}
/>

<Badges repo="arcadeai/arcade_hubspot_conversations_api" />

<StarterToolInfo toolkitName="HubspotConversationsApi" />

The Hubspot Conversations API MCP Server offers a comprehensive suite of tools for managing and interacting with conversation threads and channels within HubSpot. Users can perform a variety of actions, including:

- Retrieve and manage conversation inboxes and channels.
- Access detailed information about conversation threads and messages.
- Send new messages and update existing ones within conversation threads.
- Archive or restore conversation threads as needed.
- Resolve actor details and retrieve message history for specific threads.

This MCP Server is designed to streamline communication management and enhance user engagement through HubSpot's conversational capabilities.

## Available Tools

<TableOfContents
  headers={["Tool Name", "Description"]}
  data={[
    [
      "HubspotConversationsApi.ListConversationInboxes",
      "Retrieve a list of conversation inboxes.",
    ],
    [
      "HubspotConversationsApi.RetrieveThreadById",
      "Retrieve detailed information about a conversation thread by ID.",
    ],
    [
      "HubspotConversationsApi.ArchiveConversationThread",
      "Archives a conversation thread, marking it for deletion.",
    ],
    [
      "HubspotConversationsApi.UpdateConversationThread",
      "Update the status or restore a conversation thread.",
    ],
    [
      "HubspotConversationsApi.RetrieveFullMessageContent",
      "Retrieve the original text and rich text of a HubSpot message.",
    ],
    [
      "HubspotConversationsApi.ListConversationChannels",
      "Retrieve a list of conversation channels from Hubspot.",
    ],
    [
      "HubspotConversationsApi.RetrieveActorDetails",
      "Retrieve details of a specific actor by actor ID.",
    ],
    [
      "HubspotConversationsApi.RetrieveConversationThreads",
      "Retrieve conversation threads from Hubspot Conversations.",
    ],
    [
      "HubspotConversationsApi.GetMessageHistoryForThread",
      "Retrieve the message history for a specific thread.",
    ],
    [
      "HubspotConversationsApi.SendConversationMessage",
      "Send a new message in a conversation thread.",
    ],
    [
      "HubspotConversationsApi.ResolveConversationActors",
      "Resolve ActorIds to conversation participants.",
    ],
    [
      "HubspotConversationsApi.GetChannelAccountDetails",
      "Retrieve details of a HubSpot channel account by ID.",
    ],
    [
      "HubspotConversationsApi.RetrieveChannelAccounts",
      "Retrieve a list of channel accounts from Hubspot.",
    ],
    [
      "HubspotConversationsApi.RetrieveChannelDetails",
      "Retrieve details of a channel using its ID.",
    ],
    [
      "HubspotConversationsApi.GetInboxDetails",
      "Retrieve details of a conversation inbox by ID.",
    ],
    [
      "HubspotConversationsApi.RetrieveThreadMessage",
      "Retrieve a single message from a conversation thread.",
    ],
    [
      "HubspotConversationsApi.GetCustomChannelMessageDetails",
      "Retrieve details for a specific message in a custom channel.",
    ],
    [
      "HubspotConversationsApi.UpdateMessageStatus",
      "Update the status of a conversation message.",
    ],
    [
      "HubspotConversationsApi.UpdateChannelAccountStaging",
      "Update channel account staging token details for public apps.",
    ],
    [
      "HubspotConversationsApi.GetCustomChannelAccounts",
      "Retrieve accounts for a specified custom channel.",
    ],
    [
      "HubspotConversationsApi.CreateChannelAccount",
      "Create a new account for a specified communication channel.",
    ],
    [
      "HubspotConversationsApi.RetrieveChannelAccountDetails",
      "Retrieve details for a specific channel account.",
    ],
    [
      "HubspotConversationsApi.UpdateChannelAccountInfo",
      "Update channel account name and authorization status.",
    ],
    [
      "HubspotConversationsApi.PublishCustomChannelMessage",
      "Publish a message to a custom channel on HubSpot.",
    ],
  ]}
/>

<Callout>
  If you need to perform an action that's not listed here, you can [get in touch
  with us](mailto:contact@arcade.dev) to request a new tool, or [create your own
  tools](/guides/create-tools/tool-basics/build-mcp-server).
</Callout>

## HubspotConversationsApi.ListConversationInboxes

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/list_conversation_inboxes_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/list_conversation_inboxes_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve a list of conversation inboxes.

**Parameters**

This tool does not take any parameters.

## HubspotConversationsApi.RetrieveThreadById

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_thread_by_id_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_thread_by_id_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve detailed information about a conversation thread by ID.

**Parameters**

- **conversation_thread_id** (`string`, required) The unique identifier for the conversation thread you wish to retrieve. Provide the specific thread ID to access its details.

## HubspotConversationsApi.ArchiveConversationThread

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/archive_conversation_thread_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/archive_conversation_thread_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Archives a conversation thread, marking it for deletion.

**Parameters**

- **thread_identifier** (`string`, required) The unique identifier of the conversation thread to archive. This is a required field and should match the specific thread you wish to archive.

## HubspotConversationsApi.UpdateConversationThread

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_conversation_thread_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_conversation_thread_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Update the status or restore a conversation thread.

**Parameters**

- **thread_identifier** (`string`, required) The unique identifier for the conversation thread to update or restore.
- **is_thread_archived** (`boolean`, optional) Set to true to archive or false to restore the thread. Determines if the thread is currently archived.
- **thread_status** (`string`, optional) Set the thread's status to `OPEN` or `CLOSED`.

## HubspotConversationsApi.RetrieveFullMessageContent

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_full_message_content_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_full_message_content_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve the original text and rich text of a HubSpot message.

**Parameters**

- **conversation_thread_id** (`string`, required) The unique identifier for the conversation thread containing the message.
- **message_id** (`string`, required) The unique identifier for the message. Used to retrieve the message's full original content.

## HubspotConversationsApi.ListConversationChannels

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/list_conversation_channels_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/list_conversation_channels_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve a list of conversation channels from Hubspot.

**Parameters**

This tool does not take any parameters.

## HubspotConversationsApi.RetrieveActorDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_actor_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_actor_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details of a specific actor by actor ID.

**Parameters**

- **actor_id** (`string`, required) The unique identifier for the actor whose details are to be retrieved.

## HubspotConversationsApi.RetrieveConversationThreads

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_conversation_threads_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_conversation_threads_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve conversation threads from Hubspot Conversations.

**Parameters**

This tool does not take any parameters.

## HubspotConversationsApi.GetMessageHistoryForThread

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_message_history_for_thread_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_message_history_for_thread_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve the message history for a specific thread.

**Parameters**

- **thread_id** (`string`, required) The unique identifier for the conversation thread whose message history is to be retrieved.

## HubspotConversationsApi.SendConversationMessage

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/send_conversation_message_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/send_conversation_message_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Send a new message in a conversation thread.

**Parameters**

- **mode** (`Enum` [ToolMode](#toolmode), required) Operation mode: 'get_request_schema' returns the OpenAPI spec for the request body, 'execute' performs the actual operation
- **thread_id** (`string`, optional) The unique identifier for the conversation thread where the message will be sent. It should be a string that corresponds to the existing thread ID in Hubspot. Required when mode is 'execute', ignored when mode is 'get_request_schema'.
- **request_body** (`string`, optional) Stringified JSON representing the request body. Required when mode is 'execute', ignored when mode is 'get_request_schema'

## HubspotConversationsApi.ResolveConversationActors

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/resolve_conversation_actors_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/resolve_conversation_actors_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Resolve ActorIds to conversation participants.

**Parameters**

- **actor_ids** (`array[string]`, required) A list of Actor IDs to resolve into detailed participant information. Each entry should be a string representing an Actor ID.

## HubspotConversationsApi.GetChannelAccountDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_channel_account_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_channel_account_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details of a HubSpot channel account by ID.

**Parameters**

- **channel_account_id** (`string`, required) The unique ID of the HubSpot channel account to retrieve details for. This ID is required to fetch the channel account's information.

## HubspotConversationsApi.RetrieveChannelAccounts

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_accounts_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_accounts_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve a list of channel accounts from Hubspot.

**Parameters**

This tool does not take any parameters.

## HubspotConversationsApi.RetrieveChannelDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details of a channel using its ID.

**Parameters**

- **channel_id** (`string`, required) The unique ID of the channel to retrieve details for in Hubspot Conversations.

## HubspotConversationsApi.GetInboxDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_inbox_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_inbox_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details of a conversation inbox by ID.

**Parameters**

- **inbox_id** (`string`, required) The unique identifier for the conversation inbox you wish to retrieve details for. It should be a string representing the inbox ID.

## HubspotConversationsApi.RetrieveThreadMessage

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_thread_message_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_thread_message_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve a single message from a conversation thread.

**Parameters**

- **message_id** (`string`, required) The unique identifier for the specific message within a thread. Used to retrieve message details.
- **thread_id** (`string`, required) The unique identifier of the conversation thread from which to retrieve the message.

## HubspotConversationsApi.GetCustomChannelMessageDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_custom_channel_message_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_custom_channel_message_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details for a specific message in a custom channel.

**Parameters**

- **channel_id** (`string`, required) The unique identifier for the custom channel from which the message was sent. Required to fetch specific message details.
- **message_id** (`string`, required) The unique identifier of the message to retrieve details for. This ID is used to specify the exact message in the custom channel.

## HubspotConversationsApi.UpdateMessageStatus

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_message_status_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_message_status_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Update the status of a conversation message.

**Parameters**

- **channel_identifier** (`string`, required) The unique identifier for the custom channel where the message is located. It is required to specify which channel the message belongs to.
- **message_id** (`string`, required) Unique identifier of the message to be updated.
- **message_status** (`string`, required) Specifies the status of the message. Valid values are SENT, FAILED, and READ.
- **error_message_for_failed_status** (`string`, optional) Provide an error message when the status is FAILED to clarify the reason for failure. Only use this when 'statusType' is 'FAILED'.

## HubspotConversationsApi.UpdateChannelAccountStaging

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_channel_account_staging_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_channel_account_staging_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Update channel account staging token details for public apps.

**Parameters**

- **account_name** (`string`, required) The name of the account to be updated for the channel account staging token.
- **account_token** (`string`, required) The unique token identifying the specific channel account staging. Required for updating account details.
- **channel_id** (`string`, required) The unique identifier for the channel to update. This is necessary to specify which channel's staging token details are being modified.
- **delivery_identifier_type** (`string`, required) Type of delivery identifier: HS_EMAIL_ADDRESS, HS_PHONE_NUMBER, or CHANNEL_SPECIFIC_OPAQUE_ID.
- **delivery_identifier_value** (`string`, required) The PublicDeliveryIdentifier in string format, such as an E.164 phone number, an email address, or a channel-specific identifier.

## HubspotConversationsApi.GetCustomChannelAccounts

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_custom_channel_accounts_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/get_custom_channel_accounts_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve accounts for a specified custom channel.

**Parameters**

- **custom_channel_id** (`string`, required) The unique identifier of the custom channel to retrieve accounts for. Must be a valid string.

## HubspotConversationsApi.CreateChannelAccount

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/create_channel_account_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/create_channel_account_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Create a new account for a specified communication channel.

**Parameters**

- **account_name** (`string`, required) The name of the account to be created for the channel. It identifies the account within the specified communication channel.
- **channel_id** (`string`, required) The unique identifier for the communication channel where the account will be created. This should be a string value.
- **inbox_id** (`string`, required) The unique identifier for the inbox where the channel account will be created. This should be a string that corresponds to an existing inbox in Hubspot.
- **is_authorized** (`boolean`, required) Boolean to indicate if the account should be authorized. Set to true for authorized accounts, false otherwise.
- **delivery_identifier_type** (`string`, optional) Type of identifier: HS_EMAIL_ADDRESS, HS_PHONE_NUMBER, or CHANNEL_SPECIFIC_OPAQUE_ID.
- **delivery_identifier_value** (`string`, optional) A string representation of the delivery identifier. Can be an E.164 phone number, an email address, or a channel-specific identifier.

## HubspotConversationsApi.RetrieveChannelAccountDetails

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_account_details_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/retrieve_channel_account_details_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Retrieve details for a specific channel account.

**Parameters**

- **channel_account_id** (`string`, required) Unique identifier for the specific channel account to retrieve details about. Provided as a string.
- **channel_identifier** (`string`, required) The unique identifier for the channel. Used to specify which channel's account details to retrieve.

## HubspotConversationsApi.UpdateChannelAccountInfo

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_channel_account_info_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/update_channel_account_info_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Update channel account name and authorization status.

**Parameters**

- **channel_account_id** (`string`, required) The unique identifier for the channel account to be updated. It is required for specifying which channel account to modify.
- **channel_id** (`string`, required) The unique identifier for the channel in Hubspot Conversations. Required to specify which channel account to update.
- **channel_account_name** (`string`, optional) The new name for the channel account. This updates the display name associated with the account.
- **set_authorization_status** (`boolean`, optional) Boolean value to update the channel account's authorization. Set to False to disable the account.

## HubspotConversationsApi.PublishCustomChannelMessage

<br />
<TabbedCodeBlock
  tabs={[
    {
      label: "Call the Tool Directly",
      content: {
        Python: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/publish_custom_channel_message_example_call_tool.py",
        ],
        JavaScript: [
          "/examples/integrations/resources/integrations/hubspot_conversations_api/publish_custom_channel_message_example_call_tool.js",
        ],
      },
    },
  ]}
/>

Publish a message to a custom channel on HubSpot.

**Parameters**

- **mode** (`Enum` [ToolMode](#toolmode), required) Operation mode: 'get_request_schema' returns the OpenAPI spec for the request body, 'execute' performs the actual operation
- **custom_channel_id** (`string`, optional) The unique ID of the custom channel where the message will be published. Must be a string. Required when mode is 'execute', ignored when mode is 'get_request_schema'.
- **request_body** (`string`, optional) Stringified JSON representing the request body. Required when mode is 'execute', ignored when mode is 'get_request_schema'

## Reference

Below is a reference of enumerations used by some of the tools in the HubspotConversationsApi MCP Server:

### ToolMode

- **GET_REQUEST_SCHEMA**: `get_request_schema`
- **EXECUTE**: `execute`

## Auth

The HubspotConversationsApi MCP Server uses the Auth Provider with id `arcade-hubspot` to connect to users' HubspotConversationsApi accounts. In order to use the MCP Server, you will need to configure the `arcade-hubspot` auth provider.

<ToolFooter pipPackageName="arcade_hubspot_conversations_api" />