Skip to content

Latest commit

 

History

History
172 lines (135 loc) · 8.73 KB

README.md

File metadata and controls

172 lines (135 loc) · 8.73 KB
Raw

Sinch Node.js SDK

GitHub Workflow Status Node.js LTS Latest Release License

Here you'll find documentation related to the Sinch Node.js SDK, including how to install it, initialize it, and start developing Node.js code using Sinch services.

To use Sinch services, you'll need a Sinch account and access keys. You can sign up for an account and create access keys at dashboard.sinch.com.

Once logged-in you'll find different sets of credentials to access to the various Sinch APIs:

  • On the Account dashboard, you will find your projectId and access keys composed of pairs of keyId / keySecret. Unless mentionned otherwise, these are the credentials you will need to access most of the Sinch APIs
  • For the Verification and Voice APIs, you will find pairs of App key / App secret in the Verification dashboard and the Voice dashboard respectively. Note that the apps are the same, wherever you access them.
  • For the SMS API, the standard credentials (projectId, keyId, keySecret) are available only in the US and EU regions. If your business involves any of the other regions (BR, CA, AU), you will need to use your servicePlanId that you can find on the Service APIs dashboard. Note that the servicePlanId supports all the regions (US, EU, BR, CA, AU).
  • The Conversation API uses the standard credentials (projectId, keyId, keySecret) and is available on the US, EU and BR regions.

For more information on the Sinch APIs on which this SDK is based, refer to the official developer documentation portal.

Prerequisites

Before being able to execute the commands described below, you will need to install Node.js. We recommend to install the current or the LTS version.

NPM will come with the Node.js installation. If you want to use yarn as a package manager, you'll need to install it separately with the following command:

npm install --global yarn

Warning: Do not use this Node.js library in front-end applications (Angular, React, Vue.js, ...). Doing so can expose your Sinch credentials to end-users as part of the HTML/JavaScript files loaded on their browser.

Node.js supported versions

The Sinch Node.js SDK follows the Node.js release cycle.

This means that Node.js version 18 will be supported until May 2025. However, we recommend you to use the current LTS (20.11.0) or the current Node.js version.

Installation

With NPM

# Create a new folder (For Windows Command Prompt or PowerShell users, replace 'mkdir' by 'md')
mkdir my-sinch-app
# Move to the new folder
cd my-sinch-app
# Init the project (provide information about your project, such as package name, version, description, ...)
npm init
# Install the Sinch Node.js SDK dependency
npm install @sinch/sdk-core

With Yarn

# Create a new folder (For Windows Command Prompt or PowerShell users, replace 'mkdir' by 'md')
mkdir my-sinch-app
# Move to the new folder
cd my-sinch-app
# Init the project (provide information about your project, such as package name, version, description, ...)
yarn init
# Install the Sinch Node.js SDK dependency
yarn add @sinch/sdk-core

SDK usage

Constructor

To initialize communication with the Sinch servers, credentials obtained from the Sinch dashboard must be provided to the main client class of this SDK. It's highly recommended to not hardcode these credentials and to load them from environment variables instead.

import {
  SinchClient,
} from '@sinch/sdk-core';

const sinchClient = new SinchClient(sinchClientParameters);

where sinchClientParameters is an object containing the properties required to access the API you want to use:

  • for Verification and Voice APIs:
    • applicationKey
    • applicationSecret
    • (For the Voice API, voiceRegion is optional. Default is empty).
  • for SMS API when using the AU, BR or CA region (works also for US and EU)
    • servicePlanId
    • apiToken
    • (region is optional. Default is US).
  • for all the other APIs (including SMS is using the US and EU regions only)
    • projectId
    • keyId
    • keySecret
    • (For the SMS API, region is optional. Default is US).

From this client, you have access to all the SDK services supporting the Sinch APIs:

import {
  SinchClient,
} from '@sinch/sdk-core';

const sinch = new SinchClient(sinchClientParameters);
const conversationService = sinch.conversation;
const elasticSipTrunkingService = sinch.elasticSipTrunking;
const faxService = sinch.fax;
const numbersService = sinch.numbers;
const smsService = sinch.sms;
const verificationService = sinch.verification;
const voiceService = sinch.voice;

Promises

All the methods that interact with the Sinch APIs use Promises.

const response: SendSMSResponse = await smsService.batches.send({
   sendSMSRequestBody: {
      to: [
         '+12223334444',
         '+12223335555'
      ],
      from: '+12228889999',
      parameters: {
         name: {
            '+12223334444': 'John',
            default: 'there',
         }
      },
      body: 'Hi ${name}',
      type: 'mt_text',
   },
});
console.log(`The SMS has been sent successfully. Here is the batch id: ${response.id}`)

Supported APIs

Here is the list of the Sinch products and their level of support by the Node.js SDK:

API Category API Name Status
Messaging SMS API ✅
Conversation API ✅
Fax API (beta) ✅
Voice and Video Voice API ✅
Elastic SIP Trunking API (beta) ✅
Numbers & Connectivity Numbers API ✅
Verification Verification API ✅

Note: (beta) means that the underlying API product is still in beta version and requires specific actions for the end user to be able to use it. Please check on the dashboard or with your account manager.

Packages

The Sinch Node.js SDK is packaged in the following way:

  • @sinch/sdk-core: package defining the SinchClient class and wrapping all the other packages.
  • @sinch/sms: package that contains SMS services: Batches, Delivery reports, Inbounds, Groups and Webhooks callbacks.
  • @sinch/conversation: package that contains Conversation services: App, Capability, Contact, Conversation, Events, Messages, Templates V1 and V2, Transcoding, Webhooks management and Webhooks callbacks.
  • @sinch/voice: package that contains the Voice services: Callouts, Calls, Conferences, Applications management and Webhooks callbacks.
  • @sinch/numbers: package that contains the Numbers services: Available number, Active number, Available regions, Callbacks management and Webhooks callbacks.
  • @sinch/verification: package that contains the Verification services: Verification start and report, Verification status and Webhooks callbacks.
  • @sinch/fax: package that contains the Fax services: Services, Faxes and Faxes-on-emails.
  • @sinch/elastic-sip-trunking: package that contains the Elastic SIP Trunking services: SIP Trunks, Access Control List, SIP Endpoints, Country Permissions, Phones Numbers and Calls.
  • @sinch/sdk-client: package included by all the other ones that contains the API client classes and helpers.

Examples

You can find:

Contact

Developer Experience engineering team: devexp@sinch.com