Node.JS - SDK

The Betatel SDK is designed to provide a straightforward and efficient way to implement SMS messaging within your Node.js/TypeScript applications. It abstracts the complexities of interacting directly with the underlying API, allowing developers to quickly and easily integrate SMS sending, status checking, and message tracking. This SDK is particularly useful for scenarios requiring reliable SMS communication and delivery tracking.

Installation

Install the SDK

npm install betatelsdk

Import the SDK

import { BetatelSDK } from 'betatelsdk';

Initialization

Create an instance of the BetatelSDK:

const sdk = new BetatelSDK({
  api_key: "YOUR_API_KEY",    // Replace with your API key
  user_id: "YOUR_USER_ID"     // Replace with your user ID
});

// Access SMS service
const smsService = sdk.sms;

Replace YOUR_API_KEY and YOUR_USER_ID with the actual values provided by your service.

warning

Security Notice:

Keep your API key secure. Do not expose it in client-side code or commit it to version control. Store it securely and retrieve it from a safe source.

Usage: Sending SMS Messages

Use the send method:

async function sendSMS(from: string, to: string, message: string) {
  try {
    const response = await sdk.sms.send(from, to, message);

    console.log("SMS sent successfully!");
    console.log("Message ID:", response.messageId);
    console.log("From:", response.from);
    console.log("To:", response.to);

    return response.messageId;
  } catch (error) {
    console.error("Failed to send SMS:", error.message);
    throw error;
  }
}

// Example usage:
sendSMS("100200300", "+1987654321", "Hello from Betatel SDK!")
  .then(messageId => {
    console.log(`SMS sent with ID: ${messageId}`);
  });

tip

Phone Number Formatting:

Ensure that the phone numbers you provide are in the correct format expected by your API. The 'from' number should be your registered sender ID, and the 'to' number should include the country code.

Parameter	Type	Description
from	string	The sender number or sender ID.
to	string	The recipient's phone number.
message	string	The text message to be sent.

Usage: Checking SMS Status

Use the getStatus method:

async function checkSMSStatus(messageId: string) {
  try {
    const status = await sdk.sms.getStatus(messageId);
    
    console.log("SMS Status:", status.status);
    console.log("Message ID:", status.messageId);
    console.log("User ID:", status.userId);
    
    return status;
  } catch (error) {
    console.error("Failed to get SMS status:", error.message);
    throw error;
  }
}

// Example usage:
checkSMSStatus("msg_123456").then(status => {
  if (status.status === "Delivered") {
    console.log("Message was delivered successfully!");
  }
});

Parameter	Type	Description
messageId	string	The unique identifier of the SMS message.

Usage: Getting Complete SMS Details

Use the getDetails method:

async function getSMSDetails(messageId: string) {
  try {
    const details = await sdk.sms.getDetails(messageId);
    
    console.log("=== SMS Details ===");
    console.log("Message ID:", details.messageId);
    console.log("Status:", details.status);
    console.log("From:", details.from);
    console.log("To:", details.to);
    console.log("Text:", details.text);
    console.log("Timestamp:", details.timestamp);
    console.log("Segments:", details.segments);
    console.log("User ID:", details.userId);
    
    return details;
  } catch (error) {
    console.error("Failed to get SMS details:", error.message);
    throw error;
  }
}

Error Handling:

The SMS methods will throw errors if the API calls fail or return non-success status codes. Wrap your SMS calls within try...catch blocks to handle these errors gracefully.

Example of complete integration

import { BetatelSDK } from 'betatelsdk';

const sdk = new BetatelSDK({
  api_key: "YOUR_API_KEY_HERE",  // Replace with your API key
  user_id: "YOUR_USER_ID_HERE"   // Replace with your user ID
});

async function completeSMSWorkflow() {
  try {
    // Step 1: Send SMS
    const response = await sdk.sms.send(
      "100200300",                    // from
      "+1987654321",                  // to
      "Hello from Betatel SDK!"       // message
    );
    
    console.log(`SMS sent with ID: ${response.messageId}`);
    
    // Step 2: Check status
    const status = await sdk.sms.getStatus(response.messageId);
    console.log(`Current status: ${status.status}`);
    
    // Step 3: Get full details
    const details = await sdk.sms.getDetails(response.messageId);
    console.log(`Message segments: ${details.segments}`);
    
  } catch (error) {
    console.error("SMS workflow failed:", error.message);
  }
}

completeSMSWorkflow();

note

Important notes

• Ensure that phone numbers are in the correct format expected by your API.
• The sender number must be registered and approved for SMS sending.
• Keep your API key and user ID secure and do not expose them in client-side code.
• Monitor your SMS usage and delivery rates through the status and details methods.