Telephony API

Get started with the Telephony API

The Symbl.ai Telephony API processes audio from SIP and PSTN interfaces and provides conversation intelligence in real time. Implement the Telephony API to capture audio from VoIP or phone calls, and generate intelligence from those conversations.

Symbl.ai SDKs

The code samples provided for the Telephony API use the Symbl.ai JavaScript and Python. For details about the SDKs and additional code samples, see:

Conversation intelligence

Once you have a conversation ID, you can view speaker analytics using Get analytics. You can call Get analytics during the conversation or afterward.

You can also use the conversation ID to view real-time interim results of the transcript. Interim results are intermediate transcript predictions retrieved during a real-time conversation that are likely to change before the automatic speech recognition (ASR) engine returns its final results. During a conversation, use the Get messages operation to view interim transcript results. Use the same operation to view the final transcript after a conversation.

After the conversation is complete, use the conversation ID to view insights described in Automatic Speech Recognition.

Authentication

The following code samples ask you to include your App ID and App Secret, the credentials used to generate Symbl.ai API access tokens, for testing purposes only. For a production environment, Symbl.ai recommends that you do not store your Symbl.ai API credentials in plain text or in your source code.

For more information about your App ID and App Secret, see the Get Started Guide.

Process a conversation with the JavaScript SDK

This section describes how to use the JavaScript SDK to open a connection, process an audio stream, and close a connection.

Before you begin

Before you try the code samples, ensure your developer environment meets the following requirements.

Install Node.js
- Install Node.js with a package manager.
- Download and install Node.js manually.
Create a new directory or folder and then, on the command line, initialize a Node.js project.
```
npm init -y
```
In the new directory, create a file named telephony.js.
On the command line, install the Symbl.ai JavaScript SDK with npm.
```
npm install @symblai/symbl-js
```

Try the Telephony API

To try the code sample, paste the following code into your telephony.js file and replace the placeholder values.

This code sample authorizes you with the Telephony API and uses PSTN to call a given phone number. The sample also returns a conversation ID, which can be used to generate conversation intelligence.

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

// START changing values here.

const appId = '<APP_ID>';
const appSecret = '<APP_SECRET>';
const phoneNumber = '<PHONE_NUMBER>';
const meetingName = '<TITLE>';

// STOP changing values here.

(async () => {
    try {
        // Initialize the SDK
        await sdk.init({
            appId: appId,
            appSecret: appSecret,
            basePath: 'https://api.symbl.ai',
        })

        // Start Real-time Request (Uses Real-time WebSocket API behind the scenes)
        const connection = await sdk.startEndpoint({
            endpoint: {
                type: 'pstn',
                phoneNumber: phoneNumber,
            },
            insightTypes: ['action_item', 'question', 'follow_up', 'topic'],
            data: {
                session: {
                    name: meetingName,
                },
            },
        });

        const { connectionId } = connection;
        console.log('Successfully connected. Connection Id: ', connectionId);

        // Subscribe to connection using connectionId.
        sdk.subscribeToConnection(connectionId, (data) => {
            const { type } = data;
            if (type === 'transcript_response') {
                const { payload } = data;

                // You get live transcription here
                console.log(`Live: ${payload && payload.content}`);

            } else if (type === 'message_response') {
                const { messages } = data;

                // You get any messages here
                messages.forEach(message => {
                  console.log(`Message: ${message.payload.content}`)
                })
            } else if (type === 'insight_response') {
                const { insights } = data;
            }
        });

        // Stop call after 60 seconds to automatically.
        setTimeout(async () => {
            const connection = await sdk.stopEndpoint({
                connectionId
            });
            console.log('Stopped the connection');
            console.log('Conversation ID:', connection.conversationId);
        }, 60 * 1000); // Change the 60 to however many seconds you want.
    } catch (e) {
        console.error('Error: ', e)
    }
})();

Where:

<APP_ID> and <APP_SECRET> are your App ID and Secret from your Symbl.ai Home page.
<TITLE> is the name of the meeting or conversation. If no name is provided, the Streaming API sets the name to the conversation ID.
<PHONE_NUMBER> is a phone number in E.164 format. For example, +16175550055. For testing the code sample, use a phone number that you have access to.

To run the code sample:

On the command line, go to your Node.js project directory.
Run the code sample.
```
node telephony.js
```
When you run the code, the Telephony API places a phone call to the given number and captures any spoken conversation. The connection automatically closes after 60 seconds.

Process a conversation with the Python SDK

This section describes how to use the Python SDK to open a connection, process an audio stream, and close a connection.