Speech-to-text overview | Symbl.ai Docs

Symbl.ai delivers accurate and customizable speech-to-text transcription. You can convert audio and video conversations into text in real-time or after the conversation has ended.

Symbl.ai speech-to-text features include:

Domain specific speech-to-text transcription models for mobile calls and video calls for state-of-the-art accuracy.
Accurate paragraphs and sentences with punctuation such as commas, periods, and question marks.
Support for multiple file formats like markdown .md and SubRip Text .srt.

Customizable Speech-to-Text features:

A custom vocabulary helps speech-to-text recognize specific words or phrases that are more frequently used within a context. If your conversations often include the word sell. When Speech-to-Text encounters the word sell, you want it to transcribe the word as sell more often than cell. In this case, you can use speech adaptation to bias Speech-to-Text to recognize sell. Enable the customVocabulary request parameter as described in the Streaming API.
Speaker Diarization connects individual speakers with their statements. Using standard speech-to-text transcription results in very accurate diarization, but not 100%. To achieve nearly 100% accuracy, generate speech-to-text transcripts using audio streams and pass the audio files with one speaker per channel. For more information, see Apply Speaker Separation to Async Files.
You can identify action phrases within a transcript to generate a list of action items from a conversation. For details, see the Conversations API Retrieve Action Items by conversation ID request or Symbl.ai React Elements.

Authentication

This request requires an access token, as described in Authenticate.

Get speech-to-text transcripts

This section describes how to get speech-to-text transcripts from a conversation. This request requires a conversation ID. You receive a conversation ID when you process a conversation.

To get a transcript of your conversation, use the GET <https://api.symbl.ai/v1/conversations/><CONVERSATION_ID>/messages operation:

👍
Try our interactive examples!
We provide interactive versions of these code samples: curl, Node.js, Python
To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
CONVERSATION_ID="<CONVERSATION_ID>"

curl --request GET \
  --url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID/messages" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

import fetch from 'node-fetch';

const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';

const fetchResponse = await fetch(`https://api.symbl.ai/v1/conversations/${conversationId}/messages?sentiment=true`, {
  method: 'get',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});

const responseBody = await fetchResponse.json();

console.log(JSON.stringify(responseBody, null, 2));

import json
import requests

access_token = "<ACCESS_TOKEN>"
conversation_id = "<CONVERSATION_ID>"

headers = {
  "Authorization": "Bearer " + access_token,
  "Content-Type": "application/json"
}

response = requests.request(
  method="GET", 
  url="https://api.symbl.ai/v1/conversations/" + conversation_id + "/messages?sentiment=true",
  headers=headers
)

print(json.dumps(response.json(), indent=2))

Where:

<ACCESS_TOKEN> is a valid API access token.
<CONVERSATION_ID> is the ID of a conversation that you previously processed.

For additional reference information, see Retrieve Messages from Conversations.

Optional query parameters

This request supports the following optional query parameters.

Parameter	Type	Description
`exclude`	Array	An array of one or more strings that correspond to the subtype of managed or custom entities that you want to exclude from redaction. Entities must be written in all capital letters, such as `["PERSON_NAME"]`. If not included and if redaction is enabled, no entities are excluded by default.
`redact`	Boolean	Enables the Redaction feature. When `true`, detected entities are redacted in messages. If not included, the default value is `false`.
`sentiment`	String	Enables Sentiment Analysis for each sentence. If not included, the default value is `false`.
`verbose`	String	Enables timestamps and sentiment analysis for each word in a sentence. If not included, the default value is `false`.

Response

The following table describes the response body that is returned by this request. The request returns messages, an array of objects that contain text and data for each sentence in the conversation. The fields in the table appear in the individual message objects.

