---
title: "Publish a message"
method: POST
path: "/conversations/v3/custom-channels/{channelId}/messages"
tags: ["Messages"]
---

# Publish a message

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

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/conversations/v3/custom-channels/{channelId}/messages`
- Auth: OAuth 2
  - Authorization code: `https://app.hubspot.com/oauth/authorize`
  - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `conversations.custom_channels.write`

Publish a message over your custom channel

## Path parameters

- `channelId` integer, required

## Request body

- ChannelIntegrationMessageEgg
  - `associateWithContactId` integer
  - `attachments` union[], required
    - union
      - FileAttachment
        - `fileId` string, required
        - `fileUsageType` 'AUDIO' | 'IMAGE' | 'OTHER' | 'STICKER' | 'VOICE_RECORDING'
        - `type` 'FILE', required
      - LocationAttachment
        - `address` string
        - `latitude` number, required
        - `longitude` number, required
        - `name` string
        - `type` 'LOCATION', required
        - `url` string
      - ContactAttachment
        - `contactProfile` ContactProfile, required
          - `addresses` ContactAddress[], required
            - `city` string
            - `country` string
            - `countryCode` string
            - `state` string
            - `street` string
            - `type` 'HOME' | 'WORK'
            - `zip` string
          - `emails` ContactEmail[], required
            - `email` string, required
            - `type` 'HOME' | 'WORK'
          - `name` ContactName
            - `firstName` string
            - `lastName` string
            - `middleName` string
            - `prefix` string
            - `suffix` string
          - `org` ContactOrg
            - `company` string
            - `department` string
            - `title` string
          - `phones` ContactPhone[], required
            - `phone` string, required
            - `type` 'CELL' | 'HOME' | 'MAIN' | 'WORK'
          - `urls` ContactUrl[], required
            - `type` 'HOME' | 'WORK'
            - `url` string, required
        - `type` 'CONTACT', required
      - UnsupportedContentAttachment
        - `type` 'UNSUPPORTED_CONTENT', required
      - MessageHeaderAttachment
        - `fileId` integer
        - `text` string
        - `type` 'MESSAGE_HEADER', required
      - QuickRepliesAttachment
        - `quickReplies` QuickReply[], required
          - `label` string
          - `value` string, required
          - `valueType` 'TEXT' | 'URL', required
        - `type` 'QUICK_REPLIES', required
      - SocialMetadataIntegrationAttachment
        - `socialMetadata` SocialMetadata, required
          - `description` string
          - `id` string
          - `mediaTitle` string
          - `mediaType` 'ARTICLE' | 'AUDIO' | 'CAROUSEL' | 'DOCUMENT' | 'GIF' | 'LINK' | 'NONE' | 'PHOTO' | 'POLL' | 'STORY' | 'VIDEO', required
          - `mediaUrl` string
          - `mediaUrlString` string
          - `thumbnailUrl` string
        - `type` 'SOCIAL_MEDIA_METADATA', required
  - `channelAccountId` string, required
  - `inReplyToId` string
  - `integrationIdempotencyId` string
  - `integrationThreadId` string
  - `messageDirection` 'INCOMING' | 'OUTGOING', required
  - `preResolvedContacts` PreResolvedContacts
    - `contacts` PreResolvedContact[], required
      - `contactPropertiesLeadingToMatch` string[], required
      - `contactVid` integer, required
  - `recipients` ChannelIntegrationParticipant[], required
    - `deliveryIdentifier` PublicDeliveryIdentifier, required
      - `type` 'CHANNEL_SPECIFIC_OPAQUE_ID' | 'HS_EMAIL_ADDRESS' | 'HS_PHONE_NUMBER' | 'HS_SHORT_CODE', required
      - `value` string, required
    - `name` string
    - `senderActorId` string
  - `richText` string
  - `senders` ChannelIntegrationParticipant[], required
    - `deliveryIdentifier` PublicDeliveryIdentifier, required
      - `type` 'CHANNEL_SPECIFIC_OPAQUE_ID' | 'HS_EMAIL_ADDRESS' | 'HS_PHONE_NUMBER' | 'HS_SHORT_CODE', required
      - `value` string, required
    - `name` string
    - `senderActorId` string
  - `text` string, required
  - `timestamp` string, date-time, required

## Response `201`

successful operation

