Submit Telephony API

The Telephony Voice API allows you to easily use Symbl's Language Insights capabilities.

It exposes the functionality of Symbl to dial-in to the conference. Supported endpoints are given below. Additionally, events can be passed for further processing. The supported types of events are discussed in detail in the section below.

Symbl will connect to your SIP or PSTN exposed endpoints. The Audio stream will be fetched from the SIP or PSTN connection once connected.

HTTP REQUEST#

POST https://api.symbl.ai/v1/endpoint:connect

Example API call#

curl -k -X POST "https://api.symbl.ai/v1/endpoint:connect" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_auth_token>" \
-d @location_of_fileName_with_request_payload

Request Parameters#

FieldTypeDescription
operationstringenum([start, stop]) - Start or Stop connection
endpointobjectObject containing Type of the session - either pstn or sip, phoneNumber which is the meeting number symbl should call with country code prepended and dtmf which is the conference passcode.
actionsarrayactions that should be performed while this connection is active. Currently only one action is supported - sendSummaryEmail
dataobjectObject containing a session object which has a field name corresponding to the name of the meeting
languagesarrayThe first language code in the array is used to specify the session’s language.

languages#

Language is specified by passing an array of language codes to the language parameter when making a call to the startEndpoint.

info

Currently, transcription punctuation is not supported for French (fr-CA) or Dutch (nl-NL) languages.

Supported Languages#

The following list of languages(with their BCP-47 language-codes) are currently supported:

Supported LanguagesCode
English (United States)en-US
English (United Kingdom)en-GB
English (Australia)en-AU
English (Ireland)en-IE
English (India)en-IN
English (South Africa)en-ZA
Russian (Russian Federation)ru-RU
French (Canada)fr-CA
French (France)fr-FR
German (Germany)de-DE
Italian (Italy)it-IT
Dutch (Netherlands)nl-NL
Japanese (Japan)ja-JP
Spanish (United States)es-US
Spanish (Spain)es-ES
Arabic (Saudi Arabia)ar-SA
Hindi (India)hi-IN
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
Persian (Iran)fa-IR
caution
  1. If the language is not specified then en-US(English - United States) is used as the default language.
  2. Insights like Action items, follow-ups, topics, etc are detected for English language only.

Example#

Below is an example of specifying that the meeting’s language should be in Spanish.

sdk.startEndpoint({
endpoint: {
audioConfig: {
encoding: 'OPUS',
sampleRate: 16000
},
type: 'sip',
uri: 'sip:support@symbl.ai.3cx.com'
},
languages: ['es-US']
});
}
info

If a language is not specified, it will currently fall back to English (en-US).

Timezone#

Specifying a timezone when initiating a session will result in the Summary UI displaying the meeting start time for that given region.

curl --location --request POST 'https://api.symbl.ai/v1/endpoint:connect' \
--header 'x-api-key: <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"operation": "start",
"endpoint": {
"type" : "pstn",
"phoneNumber": "__phone_number__",
"dtmf": "__dtmf_sequence__"
},
"actions": [{
"invokeOn": "stop",
"name": "sendSummaryEmail",
"parameters": {
"emails": [
"__email_address__",
]
}
}],
"data" : {
"session": {
"name" : "__name_of_this_call__"
}
},
"languages": ["it-IT"]
}'

Example#

Below is an example of setting the timezone to the Pacific Timezone by passing the TZ database name to the timezone parameter while initiating a session:

sdk.startEndpoint({
endpoint: {
audioConfig: {
encoding: 'OPUS',
sampleRate: 16000
},
type: 'sip',
uri: 'sip:support@symbl.ai.3cx.com'
},
timezone: ' US/Pacific'
});
info

If no timezone is specified it will fall back to UTC time zone.

Response Object#

The above request returns a response structured like this:

{
"eventUrl": "https://api.symbl.ai/v1/event/771a8757-eff8-4b6c-97cd-64132a7bfc6e",
"resultWebSocketUrl": "wss://api.symbl.ai/events/771a8757-eff8-4b6c-97cd-64132a7bfc6e",
"connectionId": "771a8757-eff8-4b6c-97cd-64132a7bfc6e",
"conversationId": "51356232423"
}

Response Parameters#

FieldDescription
eventUrlREST API to push speaker events as the conversation is in progress, to add additional speaker context in the conversation. Example - In an on-going meeting, you can push speaker events
resultWebSocketUrlobjSame as eventUrl but over WebSocket. The latency of events is lower with a dedicated WebSocket connection.ct
connectionIdEphemeral connection identifier of the request, to uniquely identify the telephony connection. Once the connection is stopped using “stop” operation, or is closed due to some other reason, the connectionId is no longer valid
conversationIdRepresents the conversation - this is the ID that needs to be used in conversation api to access the conversation

Full Code Example#

To specify a language and timezone while initiating a meeting, two parameters required - languages and timezone.

The following code snippet would initiate a session with Japanese as the language and JST as the timezone.

sdk.startEndpoint({
endpoint: {
audioConfig: {
encoding: 'OPUS',
sampleRate: 16000
},
type: 'sip',
uri: 'sip:support@symbl.ai.3cx.com'
},
languages: ['ja-JP'],
timezone: 'Asia/Tokyo'
});