GuidesAPI ReferenceSDKsIntegrationsWhat's New?
Guides

Code snippets - Telephony API

Suggest Edits

Connect to endpoints

The code snippet below dials in using PSTN and hangs up after 60 seconds.

const {
  sdk
} = require('@symblai/symbl-js');

sdk.init({
  // APP_ID and APP_SECRET come from the Symbl Platform: https://platform.symbl.ai
  appId:  APP_ID,
  appSecret: APP_SECRET,
  basePath: 'https://api.symbl.ai'
}).then(() => {
  sdk.startEndpoint({
    endpoint: {
      type: 'pstn', // This can be pstn or sip
      phoneNumber: PHONE_NUMBER,  // Use international code.
      dtmf: DTMF_MEETING_ID  // if password protected, use "dtmf": "<meeting_id>#,#<password>#"
    }
  }).then(connection => {
    console.log('Successfully connected.', connection.connectionId);

    // Scheduling stop endpoint call after 60 seconds for demonstration purposes
    // In real adoption, sdk.stopEndpoint() should be called when the meeting or call actually ends

    setTimeout(() => {
      sdk.stopEndpoint({
        connectionId: connection.connectionId
      }).then(() => {
        console.log('Stopped the connection');
        console.log('Summary Info:', connection.summaryInfo);
        console.log('Conversation ID:', connection.conversationId);
      }).catch(err => console.error('Error while stopping the connection', err));
    }, 60000);
  }).catch(err => console.error('Error while starting the connection', err));
}).catch(err => console.error('Error in SDK initialization.', err));

We recommend using SIP whenever possible instead of PSTN as it provides higher audio quality options as compared to PSTN. SIP endpoint provides an optional audio configuration as well.

Testing

Create a JavaScript file named app.js and copy this code into the file. Fill in the placeholder values with the proper values. Use npm to install the required libraries: npm install @symblai/symbl-js. Now in the terminal run:

$ node app.js

If successful you should receive a response in the console.

📘

Note

If you have any questions or concerns about our API, you can join our Support Slack or send us an email at [email protected]

Active speaker events

🚧

Optional Pushing Events

Pushing events is optional. If you don't have audio to process, then you can skip this step.

Connect to a PSTN endpoint and push speaker events

The following code snippet connects to a PSTN endpoint, creates a speakerEvent instance, and pushes events on connection.

const {
  sdk,
  SpeakerEvent
} = require('@symblai/symbl-js');

sdk.init({
  appId: APP_ID,
  appSecret: APP_SECRET,
  basePath: 'https://api.symbl.ai'
}).then(() => {
  sdk.startEndpoint({
    endpoint: {
      type: 'pstn',
      phoneNumber: 'PHONE_NUMBER', // Use international code.
      dtmf: 'DTMF_MEETING_ID' // if password protected, use "dtmf": "<meeting_id>#,#<password>#"
    }
  }).then(connection => {
    const connectionId = connection.connectionId;
    console.log('Successfully connected.', connectionId);

    const speakerEvent = new SpeakerEvent();
    speakerEvent.type = SpeakerEvent.types.startedSpeaking;
    speakerEvent.user = {
      userId: '[email protected]',
      name: 'John'
    };
    speakerEvent.timestamp = new Date().toISOString();

    sdk.pushEventOnConnection(
      connectionId,
      speakerEvent.toJSON(),
      (err) => {
        if (err) {
          console.error('Error during push event.', err);
        } else {
          console.log('Event pushed!');
        }
      }
    );

    // Scheduling stop endpoint call after 60 seconds for demonstration purposes
    // In real adoption, sdk.stopEndpoint() should be called when the meeting or call actually ends

    setTimeout(() => {
      sdk.stopEndpoint({
        connectionId: connection.connectionId,
      }).then(() => {
        console.log('Stopped the connection');
        console.log('Summary Info:', connection.summaryInfo);
        console.log('Conversation ID:', connection.conversationId);
      }).catch(err => console.error('Error while stopping the connection.', err));
    }, 60000);
  }).catch(err => console.error('Error while starting the connection', err));

}).catch(err => console.error('Error in SDK initialization.', err));

🚧

Optional Timestamp

Setting the timestamp for speakerEvent is optional but it's recommended to provide accurate timestamps in the events when they occurred to get more precision.

Events can be pushed to an on-going connection to have them processed. The code snippet to the right shows a simple example.

