Skip to main content

Telephony API Reference

Endpoint#

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: $AUTH_TOKEN" \
-d $'{F
"operation": "start",
"endpoint": {
"type" : "pstn",
"phoneNumber": "'$PHONE_NUMBER'" #
"dtmf": ",,$DTMF_MEETING_ID\#,,$MEETING_PASSCODE\#"
},
"actions": [{
"invokeOn": "stop",
"name": "sendSummaryEmail",
"parameters": {
"emails": [
"'$EMAIL_ADDRESS'"
]
}
}],
"data" : {
"session": {
"name" : "My Meeting"
}
}
}'

Request Parameters#

Here is a breakdown of the request options for the Telephony API endpoint:

Main Request Body#

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. See endpoint section below.
actionsarrayactions that should be performed while this connection is active. Currently only one action is supported - sendSummaryEmail. See actions section below.
dataobjectObject containing a session object which has a field name corresponding to the name of the meeting. See data section below.
languagesarrayThe first language code in the array is used to specify the session’s language. See languages section below.
timezonestringThe timezone name which comes from the IANA TZ database. See timezone section below.
Code Example#
{
"operation": "start",
"endpoint": {} // See endpoint config section below
"actions": {} // See actions section below
"data": {} // See data section below
"languages": {} // See languages section below
"timezone": {} // See timezone section below.
}

Endpoint Config#

FieldRequiredSupported ValueDescription
typeYesenum(["sip", "pstn"])Defines the type of connection. Only SIP and PSTN supported.
phoneNumberYesStringPhone number to be used to dial in to in E.164 format i.e. special characters like () or - and leading + or international access codes like 001 or 00 must be omitted. For e.g. - US number should look like 14082924837, whereas UK number should look like 447082924837.
dtmfNoStringDTMF sequence to be sent after call is received (ex: 939293#)
Code Example#
{
"endpoint": {
"type" : "pstn",
"phoneNumber": phoneNumber,
"dtmf": dtmfSequence
}
}

Actions#

FieldRequiredSupported ValueDescription
invokeOnYesenum(["start", "stop"])Event type on which the action should be performed.
nameYesStringName of the action that needs to be invoked. Only sendSummaryEmail is currently supported.
parametersYesObjectObject with required input parameter data for invocation of the specified action.
parameters.emailsYesString[]An array of emails.
Code Example#
{
"actions": [{
"invokeOn": "stop",
"name": "sendSummaryEmail",
"parameters": {
"emails": [
"user@example.com"
]
}
}]
}

Data#

FieldRequiredSupported ValueDescription
sessionNoStringContains information about the meeting.
session.nameNoStringThe name of the meeting.
Code Example#
{
"data" : {
"session": {
"name" : "My Meeting"
}
}
}

Languages#

FieldRequiredSupported ValueDescription
languagesNoString[]Language code in BCP-47 format

For more information about our supported languages, check here.

Code Example#
{
"language": ["ja-JP"]
}

Timezone#

FieldRequiredSupported ValueDescription
timezoneNoStringThe timezone name which comes from the IANA TZ database.
Code Example#
{
"timezone": "Asia/Tokyo"
}

Full Request Code Example#

{
endpoint: {
type: "pstn",
phoneNumber: "",
dtmf: ""
},
actions: [
{
invokeOn: "stop",
name: "sendSummaryEmail",
parameters: {
emails: [
"user@example.com"
],
},
},
],
data: {
session: {
name: meetingName,
},
},
}

Telephony API Endpoint Object#

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
resultWebSocketUrlSame 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

Code Example#

{
"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"
}

Supported Languages#

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

info

Currently, transcription punctuation is not supported for French (fr-CA) or Dutch (nl-NL) 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.

Code Example#

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

{
"operation": "start",
"endpoint": {
"type" : "pstn",
"phoneNumber": phoneNumber, // Should be the Zoom phone number this time.
"dtmf": `,,${DTMF_MEETING_ID}#,,${MEETING_PASSCODE}#`
},
"languages": ['es-US'],
"actions": [{
"invokeOn": "stop",
"name": "sendSummaryEmail",
"parameters": {
"emails": [
emailAddress
]
}
}],
"data" : {
"session": {
"name" : "My Meeting"
}
}
}
info

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

Specifying Timezones#

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

Code Example#

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

{
"operation": "start",
"endpoint": {
"type" : "pstn",
"phoneNumber": phoneNumber, // Should be the Zoom phone number this time.
"dtmf": `,,${DTMF_MEETING_ID}#,,${MEETING_PASSCODE}#`
},
"timezone": "US/Pacific",
"actions": [{
"invokeOn": "stop",
"name": "sendSummaryEmail",
"parameters": {
"emails": [
emailAddress
]
}
}],
"data" : {
"session": {
"name" : "My Meeting"
}
}
}
info

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