Speech-to-text

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:

For additional reference information, see Retrieve Messages from Conversations.

Optional query parameters

This request supports the following optional query parameters.

ParameterTypeDescription
excludeArrayAn 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.
redactBooleanEnables the Redaction feature. When true, detected entities are redacted in messages.

If not included, the default value is false.
sentimentStringEnables Sentiment Analysis for each sentence.

If not included, the default value is false.
verboseStringEnables 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.

FieldDescription
idThe unique ID of the message in the conversation.
textThe 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.
fromContains 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.idThe unique ID of the speaker.
from.nameThe name of the speaker.
from.emailThe email address of the speaker.
startTimeThe start time of the message.
endTimeThe end time of the message.
conversationIdThe conversation ID of the conversation that the message was extracted from.
phrasesAn 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.
sentimentContains 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.polarityContains the sentiment polarity score for the message.
sentiment.polarity.scoreA number from -1 to 1 that represents the sentiment of the message.
sentiment.suggestedThe 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"
      }
    }
  ]
}