Every event must have a type to define the purpose of the event at a more granular level, usually to indicate different activities associated with the
event resource. For example - A "speaker" event can have type as started_speaking. An event may have additional fields specific to the event.

Currently, Symbl only supports the speaker event which is described below.

Speaker event

The speaker event is associated with different individual attendees in the meeting or session. An example of a speaker event is shown below.

In the code example the user needs to have a userId field to uniquely identify the user.

Speaker Event has the following types:

Started speaking event

The started_speaking event contains the details of the user who started speaking, with the start timestamp in ISO 8601 format.

const speakerEvent = new SpeakerEvent({
  type: SpeakerEvent.types.startedSpeaking,
  timestamp: new Date().toISOString(),
  user: {
    userId: '[email protected]',
    name: 'John'
  }
});

Stopped speaking event

Th stopped_speaking event contains the details of the user who stopped speaking with the stopped timestamp in ISO 8601 format.


const speakerEvent = new SpeakerEvent({
  type: SpeakerEvent.types.stoppedSpeaking,
  timestamp: new Date().toISOString(),
  user: {
    userId: '[email protected]',
    name: 'John'
  }
});

As shown in the above examples, it's okay to reuse the same speakerEvent instance per user, by changing the event's type to optimize by reducing the number of instances for SpeakerEvent.

A startedSpeaking event is pushed on the on-going connection. You can use pushEventOnConnection() method from the SDK to push the events.

Set language and timezone

This section describes how to set language and timezone when connecting to an endpoint.

Get started

This snippet shows how to use languages other than English and also how to set the timezone to the timezone in which the conversation is taking place.

🚧

Note

Currently, we only support English language in Streaming & Telephony API.
We support languages other than English only for our enterprise plan.
Please feel free to reach out to us at [email protected] for any queries.

Utilizing other languages

JavaScript SDK allows you to work with audio from multiple different languages.

For timezones, please refer to this.

You can also use moment-timezone node package to obtain a list of time zones like
the following: const timeZones = moment.tz.names()

❗️

Code Notes

  1. If the language is not specified then en-US(English - United States) is used as the default language.
  2. If no timezone is passed it will default to UTC.
  3. Insights like Action items, follow-ups, topics, and so on, are detected for English language only.
  4. Currently, we only support a single language at one time.

Code snippets

Configuration snippet

Here you set the language key to Japanese: "languages": ["ja-JP"], and the timezone to Tokyo: "timezone": "Asia/Tokyo".

{
  "operation": "start",
  "endpoint": {
    "type" : "pstn",
    "phoneNumber": "DEFAULT_PHONE_NUMBER"
  },
  "languages": ["ja-JP"],
  "timezone": "Asia/Tokyo",
  "actions": [{
    "invokeOn": "stop",
    "name": "sendSummaryEmail",
    "parameters": {
      "emails": [
        "[email protected]"
      ]
    }
  }],
  "data" : {
    "session": {
      "name" : "My Meeting"
    }
  }
}

Full snippet

const {sdk, SpeakerEvent} = require("@symblai/symbl-js");

sdk.init({
  appId: APP_ID,
  appSecret: APP_SECRET,
  basePath: "https://api.symbl.ai",
}).then(async() => {
  console.log('SDK initialized.');
  try {
    const phoneNumber = "PHONE_NUMBER";  // Telephony API currently only supports US phone numbers.

    sdk.startEndpoint({
      endpoint: {
        type: "pstn",
        phoneNumber: DEFAULT_PHONE_NUMBER,
      },
      languages: ["ja-JP"],
      timezone: "Asia/Tokyo",
      actions: [
        {
          invokeOn: "stop",
          name: "sendSummaryEmail",
          parameters: {
            emails: [
              "[email protected]"
            ],
          },
        },
      ],
      data: {
        session: {
          name: "Meeting name",
        },
      },
    }).then((connection) => {
      const connectionId = connection.connectionId;
      console.log("Successfully connected.", connectionId);
      console.log('Conversation ID', connection.conversationId);
    })
    .catch((err) => {
       console.error("Error while starting the connection", err);
    });
  } catch (e) {
    console.error(e);
  }
}).catch(err => console.error('Error in SDK initialization.', err));

Testing

Create a JavaScript file named app.js and copy this code into the file. Fill in the placeholder values with the proper values. Use npm to install the required libraries: npm install @symblai/symbl-js. Now in the terminal run:

$ node app.js

If successful you should receive a response in the console.

Updated about 2 years ago