@dialogios/sdk

The @dialogios/sdk provides a lightweight and intuitive interface for working with the Dialogios API.

Using this SDK, you can easily send SMS messages and implement secure Two-Factor Authentication (2FA) flows with automatically generated OTP codes for user phone number verification. Also Dialogios provide another high-quality, cost-effective, and reliable Voice and SMS solutions at market-leading prices—services that help businesses reach clients worldwide.

To get started, visit the Dialogios Official Website, create an account, enable the Messaging service, add an alphanumeric sender ID, and obtain your credentials. Once your account is registered and the service is enabled, you’ll have access to the full functionality.

Installation

npm install @dialogios/sdk

Basic Usage

Send SMS message

import {
  Dialogios,
  type Credentials,
  type CreateSmsMessagePayload,
  type GetSmsMessagePayload,
  type CreateVerificationPayload,
  type CheckVerificationPayload,
  type RetryVerificationPayload,
  type GetVerificationPayload
} from '@dialogios/sdk'

// Required credentials account_sid, account_token
const dialogios = new Dialogios({
  account_sid: 'acs1e2e6c28-8631-4b96-8249-220624******',
  account_token: 'act18b99404-a653-445b-8885-4649e3******'
} as Credentials)

async function sendSms(params: CreateSmsMessagePayload) {
  return dialogios.createSmsMessage(params)
}

// Send SMS message
// Required properties: "from", "to", "text"
// All other properties are optional (such as "encoding", "callback_url")
const smsSent = await sendSms({
  from: "sender_id",
  to: "1234567890",
  text: "Hello World",
  encoding: "ucs2",
  callback_url: "https://requestcatcher.com"
})

console.log(`smsSent: ${JSON.stringify(smsSent)}`)

Properties:

• "from" - approved sender id or mobile phone number;
• "to" - recipient mobile phone number;
• "text" - text message;
• "encoding" - encoding formats (supported gsm7, ucs2, latin1, utf8);
• "callback_url" - callback URLs with SMS details and delivery status will be sent immediately after the SMS is sent.

Get SMS details

async function getSms(params: GetSmsMessagePayload) {
  return dialogios.getSmsMessage(params)
}

// Get SMS message details
// Required properties: "message_sid"
// Please note that after sending an SMS, the message details will only become available after a few minutes
const smsDetails = await getSms({
  message_sid: "639a083f-e0cc-17d7-9455-924452******",
})

console.log(`smsDetails: ${JSON.stringify(smsDetails)}`)

Properties:

• "message_sid" - message unique identifier.

Create Verification

This method initializes a new 2FA session and sends a one-time password (OTP) to the user via SMS. During this step, the API generates a verification code and delivers it to the recipient based on your message template. This method is used when a user begins authentication, registration, password reset, or any workflow requiring phone number validation.

async function createVerification(params: CreateVerificationPayload) {
  return dialogios.createVerification(params)
}

// Create Verification and send a code (OTP) to the user via SMS.
// Required properties: "channel", "from", "to", "text".
// All other properties are optional (such as "code_length", "max_retries", "max_checks", "encoding", "callback_url", "is_test")
// Please note that TTL for Verification is 30 minutes after creating
const verificationCreate = await createVerification({
    channel: "sms",
    from: "sender_id",
    to: "1234567890",
    text: "Your verification code is: {{code}}. Please do not share it with anyone.",
    code_length: 6,
    max_retries: 3,
    max_checks: 3,
    encoding: "ucs2",
    callback_url: "https://requestcatcher.com",
    is_test: false
})

console.log(`verificationCreate: ${JSON.stringify(verificationCreate)}`)

Properties:

• "channel" - verification channel (e.g., 'sms');
• "from" - sender phone number or alphanumeric Sender ID;
• "to" - recipient phone number (e.g., '1234567890');
• "text" - message text containing the {{code}} placeholder.
• "code_length" - length of the verification code (optional, from 4 to 8, by default 4).
• "max_retries" - maximum number of retries allowed (optional, from 1 to 10, by default 5).
• "max_checks" - maximum number of checks allowed (optional, from 1 to 10, by default 5).
• "encoding" - encoding formats (optional, supported gsm7, ucs2, latin1, utf8);
• "callback_url" - callback URLs with SMS details and delivery status will be sent immediately after the SMS is sent (optional).
• "is_test" - flag indicating if this is a test verification (optional). Allows to get more details.

Check Verification

This method validates the OTP entered by the user against the active verification session. Your backend submits the phone number and the code based on user input. If the code from user is correct, the verification is marked as successful. If the code is invalid, expired, or the max number of checks has been reached, the API responds with an appropriate error.

async function checkVerification(params: CheckVerificationPayload) {
  return dialogios.checkVerification(params)
}

// Check Verification.
// Required properties: "verification_sid", "to", "code".
const verificationCheck = await checkVerification({
    verification_sid: "vrf0b059159-daac-4d30-8839-b83358cd****",
    to: "1234567890",
    code: "123456"
})

console.log(`verificationCheck: ${JSON.stringify(verificationCheck)}`)

Properties:

• "verification_sid" - the unique identifier of the verification (based on created verification respond);
• "to" - recipient phone number (e.g., '1234567890');
• "code" - the verification code to check.

Retry Verification

This method sends a new SMS with a fresh OTP code within an existing verification session. This is used when the user reports not receiving the original message, entered the wrong code too many times, or needs a new attempt before the verification session expires. You may reuse the original SMS template or provide a new one. The API enforces the configured max_retries limit.

async function retryVerification(params: RetryVerificationPayload) {
  return dialogios.retryVerification(params)
}

// Retry Verification.
// Required properties: "verification_sid".
// Optional properties: "text".
const verificationRetry = await retryVerification({
    verification_sid: "vrf0b059159-daac-4d30-8839-b83358cd****",
    text: "Your new verification code is: {{code}}.",
})

console.log(`verificationRetry: ${JSON.stringify(verificationRetry)}`)

Properties:

• "verification_sid" - the unique identifier of the verification (based on created verification respond);
• "text" - the message text containing the {{code}} placeholder (optional).

Get Verification

This method retrieves the current status and details of an existing verification session using the verification_sid. Your backend can use this to check whether a verification is still active, completed, or expired. For test-mode verifications, the endpoint also returns extended diagnostic information, including sent messages, attempts, and timestamps. Each verification is available for up to 30 minutes before automatic cleanup.

async function getVerification(params: GetVerificationPayload) {
  return dialogios.getVerification(params)
}

// Get Verification.
// Required properties: "verification_sid".
const verificationGet = await getVerification({
    verification_sid: "vrf0b059159-daac-4d30-8839-b83358cd****"
})

console.log(`verificationGet: ${JSON.stringify(verificationGet)}`)

Properties:

• "verification_sid" - the unique identifier of the verification (based on created verification respond).

Note: The credentials and options shown above are placeholder values for demonstration purposes only. To start send SMS via Dialogios API you need first of all to create account and agree with terms of use. See more on https://www.dialogios.com.

Type Definitions Included

This package includes:

• *.d.ts files for all exported classes and functions
• Type definitions for all parameters and return values
• IntelliSense support in VS Code and other TypeScript-aware editors
• Declaration maps for better debugging experience