Field	Description
`id`	The unique ID of the message in the conversation.
`text`	The content of the message. Each message corresponds to one sentence from the conversation. If redaction is enabled and entities are detected in the text, those entities are redacted.
`from`	Contains identifying information about the speaker of the sentence, if available. If redaction is enabled, the `name` and `email` values in the `from` object are redacted.
`from.id`	The unique ID of the speaker.
`from.name`	The name of the speaker.
`from.email`	The email address of the speaker.
`startTime`	The start time of the message.
`endTime`	The end time of the message.
`conversationId`	The conversation ID of the conversation that the message was extracted from.
`phrases`	An array of strings that contain actionable phrases that are detected in the conversation. This field is only populated if the `detectPhrases` query parameter was set to `true` when you processed your conversation and if actionable phrases were detected.
`sentiment`	Contains sentiment polarity for the message. This field is only populated if the optional `sentiment` query parameter is set to `true`. For more information about sentiment polarity, see Sentiment analysis.
`sentiment.polarity`	Contains the sentiment polarity score for the message.
`sentiment.polarity.score`	A number from `-1` to `1` that represents the sentiment of the message.
`sentiment.suggested`	The suggested sentiment of the message. Possible values are `positive`, `neutral`, and `negative`.

Example response

{
  "messages": [
    {
      "id": "4808748496322560",
      "text": "This is your local internet service provider.",
      "from": {},
      "startTime": "2022-07-28T00:29:55.672Z",
      "endTime": "2022-07-28T00:29:57.772Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.134
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "5939064753618944",
      "text": "How may I help you today?",
      "from": {},
      "startTime": "2022-07-28T00:29:57.872Z",
      "endTime": "2022-07-28T00:29:58.972Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": -0.047
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "6418613790572544",
      "text": "I installed your internet service for my new home and its really slow.",
      "from": {},
      "startTime": "2022-07-28T00:29:59.972Z",
      "endTime": "2022-07-28T00:30:02.672Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": -0.979
        },
        "suggested": "negative"
      }
    },
    {
      "id": "6633702162432000",
      "text": "I can send it internet service technician to your home whenever you're free.",
      "from": {},
      "startTime": "2022-07-28T00:30:03.872Z",
      "endTime": "2022-07-28T00:30:07.172Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.086
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "4593008581279744",
      "text": "Could you let me know what time works for you?",
      "from": {},
      "startTime": "2022-07-28T00:30:07.372Z",
      "endTime": "2022-07-28T00:30:09.272Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.242
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "6226587111391232",
      "text": "I will finish my work by 5 PM so you could send a technician after that, okay?",
      "from": {},
      "startTime": "2022-07-28T00:30:10.172Z",
      "endTime": "2022-07-28T00:30:15.572Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.157
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "6376853488009216",
      "text": "I just need to follow up with the technician first.",
      "from": {},
      "startTime": "2022-07-28T00:30:15.772Z",
      "endTime": "2022-07-28T00:30:17.972Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.091
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "4550301271982080",
      "text": "I will call you back in an hour to confirm your appointment.",
      "from": {},
      "startTime": "2022-07-28T00:30:18.172Z",
      "endTime": "2022-07-28T00:30:20.772Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.239
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "5439006408966144",
      "text": "Okay.",
      "from": {},
      "startTime": "2022-07-28T00:30:21.572Z",
      "endTime": "2022-07-28T00:30:22.072Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": -0.3
        },
        "suggested": "neutral"
      }
    },
    {
      "id": "5588718130823168",
      "text": "Thank you for calling.",
      "from": {},
      "startTime": "2022-07-28T00:30:23.072Z",
      "endTime": "2022-07-28T00:30:23.872Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 1
        },
        "suggested": "positive"
      }
    },
    {
      "id": "5447911688110080",
      "text": "Thank you.",
      "from": {},
      "startTime": "2022-07-28T00:30:24.372Z",
      "endTime": "2022-07-28T00:30:24.872Z",
      "conversationId": "6428584355823616",
      "phrases": [],
      "sentiment": {
        "polarity": {
          "score": 0.825
        },
        "suggested": "positive"
      }
    }
  ]
}

Get speech-to-text transcripts

👍Try our interactive examples!

Optional query parameters

Response

Example response

👍
Try our interactive examples!