# 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
```javascript index.js
/**
 * Class to place a demo Voice call using the Sinch Node.js SDK.
 */
export class VoiceSample {
  /**
   * @param { import('@sinch/sdk-core').VoiceService } voiceService - the VoiceService instance from the Sinch SDK containing the API methods.
   */
  constructor(voiceService) {
    this.voiceService = voiceService;
  }

  async start() {
    const caller = 'CALLER_NUMBER';
    const recipient = 'RECIPIENT_PHONE_NUMBER';

    const response = await this.voiceService.callouts.tts({
      ttsCalloutRequestBody: {
        method: 'ttsCallout',
        ttsCallout: {
          destination: {
            type: 'number',
            endpoint: recipient,
          },
          cli: caller,
          text: 'Hello, this is a call from Sinch. Congratulations! You just made your first call.',
        },
      },
    });

    console.log('Call ID:', response.callId);
  }
}
```

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`![external](/assets/external-blue.5a59beb5e5a442f78b530509ddf6b5d0fa705285ff8181e59adf96b5c2c73e25.33310b29.svg)](https://developers.sinch.com/sdk/sinch-sdk-node/1.5.0/classes/CalloutsApi.html)
- [`voice.calls`![external](/assets/external-blue.5a59beb5e5a442f78b530509ddf6b5d0fa705285ff8181e59adf96b5c2c73e25.33310b29.svg)](https://developers.sinch.com/sdk/sinch-sdk-node/1.5.0/classes/CallsApi.html)
- [`voice.conferences`![external](/assets/external-blue.5a59beb5e5a442f78b530509ddf6b5d0fa705285ff8181e59adf96b5c2c73e25.33310b29.svg)](https://developers.sinch.com/sdk/sinch-sdk-node/1.5.0/classes/ConferencesApi.html)
- [`voice.applications`![external](/assets/external-blue.5a59beb5e5a442f78b530509ddf6b5d0fa705285ff8181e59adf96b5c2c73e25.33310b29.svg)](https://developers.sinch.com/sdk/sinch-sdk-node/1.5.0/classes/ApplicationsApi.html)


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.