Publish a message

curl --request POST \
  --url https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attachments": [
    {
      "fileId": "<string>",
      "type": "FILE"
    }
  ],
  "channelAccountId": "<string>",
  "recipients": [
    {
      "deliveryIdentifier": {
        "value": "<string>"
      },
      "name": "<string>",
      "senderActorId": "<string>"
    }
  ],
  "senders": [
    {
      "deliveryIdentifier": {
        "value": "<string>"
      },
      "name": "<string>",
      "senderActorId": "<string>"
    }
  ],
  "text": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "associateWithContactId": 123,
  "inReplyToId": "<string>",
  "integrationIdempotencyId": "<string>",
  "integrationThreadId": "<string>",
  "richText": "<string>"
}
'

import requests

url = "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages"

payload = {
    "attachments": [
        {
            "fileId": "<string>",
            "type": "FILE"
        }
    ],
    "channelAccountId": "<string>",
    "recipients": [
        {
            "deliveryIdentifier": { "value": "<string>" },
            "name": "<string>",
            "senderActorId": "<string>"
        }
    ],
    "senders": [
        {
            "deliveryIdentifier": { "value": "<string>" },
            "name": "<string>",
            "senderActorId": "<string>"
        }
    ],
    "text": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "associateWithContactId": 123,
    "inReplyToId": "<string>",
    "integrationIdempotencyId": "<string>",
    "integrationThreadId": "<string>",
    "richText": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attachments: [{fileId: '<string>', type: 'FILE'}],
    channelAccountId: '<string>',
    recipients: [
      {
        deliveryIdentifier: {value: '<string>'},
        name: '<string>',
        senderActorId: '<string>'
      }
    ],
    senders: [
      {
        deliveryIdentifier: {value: '<string>'},
        name: '<string>',
        senderActorId: '<string>'
      }
    ],
    text: '<string>',
    timestamp: '2023-11-07T05:31:56Z',
    associateWithContactId: 123,
    inReplyToId: '<string>',
    integrationIdempotencyId: '<string>',
    integrationThreadId: '<string>',
    richText: '<string>'
  })
};

fetch('https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attachments' => [
        [
                'fileId' => '<string>',
                'type' => 'FILE'
        ]
    ],
    'channelAccountId' => '<string>',
    'recipients' => [
        [
                'deliveryIdentifier' => [
                                'value' => '<string>'
                ],
                'name' => '<string>',
                'senderActorId' => '<string>'
        ]
    ],
    'senders' => [
        [
                'deliveryIdentifier' => [
                                'value' => '<string>'
                ],
                'name' => '<string>',
                'senderActorId' => '<string>'
        ]
    ],
    'text' => '<string>',
    'timestamp' => '2023-11-07T05:31:56Z',
    'associateWithContactId' => 123,
    'inReplyToId' => '<string>',
    'integrationIdempotencyId' => '<string>',
    'integrationThreadId' => '<string>',
    'richText' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages"

	payload := strings.NewReader("{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "archived": true,
  "attachments": [
    {
      "fileId": "<string>",
      "fileUsageType": "AUDIO",
      "type": "FILE",
      "name": "<string>",
      "url": "<string>"
    }
  ],
  "channelAccountId": "<string>",
  "channelId": "<string>",
  "client": {
    "clientType": "HUBSPOT",
    "integrationAppId": 123
  },
  "conversationsThreadId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "direction": "INCOMING",
  "id": "<string>",
  "recipients": [
    {
      "deliveryIdentifier": {
        "type": "CHANNEL_SPECIFIC_OPAQUE_ID",
        "value": "<string>"
      },
      "actorId": "<string>",
      "name": "<string>",
      "recipientField": "<string>"
    }
  ],
  "senders": [
    {
      "actorId": "<string>",
      "deliveryIdentifier": {
        "type": "CHANNEL_SPECIFIC_OPAQUE_ID",
        "value": "<string>"
      },
      "name": "<string>",
      "senderField": "<string>"
    }
  ],
  "text": "<string>",
  "truncationStatus": "NOT_TRUNCATED",
  "type": "MESSAGE",
  "inReplyToId": "<string>",
  "richText": "<string>",
  "status": {
    "statusType": "FAILED",
    "failureDetails": {
      "errorMessageTokens": {},
      "errorMessage": "<string>"
    }
  },
  "subject": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "message": "Invalid input (details will vary based on the error)",
  "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
  "category": "VALIDATION_ERROR",
  "links": {
    "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
  }
}

POST

conversations

custom-channels

2026-03

{channelId}

messages

Publish a message

curl --request POST \
  --url https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attachments": [
    {
      "fileId": "<string>",
      "type": "FILE"
    }
  ],
  "channelAccountId": "<string>",
  "recipients": [
    {
      "deliveryIdentifier": {
        "value": "<string>"
      },
      "name": "<string>",
      "senderActorId": "<string>"
    }
  ],
  "senders": [
    {
      "deliveryIdentifier": {
        "value": "<string>"
      },
      "name": "<string>",
      "senderActorId": "<string>"
    }
  ],
  "text": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "associateWithContactId": 123,
  "inReplyToId": "<string>",
  "integrationIdempotencyId": "<string>",
  "integrationThreadId": "<string>",
  "richText": "<string>"
}
'

