Recordings and transcripts (BETA)

If you want to make call recordings playable in your HubSpot account, or you want to build on top of HubSpot's Conversation Intelligence functionality, you can use the engagements API to automatically transcribe calls and log them within HubSpot. 

• HubSpot will only transcribe calls associated with users with a paid Sales or Services hub seat.
• Only .WAV, .FLAC, and .MP4 audio files will be transcribed.
• In the transcription system, HubSpot splits the audio file into its different channels and treats each channel as a separate speaker. If all of the speakers are on the same audio channel, or if the caller or recipient are on an unexpected channel, HubSpot will not be able to transcribe the audio recording. Therefore, each speaker in an audio file should be on a separate channel. For calls with two channels, the caller should be on channel 1, and the call recipient should be on channel 2, regardless of whether the call is inbound or outbound. 

To list and transcribe calls on a record's timeline in HubSpot, create an endpoint that will be invoked to retrieve the authenticated call URLs associated with each engagement.

Your endpoint should accept the following parameters:

• externalId: the unique ID associated with a call URL, provided as a path parameter. This will correspond to the same parameter you include in the metadata of your POST request to the engagements API, which you can then use in your app's backend to associate with the recording URL.
• externalAccountId: a unique ID associated with the HubSpot account that made the call engagement, provided as a query parameter. You can use this parameter along with the externalId to identify the call recording.
• appId: the ID of your app, provided as a query parameter.

Your endpoint should return a JSON response with a authenticatedUrl field that provides the recording URL.

Once your endpoint is ready, make a POST request using your app's ID to /crm/v3/extensions/calling/{appId}/settings/recording and provide the URL of your endpoint with the urlToRetrieveAuthedRecording parameter in the body of your request.

• Your endpoint's URL must contain the %s character sequence, which HubSpot will substitute with the externalId of the engagement when calling your endpoint. The %s character sequence can be located anywhere in your URL.
• Provide the full path of your endpoint URL in your POST request, including the https:// prefix.

For example:

If you change the location of your endpoint, you can make a PATCH request to the same HubSpot endpoint above and provide an updated value for urlToRetrieveAuthedRecording.

After you've registered your calling app's endpoint with HubSpot, you can log a call by making a POST request to the /crm/v3/objects/calls endpoint, and including the engagement data within the properties field in the body of your request.

 The hs_call_external_id, hs_call_external_account_id, hs_call_app_id, and hs_call_source properties are required to ensure that HubSpot can fetch the authenticated recording URL.

The body of an example request is shown below:

Next, you'll need to associate the call with a record type to ensure the transcript appears on the record timeline.

• To make this association, make a PUT request to /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationType}.
• For example, if the ID of the logged call you created above is 17591596434, the ID of the contact you wanted to associate it with is 104901, and the ID of the associationType is 194, your request URL would be:

https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contacts/104901/194

When one of your app's users navigates to the associated record timeline to view the engagement, HubSpot will call the endpoint you configured to serve the authenticated recording URL. For example, to retrieve the recording URL associated with the example engagement above, HubSpot would make a GET request to:

https://app-test.com/retrieve/authenticated/recordings/test-call-01?appId=app-101&externalAccountId=test-account-01

If you're unable to create and host an endpoint to provide HubSpot with authenticated recording URLs, you can also directly log a call using the v3 engagements API by including a hs_call_recording_url in the properties field, but omitting the hs_external_id, hs_external_account_id, and hs_call_source parameters. The recording URL will appear on the contact record timeline but the recording will be publicly accessible to anyone with the URL.