HubSpot · Schema

Message

Represents a message within a conversation thread.

AnalyticsCommerceContentCRMCustomer ServiceEmail MarketingMarketingMarketing AutomationOperationsSales

Properties

Name	Type	Description
id	string	Unique identifier for the message
type	string	Type of message
text	string	Plain text content of the message
richText	string	Rich text (HTML) content of the message
direction	string	Direction of the message (incoming or outgoing)
channelId	string	ID of the communication channel
channelAccountId	string	ID of the channel account
senders	array	List of message senders
recipients	array	List of message recipients
status	object	Delivery status information for a message
createdAt	string	ISO 8601 timestamp when the message was created
truncationStatus	string	Whether the message was truncated
attachments	array	Message attachments

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/json-schema/conversations-api-message-schema.json",
  "title": "Message",
  "description": "Represents a message within a conversation thread.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the message",
      "example": "msg_123456"
    },
    "type": {
      "type": "string",
      "enum": [
        "MESSAGE",
        "COMMENT",
        "WELCOME_MESSAGE"
      ],
      "description": "Type of message",
      "example": "MESSAGE"
    },
    "text": {
      "type": "string",
      "description": "Plain text content of the message",
      "example": "Hello, I need help with my order."
    },
    "richText": {
      "type": "string",
      "description": "Rich text (HTML) content of the message",
      "example": "<p>Hello, I need help with my order.</p>"
    },
    "direction": {
      "type": "string",
      "enum": [
        "INCOMING",
        "OUTGOING"
      ],
      "description": "Direction of the message (incoming or outgoing)",
      "example": "INCOMING"
    },
    "channelId": {
      "type": "string",
      "description": "ID of the communication channel",
      "example": "channel_789"
    },
    "channelAccountId": {
      "type": "string",
      "description": "ID of the channel account",
      "example": "account_123"
    },
    "senders": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Represents a participant in a conversation (visitor, agent, or bot).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the actor",
            "example": "actor_101"
          },
          "actorId": {
            "type": "string",
            "description": "Actor ID reference",
            "example": "actor_101"
          },
          "name": {
            "type": "string",
            "description": "Display name of the actor",
            "example": "John Customer"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the actor",
            "example": "[email protected]"
          },
          "type": {
            "type": "string",
            "description": "Type of actor (e.g., VISITOR, AGENT, BOT)",
            "example": "VISITOR"
          }
        },
        "required": [
          "id"
        ]
      },
      "description": "List of message senders",
      "example": [
        {
          "id": "actor_101",
          "actorId": "actor_101",
          "name": "John Customer",
          "email": "[email protected]",
          "type": "VISITOR"
        }
      ]
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Represents a participant in a conversation (visitor, agent, or bot).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the actor",
            "example": "actor_101"
          },
          "actorId": {
            "type": "string",
            "description": "Actor ID reference",
            "example": "actor_101"
          },
          "name": {
            "type": "string",
            "description": "Display name of the actor",
            "example": "John Customer"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of the actor",
            "example": "[email protected]"
          },
          "type": {
            "type": "string",
            "description": "Type of actor (e.g., VISITOR, AGENT, BOT)",
            "example": "VISITOR"
          }
        },
        "required": [
          "id"
        ]
      },
      "description": "List of message recipients",
      "example": [
        {
          "id": "actor_101",
          "actorId": "actor_101",
          "name": "John Customer",
          "email": "[email protected]",
          "type": "VISITOR"
        }
      ]
    },
    "status": {
      "type": "object",
      "description": "Delivery status information for a message",
      "properties": {
        "statusType": {
          "type": "string",
          "enum": [
            "SENT",
            "DELIVERED",
            "READ",
            "FAILED"
          ],
          "description": "Current delivery status type",
          "example": "DELIVERED"
        }
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the message was created",
      "example": "2024-01-20T10:30:00Z"
    },
    "truncationStatus": {
      "type": "string",
      "description": "Whether the message was truncated",
      "example": "NOT_TRUNCATED"
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Represents a file attachment on a message.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the attachment",
            "example": "attach_001"
          },
          "type": {
            "type": "string",
            "description": "MIME type of the attachment",
            "example": "application/pdf"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL to access the attachment",
            "example": "https://api.hubapi.com/files/v3/files/attach_001"
          },
          "filename": {
            "type": "string",
            "description": "Original filename",
            "example": "invoice.pdf"
          },
          "size": {
            "type": "integer",
            "description": "File size in bytes",
            "example": 102400
          }
        }
      },
      "description": "Message attachments",
      "example": [
        {
          "id": "attach_001",
          "type": "application/pdf",
          "url": "https://api.hubapi.com/files/v3/files/attach_001",
          "filename": "invoice.pdf",
          "size": 102400
        }
      ]
    }
  },
  "required": [
    "id",
    "type",
    "createdAt"
  ]
}