Conversations API Documentation

Developer Support APIs & Integrations
1

Hi everyone,I’m working with the HubSpot Conversations API v3 for custom channels and have two related questions:1. Setting a message subject
I’m creating incoming messages using:

POST /conversations/v3/custom-channels/{channelId}/messages

My payload includes:

  • messageDirection: “INCOMING”

  • text: plain text content

  • richText: HTML formatted content

  • integrationThreadId, channelAccountId, senders, etc.

    However, there’s no subject parameter available in this endpoint’s payload. Yet when I look at the GET message endpoint documentation:

    GET /conversations/v3/custom-channels/{channelId}/messages/{messageId}

    It shows that a subject field should be returned in the response.Questions:

    • How do I set the subject when creating a message via custom channels?

    • Does HubSpot auto-extract it from the message content?

    • Is there a different endpoint or method I should be using?

      2. Retrieving the associated ticket ID
      After creating a message, I need to get the ticket ID that was created/associated with it. I’m using:
      c

      GET /conversations/v3/conversations/threads/{threadId}

      The docs show it should return threadAssociations.associatedTicketId.
      Questions:

      • Is the ticket auto-created when I POST a message, or do I need to create it separately?

      • Is there a delay before associatedTicketId becomes available?

      • Do I need special channel configuration for automatic ticket creation?

          Any guidance would be appreciated! Thanks!
2

Hi @rginsberg549,
Thank you for posting to the Community!
I understand that you’re seeking clarification on how to set a message subject when creating messages via the HubSpot Conversations API v3 for custom channels, as well as how to retrieve the associated ticket ID after message creation (and whether tickets are auto-created.

I would like to tag in some of our Top Contributors to take a look here.
Hi @hhawk @WesQ and @ChrisoKlepke Do any of you have any suggestions for @rginsberg549?
Thank you!
Cassie, Community Manager

3

Hey @rginsberg549 ,

The custom channel message endpoint doesn’t accept or process a subject field. That attribute is only supported when creating messages through thread-based endpoints, which are designed to represent ongoing conversations within HubSpot. The subject value you see in API responses applies only to those thread messages, not to messages posted directly via custom channels. HubSpot also doesn’t attempt to infer or auto-generate a subject from the message text or rich content. If your use case requires a subject line to appear in the conversation, you’ll need to post the message to a specific thread rather than to the channel endpoint.

To retrieve the associated ticket, request the thread data with the associations parameter set to ticket. The linked ticket ID will appear within the thread associations object once it exists. Whether a ticket is automatically created depends on your inbox configuration specifically, whether the “Automatically create tickets” option is turned on for that channel. If it isn’t, you’ll need to create and associate the ticket manually. Be aware that even when automatic creation is enabled, there can be a short propagation delay before the ticket ID becomes available in the response.

I hope this helps clarify the issue and provides the context you needed. If this solved your problem, please mark it as the accepted solution and give it an upvote — it’ll help others in the community who might face the same issue.

4

1.) My custom channel is connect to the “Help Desk” inbox which appears to be separate from “Inboxes”. The language “Any customer requests will be received as tickets in your help desk.” makes me believe ticket creation happens automatically for any channel connected.

Screenshot 2025-10-06 at 10.24.39 AM.png
Screenshot 2025-10-06 at 10.24.39 AM.png2148×352 65.2 KB

2.) I am only able to enable automatic ticket assignment in the channel configurations.

Screenshot 2025-10-06 at 10.25.25 AM.png
Screenshot 2025-10-06 at 10.25.25 AM.png1350×616 87.2 KB

3.) This is what I see after creating a new “conversation”

Screenshot 2025-10-06 at 10.27.20 AM.png
Screenshot 2025-10-06 at 10.27.20 AM.png2606×1598 306 KB

4.) Even after waiting, longer than 5 minutes, the associatedTicketId is not being returned when making a GET request using the threadID. Will provide details here shortly.-GET Message - https://api.hubapi.com/conversations/v3/custom-channels/1752326/messages/be93309cdb26085f852020f986a6137b

{
 "id": "be93309cdb26085f852020f986a6137b",
 "conversationsThreadId": "9591826107",
 "createdAt": "2025-10-06T17:33:31.443Z",
 "updatedAt": "2025-10-06T17:33:31.589Z",
 "createdBy": "V-250020938462",
 "client": {
 "clientType": "SYSTEM"
 },
 "senders": [
 {
 "actorId": "V-250020938462",
 "name": "Jane Doe",
 "deliveryIdentifier": {
 "type": "HS_EMAIL_ADDRESS",
 "value": "jane.doe@example.com"
 }
 }
 ],
 "recipients": [
 {
 "name": "Support Team",
 "deliveryIdentifier": {
 "type": "HS_EMAIL_ADDRESS",
 "value": "support@getstreamline.com"
 }
 }
 ],
 "archived": false,
 "text": "I cannot access my account",
 "richText": "I cannot access my account",
 "attachments": [],
 "truncationStatus": "NOT_TRUNCATED",
 "status": {
 "statusType": "RECEIVED"
 },
 "direction": "INCOMING",
 "channelId": "1752326",
 "channelAccountId": "2054675314",
 "type": "MESSAGE"
}

