Conversations inbox and messages APIs (BETA)

The conversations APIs enable you to manage and interact with the conversations inbox, channels, and messages. For example, you can use these APIs to:

• Get and sort conversations inboxes, channels, threads, and messages.
• Update thread statuses.
• Delete and restore threads.
• Send outbound messages via existing conversations channels.
• Send an internal comment to an agent. 
• Retrieve conversation data to create advanced reports and analytics in external tools.

You could also use these APIs to integrate existing channels with other apps such as Slack or Microsoft Teams to send replies or receive notifications. 

To get started with the conversations APIs, make sure you have set up a HubSpot developer account and created an app. You will need a developer account ID and app ID to get access to these APIs. 

You can also use webhooks with the conversations API. Learn more about the available webhook events.

To view all available endpoints and their requirements, click the Endpoints tab at the top of this article.

When retrieving inboxes, channels, channel accounts, threads, and messages using the endpoints outlined in this article, you can use different query parameters to filter and sort your responses. 

You can also sort your results by any field on the channel, channel accounts, or inbox objects. For example, you could sort inboxes by name, or channel accounts by both channel ID and name. 

You can retrieve a list of the channels connected to your inboxes by making a GET request to conversations/v3/conversations/channels. 

When you make a successful request, the response will include the channel IDs for the different channels connected to your inbox. To retrieve a specific channel, use the channel ID to make a GET request to conversations/v3/conversations/channels/{channelId}. 

You can also retrieve channel accounts, which are instances of a channel that are used to send and receive messages, like a specific chatflow created for one of your chat channels or a team email address connected as an email channel. 

To retrieve a list of channel accounts, make a GET request to conversations/v3/conversations/channel-accounts. You can limit the results by including the following parameters in the request URL: 

For example, your request may look similar to the following:
https://api.hubspot.com/conversations/v3/conversations/channel-accounts?channelId=1000&inboxId=448.

When you make a successful request, the response will include an ID number, which is the channel account ID.

You can use the channel account ID to retrieve a single channel account, such as a specific chatflow. To retrieve a specific channel account, make a GET request to conversations/v3/conversations/channel-accounts/{channelAccountId}. 

Threads are a group of related messages that make up a conversation in the inbox. To retrieve a list of all threads in your conversations inbox, make a GET request to conversations/v3/conversations/threads. To filter and search your results, you can use the following parameters in your request:

When you make a successful request, the response will include the thread ID, which you can use to retrieve, update, or create a new message in a thread. 

To retrieve a specific thread by thread ID, make a GET request to conversations/v3/conversations/threads/{threadId}. 

To get the entire message history, make a GET request to conversations/v3/conversations/threads/{threadId}/messages.

When you make a successful request, the response will include the message ID, which you can use to retrieve a specific message. To do so, make a GET request to conversations/v3/conversations/threads/{threadId}/messages/{messageId}. 

For email messages, HubSpot cuts off the reply history section of an email. This is similar to how common mail clients handle reply history and longer emails. When you retrieve a message, the response will include a truncationStatus field. The value will either be NOT_TRUNCATED, TRUNCATED_TO_MOST_RECENT_REPLY, or TRUNCATED.

If a message is truncated, you can make a GET request to conversations/v3/conversations/threads/{threadId}/messages/{messageId}/original-content. This will retrieve the full original version of the message. 

You can also fetch messages associated with a single contact, which can be helpful if you're creating a view where a customer can review the conversations they've had with your business.

To filter for messages associated with a contact, provide the ID of the contact as the associatedContactId as a query parameter in the URL of your request, along with a threadStatus parameter, which can be either OPEN or CLOSED.

For example, to retrieve open threads associated with a contact whose ID is 53701, you'd make a GET request to the following URL:

https://api.hubapi.com/conversations/v3/conversations/threads?associatedContactId=53701&threadStatus=OPEN

Actors are entities that interact with conversations, like a HubSpot user responding to a message or a visitor sending a message. When you make a request to retrieve threads or messages, the response will include actor IDs.

All actor IDs are a single letter representing the actor type, followed by a hyphen, followed by an identifier for the actor. The identifier could be a number, a string, etc. depending on the actor type. In the table below, learn more about the different actor IDs: 

For example, if you make a GET request to conversations/v3/conversations/threads/{threadId}/messages, the response will include a sender and recipient fields. These fields will include the actor IDs for the visitor or agent. For example, your response may look similar to the following: To retrieve a single actor, make a GET request to conversations/v3/conversations/actors/{actorId}. You will need the actorId, which is included in the response to a request to get a message or thread. The response will return details like the actor name, email address, avatar, and actor type. 

You can update a thread's status by making a PATCH request to conversations/v3/conversations/threads/{threadId}. In the request body, include the thread properties to update. 

To restore any soft-deleted threads, make a PATCH request to conversations/v3/conversations/threads/{threadId}?archived=true to retrieve the archived thread, then in the request body set the archived property to false. 

You can archive a thread by making a DELETE request to conversations/v3/conversations/threads/{threadId}. 

If you use this endpoint to archive a thread, the thread will be moved to the trash and will be permanently deleted after 30 days. In the section above, learn how to restore a thread before it is permanently deleted. 

To add a comment to an existing thread, make a POST request to conversations/v3/conversations/threads/{threadId}/messages. Comments only appear in the inbox and are not sent to visitors.

You can include the following fields in the request body when sending a comment: 

For example, your request body may look similar to the following:

Using this endpoint, an integration can send outgoing messages as a user in a HubSpot account. These messages are sent from the channel, just like if a user typed and sent a response in the inbox. To send a message to an existing thread, make a POST request to conversations/v3/conversations/threads/{threadId}/messages. 

When sending a message to a thread, you can include the following fields. You can include both the message details, as well as recipient information, in the request body. 

If you make a successful request, the new message will be sent to the visitor. This can appear as a message in the chat widget, an email in the thread, a message in Facebook Messenger, etc. 

Attachments can be links to a file hosted in the HubSpot files tool, or a set of quick replies if you're sending a message using Facebook Messenger or LiveChat.

To include an attachment from a file in your HubSpot account, provide the absolute URL as the fileId in the attachments field of the request body. For example, the corresponding part of the request body is shown in lines 10-12 below:

If you connected Facebook Messenger or LiveChat as a channel, you can also specify a set of quick replies within the attachments field, which prompt the recipient with certain options that appear as tappable buttons below a message. Once tapped, the corresponding value of that option will be recorded.

Quick replies should be provided as a list of objects that each contain the following fields:

• label: the visible text that appears to the recipient (e.g., Red)
• value: the associated value of the button that you want to record  (e.g., RED)
• valueType: the type of the quick reply option, which can be either TEXT or URL.

The example request body below demonstrates how to specify two quick reply options, Yes and No, on lines 10-23:

Webhooks for conversations are also supported and can be used in tandem with the conversations API. You can use webhooks to subscribe to events about conversations, including thread creation, thread status and assignment changes, and new messages on threads. Learn more about using webhooks. 

You must have the conversations.read scope to get access to following webhooks.

The available conversation webhook events are:

The available properties for each event type are: