Communications

You can log external communications via WhatsApp, LinkedIn, or SMS messages on CRM records to add information about the message to the record timeline. 

You can log a message directly in your HubSpot account or using the API endpoints below. You can review all available endpoints on the Endpoints tab at the top of this article.

To create a message, make a POST request to /crm/v3/objects/communications.

In the request body, add message details in a properties object. You can also add an associations object to associate your new message with an existing record (e.g., contacts, companies).

In the properties object, you can include the following fields:

To create and associate a postal mail engagement with existing records, include an associations object in your request. The object should include the following fields:

For example, if you want to log an SMS message and associate it with a contact and company, your request body might resemble the following:

The response to your request will include an ID that you can use to update or associate the message with a record:

You can retrieve messages individually or in batches. To retrieve an individual messages, make a GET request to /crm/v3/objects/communication/{communicationId}.

To request a list of all of logged WhatsApp, LinkedIn, and SMS messages, make a GET request to /crm/v3/objects/communications.

For both endpoints, you can include the following query parameters in the request URL:

For example, to retrieve messages with their text content and any associated contact IDs, your request URL might look similar to the following:

https://api.hubapi.com/crm/v3/objects/communications?limit=10&properties=hs_communication_body&associations=contact&archived=false.

Learn more about retrieving a batch of messages by internal ID or unique property value on the Endpoints tab at the top of this article.

You can update messages individually or in batches. To update an individual message by its communication ID, make a PATCH request to /crm/v3/objects/communications/{communicationId}. 

In the request body, include the message properties that you want to update:

HubSpot will ignore values for read-only and non-existent properties. To clear a property value, pass an empty string for the property in the request body.

Learn more about batch updating messages on the Endpoints tab at the top of this article.

To associate a message with other CRM records, such as a contact, make a PUT request to /crm/v3/objects/communications/{communicationId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. The request URL contains the following fields:

For example, your request URL might look similar to the following:

https://api.hubapi.com/crm/v3/objects/communications/12021896773/associations/contact/581751/communication_to_contact

Remove an association

To remove an association between a message and a record, make a DELETE request to the same URL as above:

/crm/v3/objects/communications/{communicationId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

You can pin a message on a record so it remains on the top of the record's timeline. The message must already be associated with the record prior to pinning, and you an only pin one activity per record. To pin a message, include the message's id in the hs_pinned_engagement_id field when creating or updating a record via the object APIs. Learn more about using the companies,contacts, deals, tickets, and custom objects APIs.

You can delete messages individually or in batches, which will add the message to the recycling bin in HubSpot. You can later restore the message from the record timeline.

To delete an individual message by its ID, make a DELETE request to /crm/v3/objects/communications/{communicationId}.

Learn more about batch deleting messages on the Endpoints tab at the top of this article.