Get Single Thread - https://api.hubapi.com/conversations/v3/conversations/threads/9591826107

{
 "id": "9591826107",
 "createdAt": "2025-10-06T17:27:01.074Z",
 "status": "OPEN",
 "originalChannelId": "1752326",
 "originalChannelAccountId": "2054675314",
 "latestMessageTimestamp": "2025-10-06T17:33:31.443Z",
 "latestMessageReceivedTimestamp": "2025-10-06T17:33:31.443Z",
 "spam": false,
 "inboxId": "486271143",
 "associatedContactId": "250020938462",
 "archived": false
}

None of these responses are including the threadAssociations

5

My custom channel is connect to the “Help Desk” inbox which appears to be separate from “Inboxes”. The language “Any customer requests will be received as tickets in your help desk.” makes me believe ticket creation happens automatically for any channel connected.

Screenshot 2025-10-06 at 10.24.39 AM.png
Screenshot 2025-10-06 at 10.24.39 AM.png2148×352 65.2 KB

I am only able to enable automatic ticket assignment in the channel configurations.

Screenshot 2025-10-06 at 10.25.25 AM.png
Screenshot 2025-10-06 at 10.25.25 AM.png1350×616 87.2 KB

This is what I see after creating a new “conversation”

Screenshot 2025-10-06 at 10.27.20 AM.png
Screenshot 2025-10-06 at 10.27.20 AM.png2606×1598 306 KB

Even after waiting, longer than 5 minutes, the associatedTicketId is not being returned when making a GET request using the threadID. Will provide details here shortly.-GET Message - https://api.hubapi.com/conversations/v3/custom-channels/1752326/messages/be93309cdb26085f852020f986a6137b

{
 "id": "be93309cdb26085f852020f986a6137b",
 "conversationsThreadId": "9591826107",
 "createdAt": "2025-10-06T17:33:31.443Z",
 "updatedAt": "2025-10-06T17:33:31.589Z",
 "createdBy": "V-250020938462",
 "client": {
 "clientType": "SYSTEM"
 },
 "senders": [
 {
 "actorId": "V-250020938462",
 "name": "Jane Doe",
 "deliveryIdentifier": {
 "type": "HS_EMAIL_ADDRESS",
 "value": "jane.doe@example.com"
 }
 }
 ],
 "recipients": [
 {
 "name": "Support Team",
 "deliveryIdentifier": {
 "type": "HS_EMAIL_ADDRESS",
 "value": "support@getstreamline.com"
 }
 }
 ],
 "archived": false,
 "text": "I cannot access my account",
 "richText": "I cannot access my account",
 "attachments": [],
 "truncationStatus": "NOT_TRUNCATED",
 "status": {
 "statusType": "RECEIVED"
 },
 "direction": "INCOMING",
 "channelId": "1752326",
 "channelAccountId": "2054675314",
 "type": "MESSAGE"
}

Get Single Thread - https://api.hubapi.com/conversations/v3/conversations/threads/9591826107

{
 "id": "9591826107",
 "createdAt": "2025-10-06T17:27:01.074Z",
 "status": "OPEN",
 "originalChannelId": "1752326",
 "originalChannelAccountId": "2054675314",
 "latestMessageTimestamp": "2025-10-06T17:33:31.443Z",
 "latestMessageReceivedTimestamp": "2025-10-06T17:33:31.443Z",
 "spam": false,
 "inboxId": "486271143",
 "associatedContactId": "250020938462",
 "archived": false
}

None of these responses are including the threadAssociations
@suprdense @chighsmith @hhawk @WesQ @ChrisoKlepke

6

To retrieve the threadAssociations.associatedTicketId section you need to do the GET thread with the following parameter:

“/conversations/#{@conversations_api_version}/conversations/threads/#{thread_id}?association=ticket”

mind it’s “association” and “ticket”, in the singular form. I spent countless hours/days because I was using the plural form :slightly_smiling_face:

7

The true heroes in this community are the folks who take the time to come back and update posts. Thanks for being a real on @hugo-at-ukio :raising_hands: — Jaycee