import requests

url = "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages"

payload = {
    "attachments": [
        {
            "fileId": "<string>",
            "type": "FILE"
        }
    ],
    "channelAccountId": "<string>",
    "recipients": [
        {
            "deliveryIdentifier": { "value": "<string>" },
            "name": "<string>",
            "senderActorId": "<string>"
        }
    ],
    "senders": [
        {
            "deliveryIdentifier": { "value": "<string>" },
            "name": "<string>",
            "senderActorId": "<string>"
        }
    ],
    "text": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "associateWithContactId": 123,
    "inReplyToId": "<string>",
    "integrationIdempotencyId": "<string>",
    "integrationThreadId": "<string>",
    "richText": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    attachments: [{fileId: '<string>', type: 'FILE'}],
    channelAccountId: '<string>',
    recipients: [
      {
        deliveryIdentifier: {value: '<string>'},
        name: '<string>',
        senderActorId: '<string>'
      }
    ],
    senders: [
      {
        deliveryIdentifier: {value: '<string>'},
        name: '<string>',
        senderActorId: '<string>'
      }
    ],
    text: '<string>',
    timestamp: '2023-11-07T05:31:56Z',
    associateWithContactId: 123,
    inReplyToId: '<string>',
    integrationIdempotencyId: '<string>',
    integrationThreadId: '<string>',
    richText: '<string>'
  })
};

fetch('https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'attachments' => [
        [
                'fileId' => '<string>',
                'type' => 'FILE'
        ]
    ],
    'channelAccountId' => '<string>',
    'recipients' => [
        [
                'deliveryIdentifier' => [
                                'value' => '<string>'
                ],
                'name' => '<string>',
                'senderActorId' => '<string>'
        ]
    ],
    'senders' => [
        [
                'deliveryIdentifier' => [
                                'value' => '<string>'
                ],
                'name' => '<string>',
                'senderActorId' => '<string>'
        ]
    ],
    'text' => '<string>',
    'timestamp' => '2023-11-07T05:31:56Z',
    'associateWithContactId' => 123,
    'inReplyToId' => '<string>',
    'integrationIdempotencyId' => '<string>',
    'integrationThreadId' => '<string>',
    'richText' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages"

	payload := strings.NewReader("{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hubapi.com/conversations/custom-channels/2026-03/{channelId}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"attachments\": [\n    {\n      \"fileId\": \"<string>\",\n      \"type\": \"FILE\"\n    }\n  ],\n  \"channelAccountId\": \"<string>\",\n  \"recipients\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"senders\": [\n    {\n      \"deliveryIdentifier\": {\n        \"value\": \"<string>\"\n      },\n      \"name\": \"<string>\",\n      \"senderActorId\": \"<string>\"\n    }\n  ],\n  \"text\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"associateWithContactId\": 123,\n  \"inReplyToId\": \"<string>\",\n  \"integrationIdempotencyId\": \"<string>\",\n  \"integrationThreadId\": \"<string>\",\n  \"richText\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "archived": true,
  "attachments": [
    {
      "fileId": "<string>",
      "fileUsageType": "AUDIO",
      "type": "FILE",
      "name": "<string>",
      "url": "<string>"
    }
  ],
  "channelAccountId": "<string>",
  "channelId": "<string>",
  "client": {
    "clientType": "HUBSPOT",
    "integrationAppId": 123
  },
  "conversationsThreadId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "direction": "INCOMING",
  "id": "<string>",
  "recipients": [
    {
      "deliveryIdentifier": {
        "type": "CHANNEL_SPECIFIC_OPAQUE_ID",
        "value": "<string>"
      },
      "actorId": "<string>",
      "name": "<string>",
      "recipientField": "<string>"
    }
  ],
  "senders": [
    {
      "actorId": "<string>",
      "deliveryIdentifier": {
        "type": "CHANNEL_SPECIFIC_OPAQUE_ID",
        "value": "<string>"
      },
      "name": "<string>",
      "senderField": "<string>"
    }
  ],
  "text": "<string>",
  "truncationStatus": "NOT_TRUNCATED",
  "type": "MESSAGE",
  "inReplyToId": "<string>",
  "richText": "<string>",
  "status": {
    "statusType": "FAILED",
    "failureDetails": {
      "errorMessageTokens": {},
      "errorMessage": "<string>"
    }
  },
  "subject": "<string>",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "message": "Invalid input (details will vary based on the error)",
  "correlationId": "aeb5f871-7f07-4993-9211-075dc63e7cbf",
  "category": "VALIDATION_ERROR",
  "links": {
    "knowledge-base": "https://www.hubspot.com/products/service/knowledge-base"
  }
}