- PublicConversationsMessage
  - `archived` boolean, required
  - `attachments` union[], required
    - union
      - PublicFile
        - `fileId` string, required
        - `fileUsageType` 'AUDIO' | 'IMAGE' | 'OTHER' | 'STICKER' | 'VOICE_RECORDING', required
        - `name` string
        - `type` 'FILE', required
        - `url` string
      - PublicLocation
        - `address` string
        - `latitude` number, required
        - `longitude` number, required
        - `name` string
        - `type` 'LOCATION', required
        - `url` string
      - PublicContact
        - `contactProfile` ContactProfile, required
          - `addresses` ContactAddress[], required
            - `city` string
            - `country` string
            - `countryCode` string
            - `state` string
            - `street` string
            - `type` 'HOME' | 'WORK'
            - `zip` string
          - `emails` ContactEmail[], required
            - `email` string, required
            - `type` 'HOME' | 'WORK'
          - `name` ContactName
            - `firstName` string
            - `lastName` string
            - `middleName` string
            - `prefix` string
            - `suffix` string
          - `org` ContactOrg
            - `company` string
            - `department` string
            - `title` string
          - `phones` ContactPhone[], required
            - `phone` string, required
            - `type` 'CELL' | 'HOME' | 'MAIN' | 'WORK'
          - `urls` ContactUrl[], required
            - `type` 'HOME' | 'WORK'
            - `url` string, required
        - `type` 'CONTACT', required
      - PublicUnsupportedContent
        - `type` 'UNSUPPORTED_CONTENT', required
      - PublicMessageHeader
        - `fileId` integer
        - `text` string
        - `type` 'MESSAGE_HEADER', required
      - PublicQuickReplies
        - `allowMultiSelect` boolean, required
        - `allowUserInput` boolean, required
        - `quickReplies` QuickReply[], required
          - `label` string
          - `value` string, required
          - `valueType` 'TEXT' | 'URL', required
        - `type` 'QUICK_REPLIES', required
      - PublicWhatsAppTemplateMetadata
        - `contentId` integer
        - `crmObjectIds` object, required
        - `mappedTemplateId` integer
        - `parameters` object, required
        - `rootMicId` integer
        - `type` 'WHATSAPP_TEMPLATE_METADATA', required
      - PublicSocialMetadataAttachment
        - `socialMetadata` SocialMetadata, required
          - `description` string
          - `id` string
          - `mediaTitle` string
          - `mediaType` 'ARTICLE' | 'AUDIO' | 'CAROUSEL' | 'DOCUMENT' | 'GIF' | 'LINK' | 'NONE' | 'PHOTO' | 'POLL' | 'STORY' | 'VIDEO', required
          - `mediaUrl` string
          - `mediaUrlString` string
          - `thumbnailUrl` string
        - `type` 'SOCIAL_MEDIA_METADATA', required
  - `channelAccountId` string, required
  - `channelId` string, required
  - `client` PublicClient, required
    - `clientType` 'HUBSPOT' | 'INTEGRATION' | 'SYSTEM' | 'UNKNOWN', required
    - `integrationAppId` integer
  - `conversationsThreadId` string, required
  - `createdAt` string, date-time, required
  - `createdBy` string, required
  - `direction` 'INCOMING' | 'OUTGOING', required
  - `id` string, required
  - `inReplyToId` string
  - `recipients` PublicRecipient[], required
    - `actorId` string
    - `deliveryIdentifier` PublicDeliveryIdentifier, required
      - `type` 'CHANNEL_SPECIFIC_OPAQUE_ID' | 'HS_EMAIL_ADDRESS' | 'HS_PHONE_NUMBER' | 'HS_SHORT_CODE', required
      - `value` string, required
    - `name` string
    - `recipientField` string
  - `richText` string
  - `senders` PublicSender[], required
    - `actorId` string
    - `deliveryIdentifier` PublicDeliveryIdentifier
      - `type` 'CHANNEL_SPECIFIC_OPAQUE_ID' | 'HS_EMAIL_ADDRESS' | 'HS_PHONE_NUMBER' | 'HS_SHORT_CODE', required
      - `value` string, required
    - `name` string
    - `senderField` string
  - `status` PublicMessageStatus
    - `failureDetails` PublicMessageFailureDetails
      - `errorMessage` string
      - `errorMessageTokens` object, required
    - `statusType` 'FAILED' | 'READ' | 'RECEIVED' | 'SENT', required
  - `subject` string
  - `text` string, required
  - `truncationStatus` 'NOT_TRUNCATED' | 'TRUNCATED' | 'TRUNCATED_TO_MOST_RECENT_REPLY', required
  - `type` 'MESSAGE', required
  - `updatedAt` string, date-time

## Other responses

- `default`: An error occurred.

## Changes

- **2026-11-11** (v3) `79a7df92c8e1`: 1 info
  - added the new `hs_geocode_mapping_id` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
- **2026-10-30** (v3) `9d45a9210654`: 4 info
  - added the new `hs_sms_mobilephone_communication_subscriptions_opted_in` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
  - added the new `hs_sms_mobilephone_communication_subscriptions_opted_out` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
  - added the new `hs_sms_phone_communication_subscriptions_opted_in` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
  - added the new `hs_sms_phone_communication_subscriptions_opted_out` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
- **2026-10-29** (v3) `3c5f8e4b0cc4`: 1 info
  - added the new `hs_cross_account_data_mirroring_source_account_ids` enum value to the request property `preResolvedContacts/contacts/items/contactPropertiesLeadingToMatch/items/`
- …earlier changes not shown

[Operation history](https://skmtc.dev/hubspot/apis/conversations-custom-channels/changes/conversations/v3/custom-channels/:channelId/messages/post.md)

---

[API](https://skmtc.dev/hubspot/apis/conversations-custom-channels.md) - [All operations](https://skmtc.dev/hubspot/apis/conversations-custom-channels/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/conversations-custom-channels/revisions/b6d4942824fa?raw)
