Third-party transcripts

If you use a third-party solution for transcribing calls, you can sync those transcriptions to HubSpot using the transcription API. This may be a good alternative to using HubSpot to transcribe third-party calls.

Requirements

Calls to the transcription API must be authenticated with OAuth, and your public app must include the following scopes:

crm.extensions_calling_transcripts.read
crm.extensions_calling_transcripts.write

Transcript data is made available to HubSpot by attaching the transcript to a call engagement, so you may need to use the call engagement API to create and retrieve call engagements while working with the transcripts API.

Create a transcript

To create a transcript, make a POST request to /crm/v3/extensions/calling/transcripts. The request body will need to include the ID of the call engagement in HubSpot to attach the transcript to, along with a transcriptCreateUtterances array containing the transcript data.

{
  "engagementId": 21,
  "transcriptCreateUtterances": [
    {
      "speaker": {
        "id": "11",
        "name": "Speaker_NAME1"
      },
      "text": "Hello. How are you?",
      "languageCode": "en-US",
      "startTimeMillis": 1980,
      "endTimeMillis": 2090
    },
    {
      "speaker": {
        "id": "12",
        "name": "Speaker_NAME2",
        "email": "speakerName2@gmail.com"
      },
      "text": "Good, and you?",
      "startTimeMillis": 2090,
      "endTimeMillis": 3450
    }
  ]
}

Transcript details

The table below lists the top-level transcript fields. Fields marked with * are required.

Field	Type	Description
`engagementId`*	String	The ID of the HubSpot call engagement to attach the transcript to.
`transcriptCreateUtterances`*	Array	A list of objects containing the transcribed call dialogue. The available fields are listed in the table below.

Transcript utterances

The table below outlines all available fields you can provide for the transcriptCreateUtterances array. Fields marked with * are required.

Field	Type	Description
`speaker`*	Object	Contains the following information about the speaker: `id`: the speaker’s ID (max 100 characters). `name`: the speaker’s name (max 100 characters). `email`: optionally, the speaker’s email, which will be matched to a contact record in the account. Must be a valid email.
`text`*	String	The transcribed text.
`languageCode`	String	The speaker’s language. Default is `en-US`.
`startTimeMillis`*	Integer	The starting time of the utterance, in milliseconds from the start of the call. Should be a positive number.
`endTimeMillis`*	Integer	The end time of the utterance, in milliseconds from the start of the call. Should be greater than `startTimeMillis`.

A successful response will return the id of the transcript, as generated by HubSpot.

{
  "id": 5
}

Retrieve a transcript

To retrieve a transcript from HubSpot, make a GET request to /crm/v3/extensions/calling/transcripts/{transcriptId}. The response will include the transcript details along with the ID of the associated call engagement.

{
  "id": 5,
  "engagementId": 21,
  "transcriptSource": "INTEGRATOR_GENERATED",
  "createdAt": "2024-12-05T16:50:00.000Z",
  "transcriptUtterances": [
    {
      "speaker": {
        "id": 11,
        "name": "Speaker_NAME1"
      },
      "text": "Hello. How are you?",
      "languageCode": "en-US",
      "startTimeMillis": 1980,
      "endTimeMillis": 2090
    },
    {
      "speaker": {
        "id": 12,
        "name": "Speaker_NAME2",
        "email": "speakerName2@gmail.com"
      },
      "text": "Good, and you?",
      "startTimeMillis": 2090,
      "endTimeMillis": 3450
    }
  ]
}

Field	Type	Description
`id`	Integer	The ID of the transcript.
`engagementId`	String	The ID of the HubSpot call engagement attached to the transcript.
`transcriptSource`	String	The source of the transcript (will be set to `INTEGRATOR_GENERATED`).
`createdAt`	String	The datetime of when the transcript was created in HubSpot.
`transcriptUtterances`	Array	A list of objects containing the transcribed call dialogue.
`speaker`	Object	Contains information about the speaker, including their `id`, `name`, and an email address if previously provided.
`text`	String	The transcribed text.
`languageCode`	String	The speaker’s language. Default is `en-US`.
`startTimeMillis`	Integer	The starting time of the utterance, in milliseconds from the start of the call.
`endTimeMillis`	Integer	The end time of the utterance, in milliseconds from the start of the call.

Delete a transcript

To delete a transcript from HubSpot, make a DELETE request to /crm/v3/extensions/calling/transcripts/{transcriptId}.

​Requirements

​Create a transcript

​Transcript details

​Transcript utterances

​Retrieve a transcript