Supported products

Required Scopes

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

FlowAuthorization Code

Authorization URL: https://app.hubspot.com/oauth/authorize
Token URL: https://api.hubapi.com/oauth/v1/token

Scopes1

conversations.custom_channels.write

Path Parameters

channelId

integer<int32>

required

The unique identifier of the custom channel where the message will be created.

Body

application/json

attachments

required

An array of attachments included with the message, which can be files, locations, contacts, or other supported types.

Show child attributes

channelAccountId

string

required

The ID of the channel account through which the message is sent.

messageDirection

enum<string>

required

The direction of the message, indicating whether it is 'INCOMING' or 'OUTGOING'.

Available options:

INCOMING,

OUTGOING

recipients

object[]

required

An array of participants representing the recipients of the message.

Show child attributes

senders

object[]

required

An array of participants representing the senders of the message.

Show child attributes

text

string

required

The plain text content of the message.

timestamp

string<date-time>

required

The date and time when the message was created, in ISO 8601 format.

associateWithContactId

integer<int64>

The ID of the contact with which this message should be associated.

inReplyToId

string

The ID of the message this message is replying to.

integrationIdempotencyId

string

A unique identifier to ensure idempotency of the message within the integration.

integrationThreadId

string

A unique identifier for the thread within the integration.

preResolvedContacts

object

Show child attributes

richText

string

The rich text content of the message, allowing for formatting.

Response

successful operation

archived

boolean

required

A boolean indicating whether the message is archived.

attachments

required

An array of attachments included with the message, which can be files, locations, contacts, or other supported types.

Show child attributes

channelAccountId

string

required

The identifier of the channel account associated with the message.

channelId

string

required

The identifier of the channel through which the message was sent.

client

object

required

Show child attributes

conversationsThreadId

string

required

The identifier for the conversation thread to which this message belongs.

createdAt

string<date-time>

required

The date and time when the message was created, in ISO 8601 format.

createdBy

string

required

The identifier of the user or system that created the message.

direction

enum<string>

required

The direction of the message, either 'INCOMING' or 'OUTGOING'.

Available options:

INCOMING,

OUTGOING

string

required

The unique identifier for the message.

recipients

object[]

required

An array of recipients of the message, each containing recipient details.

Show child attributes

senders

object[]

required

An array of senders associated with the message, each containing sender details.

Show child attributes

text

string

required

The plain text content of the message.

truncationStatus

enum<string>

required

Indicates whether the message content is truncated. Valid values are 'NOT_TRUNCATED', 'TRUNCATED_TO_MOST_RECENT_REPLY', and 'TRUNCATED'.

Available options:

NOT_TRUNCATED,

TRUNCATED,

TRUNCATED_TO_MOST_RECENT_REPLY

type

enum<string>

default:MESSAGE

required

The type of the message, which is always 'MESSAGE'.

Available options:

MESSAGE

inReplyToId

string

The identifier of the message to which this message is a reply, if applicable.

richText

string

The rich text content of the message, if available.

status

object

Show child attributes

subject

string

The subject of the message, if applicable.

updatedAt

string<date-time>

The date and time when the message was last updated, in ISO 8601 format.

Last modified on September 9, 2026