ANNOUNCEMENT: Changes to Actors and Delivery Identifiers in the Conversations API

[jmclaren]

Note the text below is a reposting of the announcement on the HubSpot Developer Changelog.

---

The Conversations API (currently in beta) is used to read and send HubSpot conversations inbox messages. We're making 2 changes to the message recipient portion of the API response, and one of the changes may require you to make changes if your integration leverages this API.

Currently this is what an email message recipient would look like:

"recipients": [{
    "actorId": "E-user@hubspot.com",
    "name": "Leslie Knope",
    "recipientField": "TO",
    "deliveryIdentifiers": [{
        "type": "HS_EMAIL_ADDRESS",
        "value": "lknope@hubspot.com"
    }]
}]

1. actorId is becoming an optional field, and we're removing the Email Actor Type, which is prefixed with "E-". ActorIds represent the entity within the HubSpot account that performed an action or is assigned to an object. An email address does not fit that definition of an Actor so we have decided to remove the "E-[actorId]". Going forward, messages will simply have no actorId, instead of an email ActorId. It still might be possible for message recipients on email messages to have other actorIds (For example "V-123456"  if the recipient is a known contact in the CRM); However, if there isn't a known actorId, the field will just be empty. If your integration needs the email address, it will continue to be provided in the deliveryIdentifiers.
2. The deliveryIdentifiers field is being changed to a single, optional field called deliveryIdentifier (without the end 's'). This does not affect the ability to have multiple recipients, it merely changes the field based on how it's actually used. Each recipient has at most 1 delivery identifier, so no information will be lost, but the structure of the data for the field will be changing from an array of objects to just an object.
   
   After these changes, the recipients data will look like this (note the exclusion of the now optional actorId field):
   

   "recipients": [{
       "name": "Leslie Knope",
       "recipientField": "TO",
       "deliveryIdentifier": {
           "type": "HS_EMAIL_ADDRESS",
           "value": "lknope@hubspot.com"
       }
   }]​

When is this happening?

We have already begun including the new deliveryIndentifier field in-addition to the old deliveryIdentifiers field. If you have an app using this API you should migrate from the deliveryIdentifiers field to the deliveryIdentifier field.

On April 10th, 2023, the deliveryIdentifiers field will stop being returned in the API. So if you're using the data in that field, you'll want to migrate to the deliveryIdentifier field before then.