Actions

The ballerinax/hubspot.crm.engagements.communications package exposes the following clients:

Client	Purpose
`Client`	Manage HubSpot communication records: CRUD, batch operations, and search.

Client

Manage HubSpot communication records: CRUD, batch operations, and search.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig\|OAuth2RefreshTokenGrantConfig\|ApiKeysConfig`	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or API keys.
`httpVersion`	`HttpVersion`	`HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`30`	Request timeout in seconds.
`retryConfig`	`RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`ProxyConfig`	`()`	Proxy server configuration.

Initializing the client

import ballerinax/hubspot.crm.engagements.communications;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

communications:Client communicationsClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        refreshUrl: "https://api.hubapi.com/oauth/v1/token"
    }
});

Operations

Single record operations

Create a communication

Signature: post /

Creates a new communication record with the specified properties and optional associations.

Parameters:

Name	Type	Required	Description
`payload`	`SimplePublicObjectInputForCreate`	Yes	The communication properties and associations.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: SimplePublicObject|error

Sample code:

communications:SimplePublicObject response = check communicationsClient->/.post({
    properties: {
        "hs_communication_channel_type": "WHATS_APP",
        "hs_communication_logged_from": "CRM",
        "hs_communication_body": "Hello! This is a WhatsApp message."
    },
    associations: [
        {
            types: [
                {
                    associationCategory: "HUBSPOT_DEFINED",
                    associationTypeId: 81
                }
            ],
            to: {
                id: "12345"
            }
        }
    ]
});

Sample response:

{
  "id": "67890",
  "properties": {
    "hs_communication_channel_type": "WHATS_APP",
    "hs_communication_logged_from": "CRM",
    "hs_communication_body": "Hello! This is a WhatsApp message.",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
    "hs_object_id": "67890"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Retrieve messages

Signature: get /

Retrieves a paginated list of communication records with optional property and association filtering.

Parameters:

Name	Type	Required	Description
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetCrmV3ObjectsCommunicationsGetPageQueries`	No	Query parameters including `limit`, `after`, `properties`, `associations`, `archived`, and `propertiesWithHistory`.

Returns: CollectionResponseSimplePublicObjectWithAssociationsForwardPaging|error

Sample code:

communications:CollectionResponseSimplePublicObjectWithAssociationsForwardPaging response =
    check communicationsClient->/.get(
        queries = {
            'limit: 10,
            properties: ["hs_communication_channel_type", "hs_communication_body"]
        }
    );

Sample response:

{
  "results": [
    {
      "id": "67890",
      "properties": {
        "hs_communication_channel_type": "WHATS_APP",
        "hs_communication_body": "Hello! This is a WhatsApp message.",
        "hs_createdate": "2025-01-15T10:30:00.000Z",
        "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
        "hs_object_id": "67890"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "67890",
      "link": "https://api.hubapi.com/crm/v3/objects/communications?after=67890"
    }
  }
}

Retrieve a message

Signature: get /[string communicationId]

Retrieves a single communication record by its ID, with optional properties and associations.

Parameters:

Name	Type	Required	Description
`communicationId`	`string`	Yes	The ID of the communication record to retrieve.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetCrmV3ObjectsCommunicationsCommunicationIdGetByIdQueries`	No	Query parameters including `properties`, `associations`, `archived`, `propertiesWithHistory`, and `idProperty`.

Returns: SimplePublicObjectWithAssociations|error

Sample code:

communications:SimplePublicObjectWithAssociations response =
    check communicationsClient->/["67890"].get(
        queries = {
            properties: ["hs_communication_channel_type", "hs_communication_body"]
        }
    );

Sample response:

{
  "id": "67890",
  "properties": {
    "hs_communication_channel_type": "WHATS_APP",
    "hs_communication_body": "Hello! This is a WhatsApp message.",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
    "hs_object_id": "67890"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Update a message

Signature: patch /[string communicationId]

Updates an existing communication record with new property values.

Parameters:

Name	Type	Required	Description
`communicationId`	`string`	Yes	The ID of the communication record to update.
`payload`	`SimplePublicObjectInput`	Yes	The properties to update.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PatchCrmV3ObjectsCommunicationsCommunicationIdUpdateQueries`	No	Query parameters including `idProperty`.

Returns: SimplePublicObject|error

Sample code:

communications:SimplePublicObject response = check communicationsClient->/["67890"].patch({
    properties: {
        "hs_communication_body": "Updated message body content."
    }
});

Sample response:

{
  "id": "67890",
  "properties": {
    "hs_communication_channel_type": "WHATS_APP",
    "hs_communication_body": "Updated message body content.",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T11:00:00.000Z",
    "hs_object_id": "67890"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T11:00:00.000Z",
  "archived": false
}

Archive a message

Signature: delete /[string communicationId]

Archives (soft-deletes) a communication record by its ID.

Parameters:

Name	Type	Required	Description
`communicationId`	`string`	Yes	The ID of the communication record to archive.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: error?

Sample code:

check communicationsClient->/["67890"].delete();

Batch operations

Create a batch of messages

Signature: post /batch/create

Creates multiple communication records in a single batch request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputSimplePublicObjectInputForCreate`	Yes	Batch input containing an array of communication records to create.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

communications:BatchResponseSimplePublicObject|communications:BatchResponseSimplePublicObjectWithErrors response =
    check communicationsClient->/batch/create.post({
        inputs: [
            {
                properties: {
                    "hs_communication_channel_type": "LINKEDIN_MESSAGE",
                    "hs_communication_logged_from": "CRM",
                    "hs_communication_body": "First LinkedIn message"
                },
                associations: [
                    {
                        types: [{associationCategory: "HUBSPOT_DEFINED", associationTypeId: 81}],
                        to: {id: "12345"}
                    }
                ]
            },
            {
                properties: {
                    "hs_communication_channel_type": "LINKEDIN_MESSAGE",
                    "hs_communication_logged_from": "CRM",
                    "hs_communication_body": "Second LinkedIn message"
                },
                associations: [
                    {
                        types: [{associationCategory: "HUBSPOT_DEFINED", associationTypeId: 81}],
                        to: {id: "12346"}
                    }
                ]
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "67891",
      "properties": {
        "hs_communication_channel_type": "LINKEDIN_MESSAGE",
        "hs_communication_body": "First LinkedIn message",
        "hs_object_id": "67891"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    },
    {
      "id": "67892",
      "properties": {
        "hs_communication_channel_type": "LINKEDIN_MESSAGE",
        "hs_communication_body": "Second LinkedIn message",
        "hs_object_id": "67892"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:30:00.000Z",
  "completedAt": "2025-01-15T10:30:01.000Z"
}

Retrieve a batch of messages

Signature: post /batch/read

Retrieves multiple communication records by their IDs in a single batch request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchReadInputSimplePublicObjectId`	Yes	Batch input containing record IDs, requested properties, and properties with history.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PostCrmV3ObjectsCommunicationsBatchReadReadQueries`	No	Query parameters including `archived`.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

communications:BatchResponseSimplePublicObject|communications:BatchResponseSimplePublicObjectWithErrors response =
    check communicationsClient->/batch/read.post({
        properties: ["hs_communication_channel_type", "hs_communication_body"],
        propertiesWithHistory: ["hs_communication_body"],
        inputs: [
            {id: "67891"},
            {id: "67892"}
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "67891",
      "properties": {
        "hs_communication_channel_type": "LINKEDIN_MESSAGE",
        "hs_communication_body": "First LinkedIn message",
        "hs_object_id": "67891"
      },
      "propertiesWithHistory": {
        "hs_communication_body": [
          {
            "value": "First LinkedIn message",
            "timestamp": "2025-01-15T10:30:00.000Z",
            "sourceType": "CRM_UI",
            "sourceId": "userId:12345"
          }
        ]
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T10:30:00.000Z",
  "completedAt": "2025-01-15T10:30:01.000Z"
}

Update a batch of messages

Signature: post /batch/update

Updates multiple communication records in a single batch request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputSimplePublicObjectBatchInput`	Yes	Batch input containing record IDs and properties to update.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

communications:BatchResponseSimplePublicObject|communications:BatchResponseSimplePublicObjectWithErrors response =
    check communicationsClient->/batch/update.post({
        inputs: [
            {
                id: "67891",
                properties: {
                    "hs_communication_body": "Updated first message"
                }
            },
            {
                id: "67892",
                properties: {
                    "hs_communication_body": "Updated second message"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "67891",
      "properties": {
        "hs_communication_channel_type": "LINKEDIN_MESSAGE",
        "hs_communication_body": "Updated first message",
        "hs_object_id": "67891"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    },
    {
      "id": "67892",
      "properties": {
        "hs_communication_channel_type": "LINKEDIN_MESSAGE",
        "hs_communication_body": "Updated second message",
        "hs_object_id": "67892"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T11:00:00.000Z",
  "completedAt": "2025-01-15T11:00:01.000Z"
}

Create and update a batch of messages

Signature: post /batch/upsert

Creates or updates multiple communication records in a single batch request based on a unique ID property.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputSimplePublicObjectBatchInputUpsert`	Yes	Batch input containing records to upsert with their ID property and properties.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: BatchResponseSimplePublicUpsertObject|BatchResponseSimplePublicUpsertObjectWithErrors|error

Sample code:

communications:BatchResponseSimplePublicUpsertObject|communications:BatchResponseSimplePublicUpsertObjectWithErrors response =
    check communicationsClient->/batch/upsert.post({
        inputs: [
            {
                id: "67891",
                idProperty: "hs_object_id",
                properties: {
                    "hs_communication_body": "Upserted message content"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "67891",
      "properties": {
        "hs_communication_body": "Upserted message content",
        "hs_object_id": "67891"
      },
      "new": false,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T11:30:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-15T11:30:00.000Z",
  "completedAt": "2025-01-15T11:30:01.000Z"
}

Archive a batch of messages

Signature: post /batch/archive

Archives (soft-deletes) multiple communication records in a single batch request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputSimplePublicObjectId`	Yes	Batch input containing an array of record IDs to archive.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: error?

Sample code:

check communicationsClient->/batch/archive.post({
    inputs: [
        {id: "67891"},
        {id: "67892"}
    ]
});

Search

Search for messages

Signature: post /search

Searches for communication records using filters, query text, and sorting options.

Parameters:

Name	Type	Required	Description
`payload`	`PublicObjectSearchRequest`	Yes	Search request with filters, query, sorting, properties, and pagination.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: CollectionResponseWithTotalSimplePublicObjectForwardPaging|error

Sample code:

communications:CollectionResponseWithTotalSimplePublicObjectForwardPaging response =
    check communicationsClient->/search.post({
        filterGroups: [
            {
                filters: [
                    {
                        propertyName: "hs_communication_channel_type",
                        operator: "EQ",
                        value: "WHATS_APP"
                    }
                ]
            }
        ],
        properties: ["hs_communication_channel_type", "hs_communication_body"],
        'limit: 10
    });

Sample response:

{
  "total": 1,
  "results": [
    {
      "id": "67890",
      "properties": {
        "hs_communication_channel_type": "WHATS_APP",
        "hs_communication_body": "Hello! This is a WhatsApp message.",
        "hs_createdate": "2025-01-15T10:30:00.000Z",
        "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z",
        "hs_object_id": "67890"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "paging": {}
}

Client​

Configuration​

Initializing the client​

Operations​

Single record operations​

Batch operations​

Search​

Client

Configuration

Initializing the client

Operations

Single record operations

Batch operations

Search