# Sinch Node.js SDK for Voice API The Sinch Node.js SDK allows you to quickly interact with the from inside your Node.js applications. When using the Node.js SDK, the code representing requests and queries sent to and responses received from the are structured similarly to those that are sent and received using the . The fastest way to get started with the SDK is to check out our [getting-started](/docs/voice/getting-started/node-sdk/make-call) guides. There you'll find all the instructions necessary to download, install, set up, and start using the SDK. ## Syntax Note: This guide describes the syntactical structure of the Node.js SDK for the Voice API, including any differences that may exist between the API itself and the SDK. For a full reference on Voice API calls and responses, see the [Voice API Reference](/docs/voice/api-reference/voice). The code sample below is an example of how to use the Node.js SDK to make a Text to speech phone call. We've also provided an example that accomplishes the same task using the REST API. SDK index.js // eslint-disable-next-line no-unused-vars import { Voice, VoiceService } from '@sinch/sdk-core'; /** @param {VoiceService} voiceService */ export const execute = async (voiceService) => { const recipientPhoneNumber = 'the_phone_number_to_call'; const callingNumber = 'the_calling_number'; /** @type {Voice.TtsCalloutRequestData} */ const requestData = { ttsCalloutRequestBody: { method: 'ttsCallout', ttsCallout: { destination: { type: 'number', endpoint: recipientPhoneNumber, }, cli: callingNumber, locale: 'en-US/male', text: 'Hello, this is a call from Sinch.', }, }, }; const response = await voiceService.callouts.tts(requestData); console.log(`Callout response: \n${JSON.stringify(response, null, 2)}`); }; REST API ```javascript const APPLICATION_KEY = ""; const APPLICATION_SECRET = ""; const SINCH_NUMBER = ""; const LOCALE = ""; const TO_NUMBER = ""; const basicAuthentication = APPLICATION_KEY + ":" + APPLICATION_SECRET; const fetch = require('cross-fetch'); const ttsBody = { method: 'ttsCallout', ttsCallout: { cli: SINCH_NUMBER, destination: { type: 'number', endpoint: TO_NUMBER }, locale: LOCALE, text: 'This is a call from sinch', } }; fetch("https://calling.api.sinch.com/calling/v1/callouts", { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Basic ' + Buffer.from(basicAuthentication).toString('base64') }, body: JSON.stringify(ttsBody) }).then(res => res.json()).then(json => console.log(json)); ``` This example highlights the following required to successfully make a Voice API call using the Sinch Node.js SDK: - [Client initialization](#client) - [Voice domain access](#voice-domain) - [Endpoint usage](#endpoint-categories) - [Field population](#request-and-query-parameters) ## Client When using the Sinch Node.js SDK, you initialize communication with the Sinch backend by initializing the Node.js SDK's main client class. This client allows you to access the functionality of the Sinch Node.js SDK. ### Initialization To start using the SDK, you need to initialize the main client class with your credentials from your Sinch [dashboard](https://dashboard.sinch.com/dashboard). ```javascript const {SinchClient} = require('@sinch/sdk-core'); const sinchClient = new SinchClient({ applicationKey: "YOUR_application_key", applicationSecret: "YOUR_application_secret" }); ``` Note For testing purposes on your local environment it's fine to use hardcoded values, but before deploying to production we strongly recommend using environment variables to store the credentials, as in the following example: **`.env` File** ```shell APPKEY="YOUR_application_key" APPSECRET="YOUR_application_secret" ``` **`app.js` File** ```javascript const {SinchClient} = require('@sinch/sdk-core'); const sinchClient = new SinchClient({ applicationKey: process.env.APPKEY, applicationSecret: process.env.APPSECRET }); ``` Note If you are using the Node.js SDK for multiple products that use different sets of authentication credentials, you can include all of the relevant credentials in the same configuration object, as in the following example: ```javascript const {SinchClient} = require('@sinch/sdk-core'); const sinchClient = new SinchClient({ projectId: "YOUR_project_id", keyId: "YOUR_access_key", keySecret: "YOUR_access_secret", applicationKey: "YOUR_application_key", applicationSecret: "YOUR_application_secret" }); ``` ## Voice domain The Sinch Node.js SDK organizes different functionalities in the Sinch product suite into domains. These domains are accessible through the client. For example, `sinch.voice.[endpoint_category].[method()]`. In the Sinch Node.js SDK, Voice API endpoints are accessible through the client. The naming convention of the endpoint's representation in the SDK matches the API: - `voice.callouts` - `voice.calls` - `voice.conferences` - `voice.applications` For example: ```javascript const response = await sinchClient.voice.callouts.tts({ ttsCalloutRequestBody: { method: 'ttsCallout', ttsCallout: { cli: 'YOUR_Sinch_number', destination: { type: 'number', endpoint: 'YOUR_phone_number' }, text: 'This is a test call from Sinch using the Node.js SDK.' } } }); ``` The `voice.callouts` category of the Node.js SDK corresponds corresponds to the [callouts](/docs/voice/api-reference/voice/callouts/) endpoint. The mapping between the API operations and corresponding Node.js methods are described below: | API operation | SDK method | | --- | --- | | [Makes a Text-to-speech callout](/docs/voice/api-reference/voice/callouts/callouts#callouts/callouts/request) | `tts()` | | [Makes a Conference callout](/docs/voice/api-reference/voice/callouts/callouts#callouts/callouts/request) | `conference()` | | [Makes a Custom callout](/docs/voice/api-reference/voice/callouts/callouts#callouts/callouts/request) | `custom()` | The `voice.calls` category of the Node.js SDK corresponds corresponds to the [calls](/docs/voice/api-reference/voice/calls/) endpoint. The mapping between the API operations and corresponding Node.js methods are described below: | API operation | SDK method | | --- | --- | | [Get information about a call](/docs/voice/api-reference/voice/calls/calling_getcallresult) | `get()` | | [Manage call with `callLeg`](/docs/voice/api-reference/voice/calls/calling_managecallwithcallleg) | `manageWithCallLeg()` | | [Updates a call in progress](/docs/voice/api-reference/voice/calls/calling_updatecall) | `update()` | The `voice.conferences` category of the Node.js SDK corresponds corresponds to the [conferences](/docs/voice/api-reference/voice/conferences/) endpoint. The mapping between the API operations and corresponding Node.js methods are described below: | API operation | SDK method | | --- | --- | | [Get information about a conference](/docs/voice/api-reference/voice/conferences/calling_getconferenceinfo) | `get()` | | [Manage a conference participant](/docs/voice/api-reference/voice/conferences/calling_manageconferenceparticipant) | `manageParticipant()` | | [Remove a participant from a conference](/docs/voice/api-reference/voice/conferences/calling_kickconferenceparticipant) | `kickParticipant()` | | [Remove all participants from a conference](/docs/voice/api-reference/voice/conferences/calling_kickconferenceall) | `kickAll()` | The `voice.applications` category of the Node.js SDK corresponds corresponds to the [configuration](/docs/voice/api-reference/voice/applications/) endpoint. The mapping between the API operations and corresponding Node.js methods are described below: | API operation | SDK method | | --- | --- | | [Return all the numbers assigned to an application](/docs/voice/api-reference/voice/applications/configuration_getnumbers) | `listNumbers()` | | [Assign a number or list of numbers to an application](/docs/voice/api-reference/voice/applications/configuration_updatenumbers) | `assignNumbers()` | | [Unassign a number from an application](/docs/voice/api-reference/voice/applications/configuration_unassignnumber) | `unassignNumber()` | | [Return the callback URLs for an application](/docs/voice/api-reference/voice/applications/configuration_getcallbackurls) | `getCallbackUrls()` | | [Update the callback URL for an application](/docs/voice/api-reference/voice/applications/configuration_updatecallbackurls) | `updateCallbackUrls()` | | [Returns information about a number](/docs/voice/api-reference/voice/applications/calling_querynumber) | `QueryNumber()` | The Voice API uses [call events](/docs/voice/api-reference/voice/callbacks) and [SVAML responses](/docs/voice/api-reference/svaml/) to dynamically control calls throughout their life cycle. The Node.js SDK has a number of builder and helper methods designed to aid in quickly constructing the correct SVAML responses for the various call events. The builder and helper methods available and their parameters are described in the example and tables below. ```javascript const iceResponse = new Voice.IceSvamletBuilder() .setAction(Voice.iceActionHelper.hangup()) .addInstruction(Voice.iceInstructionHelper.say('Thank you for calling Sinch! This call will now end.', 'en-US')) .build(); ``` | Call event | Builder method name | Methods | | --- | --- | --- | | [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) | `AceSvamletBuilder()` | `setAction()` or `addInstruction()` | | [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) | `IceSvamletBuilder()` | `setAction()` or `addInstruction()` | | [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) | `PieSvamletBuilder()` | `setAction()` or `addInstruction()` | Using these builder methods you can then build your SVAML responses using the following methods: **Actions:** | Helper method name | Action | | --- | --- | | `Voice.aceActionHelper.connectConf` | [connectConf](/docs/voice/api-reference/svaml/actions#connectconf) | | `Voice.aceActionHelper.continue` | [continue](/docs/voice/api-reference/svaml/actions#continue) | | `Voice.aceActionHelper.hangup` | [hangup](/docs/voice/api-reference/svaml/actions#hangup) | | `Voice.aceActionHelper.runMenu` | [runMenu](/docs/voice/api-reference/svaml/actions#runmenu) | | `Voice.iceActionHelper.connectConf` | [connectConf](/docs/voice/api-reference/svaml/actions#connectconf) | | `Voice.iceActionHelper.connectMxp` | [connectMxp](/docs/voice/api-reference/svaml/actions#connectmxp) | | `Voice.iceActionHelper.connectPstn` | [connectPstn](/docs/voice/api-reference/svaml/actions#connectpstn) | | `Voice.iceActionHelper.connectSip` | [connectSip](/docs/voice/api-reference/svaml/actions#connectsip) | | `Voice.iceActionHelper.hangup` | [hangup](/docs/voice/api-reference/svaml/actions#hangup) | | `Voice.iceActionHelper.park` | [park](/docs/voice/api-reference/svaml/actions#park) | | `Voice.iceActionHelper.runMenu` | [runMenu](/docs/voice/api-reference/svaml/actions#runmenu) | | `Voice.pieActionHelper.connectConf` | [connectConf](/docs/voice/api-reference/svaml/actions#connectconf) | | `Voice.pieActionHelper.connectSip` | [connectSip](/docs/voice/api-reference/svaml/actions#connectsip) | | `Voice.pieActionHelper.continue` | [continue](/docs/voice/api-reference/svaml/actions#continue) | | `Voice.pieActionHelper.hangup` | [hangup](/docs/voice/api-reference/svaml/actions#hangup) | | `Voice.pieActionHelper.runMenu` | [runMenu](/docs/voice/api-reference/svaml/actions#runmenu) | **Instructions:** | Helper method name | Action | | --- | --- | | `Voice.aceActionHelper.playFiles` | [playFiles](/docs/voice/api-reference/svaml/instructions#playfiles) | | `Voice.aceActionHelper.say` | [say](/docs/voice/api-reference/svaml/instructions#say) | | `Voice.aceActionHelper.setCookie` | [setCookie](/docs/voice/api-reference/svaml/instructions#setCookie) | | `Voice.aceActionHelper.startRecording` | [startRecording](/docs/voice/api-reference/svaml/instructions#startrecording) | | `Voice.iceActionHelper.answer` | [answer](/docs/voice/api-reference/svaml/instructions#answer) | | `Voice.iceActionHelper.playFiles` | [playFiles](/docs/voice/api-reference/svaml/instructions#playfiles) | | `Voice.iceActionHelper.say` | [say](/docs/voice/api-reference/svaml/instructions#say) | | `Voice.iceActionHelper.sendDtmf` | [sendDtmf](/docs/voice/api-reference/svaml/instructions#sendDtmf) | | `Voice.iceActionHelper.setCookie` | [setCookie](/docs/voice/api-reference/svaml/instructions#setcookie) | | `Voice.iceActionHelper.startRecording` | [startRecording](/docs/voice/api-reference/svaml/instructions#startrecording) | | `Voice.pieActionHelper.playFiles` | [playFiles](/docs/voice/api-reference/svaml/instructions#playfiles) | | `Voice.pieActionHelper.say` | [say](/docs/voice/api-reference/svaml/instructions#say) | | `Voice.pieActionHelper.sendDtmf` | [sendDtmf](/docs/voice/api-reference/svaml/instructions#senddtmf) | | `Voice.pieActionHelper.setCookie` | [setCookie](/docs/voice/api-reference/svaml/instructions#setcookie) | | `Voice.pieActionHelper.startRecording` | [startRecording](/docs/voice/api-reference/svaml/instructions#startrecording) | | `Voice.pieActionHelper.stopRecording` | [stopRecording](/docs/voice/api-reference/svaml/instructions#stoprecording) | Requests and queries made using the Node.js SDK are similar to those made using the Voice API. Path parameters, request body parameters, and query parameters that are used in the API are all passed as arguments to the corresponding Node.js method. For example, consider this example in which the `get()` method of the `voice.calls` class is invoked: ```javascript const response = await sinchClient.voice.calls.get({ callId: 'YOUR_call_id' }); ``` ```JSON url = "https://calling.api.sinch.com/calling/v1/calls/id/" + callId ``` When using the Voice API, `callId` would be included as a path parameter in the request. With the Node.js SDK, the `callId` parameter is used in an object passed as an argument in the `get()` method. Response fields match the API responses. They are delivered as Javascript objects.