bestsms

The bestsms package, listed on npm, is BestSMS Australia's own TypeScript client for the BestSMS REST API v3.00. With it you can send text messages and look after your Addressbook and OptOut list from Node.js, with typed request arguments and typed results, and no need to write HTTP plumbing or response parsing. It works equally well from plain JavaScript.

Quick Example

import { BestSMS, ErrorResponseDTO } from 'bestsms';

const client = new BestSMS({ AuthToken: "[Your Auth Token]" });

const result = await client.Messaging.SMS.SendMessage({
    Message: "Hello from BestSMS",
    Destination: "+61491570006",
    Mode: "Test"
});

if (result instanceof ErrorResponseDTO) {
    console.error(result.Result, result.ErrorMessage);
} else {
    console.log(`Accepted - MessageID: ${result.MessageID}`);
}

Mode: "Test" makes the API treat the call as a successful submission without sending or charging anything. Take it out when you are ready to send for real. The Getting Started section explains where an Auth Token comes from.

What you can do

Messaging:

• SMS: send messages, then follow up on replies and inbound texts

Account tools:

• Addressbook: contacts, groups and which contacts belong to which group
• OptOut: keep track of destinations that must not be messaged
• Webhooks: typed payloads and a parseWebhook() helper for events that BestSMS pushes to your own server
• Reports: poll for message status, SMS replies and received SMS
• Actions: abort an SMS, or move it to a new send time, while it is still delayed

Supported Node.js versions

This is a server-side library. Requests go out through Node's built-in http and https modules, and SMS attachments are read from disk with fs, so it cannot be bundled for a browser. Code running in the browser (client-side React, Vue or Angular, or a plain <script> tag) should call your own backend, which in turn uses bestsms.

• Node.js: package.json sets no engines constraint. The code is compiled to an ES2020 target, which leaves optional chaining (?.) as written, so Node.js 14 is the practical minimum. The project's own build pipeline runs on Node.js 22.
• Module format: CommonJS, with .d.ts declarations included. Importing from an ES module project ("type": "module") also works: import { BestSMS } from 'bestsms' is valid in both module systems.
• TypeScript: the declarations use the export type * syntax, which arrived in TypeScript 5.0, so use 5.0 or later. The library itself is built with TypeScript 5.4 and above (^5.4.5). If you work in plain JavaScript, the types are simply ignored.

Only one runtime dependency is pulled in, google-libphonenumber, which the SDK uses to check that SMS destination numbers are mobile numbers before a request is made.

Installation

Add the package to your project with npm:

npm i bestsms

The source repository includes samples/ with runnable scripts for Messaging, Addressbook, OptOut, Actions, Reports and Webhooks. It also holds demo/, a small local-only NestJS REST API that wraps one endpoint around each SDK call.

Upgrading from bestsms 2.x

Release 3.x is an API v3.00 client and is not a drop-in replacement for the 2.x package. Documentation for the older client stays available under the v2.04 Node.js reference. The main differences are:

• The client is now a named export: import { BestSMS } from 'bestsms' replaces require('bestsms') with a default export.
• The constructor takes AuthToken and an optional URL. The Sender and APIKey arguments are gone.
• Calls follow the v3.00 resource paths (/sms, /addressbook, /optout) instead of the old Send, Get and Set groupings, and every method returns a Promise of a typed result or an ErrorResponseDTO.
• Actions.Resubmit has been removed. Abort and Reschedule remain, apply to SMS only, and take no Channel argument.
• New in 3.x: Contact.Search, the OptOut module (including Update and Batch), webhook types, Mode: "Test", TemplateID and attachments.

When you are ready, go to Getting Started and create your first BestSMS client.

Getting Started

Every integration starts by creating a BestSMS client, the object that gives you access to the whole BestSMS API.

Register an Account

You need a BestSMS account before anything else. No account yet? Register here, then return to this page.

API Credentials

Each request that bestsms makes carries your Auth Token in an Authorization: Bearer header. The token is never placed in a request body.

Export your Auth Token

1. Sign in to the BestSMS Dashboard
2. Open the 'Users' page
3. Add a new user, or pick an existing one
4. Switch on API access if it is currently off
5. Open its 'API' tab
6. Turn on 'Auth Token', then generate a fresh token
7. Press 'Copy' to put the token on your clipboard

Hand the token to the BestSMS constructor:

import { BestSMS } from 'bestsms';

const client = new BestSMS({ AuthToken: "[Your Auth Token]" });

The constructor takes an optional object with two fields, AuthToken and URL (the API base URL). It creates all five facades straight away: .Messaging, .Reports, .Actions, .Addressbook and .OptOut. There is just this one way to build a client, and no separate user object to set up first.

The Auth Token is mandatory

You must supply a token through either the AuthToken argument or the BESTSMS_AUTH_TOKEN environment variable. When both are missing, new BestSMS() throws straight away:

Error: BestSMS AuthToken is required. Pass it as AuthToken or set the BESTSMS_AUTH_TOKEN environment variable.

That constructor check is the only place where the client throws for a configuration problem. API calls themselves never reject for API or validation errors: the Promise resolves with an error object, as described under Response basics. (The webhook helper parseWebhook() is separate, and does throw on a body it cannot read; see Webhooks.)

Refresh or invalidate your Auth Token

1. Sign in to the BestSMS Dashboard
2. Open the 'Users' page
3. Select the user that has API access
4. Open its 'API' tab
5. Press the refresh/recycle button beside the Auth Token
6. Give the new token to every application that uses it

Refreshing disables the previous token at once. Applications still using it fail authentication until they are switched to the new token.

Environment Variables

bestsms can also be configured through environment variables, which suits CI pipelines and containers, or any situation where credentials should stay out of your source code. Only operating-system environment variables are read. No .env file is loaded for you, so a loader like dotenv is needed if your script relies on one.

import { BestSMS } from 'bestsms';

// No AuthToken passed, so BESTSMS_AUTH_TOKEN is read from the environment
const client = new BestSMS();

// An explicit token and a local test server
const local = new BestSMS({
    AuthToken: "your-token",
    URL: "https://localhost:5001/api/v3.00"
});

Setting environment variables

$env:BESTSMS_AUTH_TOKEN = "your-auth-token"

set BESTSMS_AUTH_TOKEN=your-auth-token

[System.Environment]::SetEnvironmentVariable("BESTSMS_AUTH_TOKEN", "your-auth-token", "User")

export BESTSMS_AUTH_TOKEN="your-auth-token"

[Service]
Environment="BESTSMS_AUTH_TOKEN=your-auth-token"

export BESTSMS_AUTH_TOKEN="your-auth-token"

The other three variables are set in exactly the same way, with only the name changing.

Response basics

Whichever method you call, the Promise settles with one of two kinds of object. A successful call yields a typed result object (for example MessagingApiSuccessResponseDTO with a MessageID) whose Result is "Success". A failed call yields an ErrorResponseDTO, a class exported by the package, with a Result string and an ErrorMessage that is always a string[], empty or not. If the API replies with a single string as ErrorMessage, the SDK wraps it in a one-element array for you.

import { BestSMS, ErrorResponseDTO } from 'bestsms';

const client = new BestSMS();

const response = await client.Messaging.SMS.SendMessage({
    Message: "Your appointment is confirmed for 10:30am tomorrow.",
    Destination: "+61491570006"
});

if (response instanceof ErrorResponseDTO) {
    for (const error of response.ErrorMessage) {
        console.log(`- Error=${error}`);
    }
} else {
    console.log(`Accepted - MessageID: ${response.MessageID}`);
}

Testing response.Result === "Success" narrows the type in exactly the same way. A failed response has one of these Result values:

• "Error": the SDK itself produced the failure, either because validation stopped the call before any request went out, or because of a transport problem (an unreachable host, a timeout, a body that is not JSON).
• "Failed" or "Unauthorized": reported by the API.
• Other API codes such as "RecordNotFound" (a 404) can also arrive. The declared type lists only the three values above, so compare Result as a plain string or use instanceof ErrorResponseDTO.

A reply is treated as a success when the HTTP status is 200 or when the body's Result is "Success". Keep in mind that acceptance is not delivery: a successful send tells you BestSMS took the message. To learn whether it reached the handset, poll with Reports or listen for Webhooks.

The internal Result enum is not exported from 'bestsms', so compare against the string literals above. The response DTO types (StatusApiResponseDTO, ActionApiResponseDTO, ContactApiResponseDTO, OptOutListApiResponseDTO and so on) are exported as types, and can be used to annotate your own functions:

import type { StatusApiResponseDTO } from 'bestsms';

function summarise(status: StatusApiResponseDTO): string {
    return `${status.JobNum}: ${status.Success} delivered, ${status.Failed} failed`;
}

Request validation

Before sending anything, the SDK checks the arguments it can verify locally. A missing or empty required value, such as the MessageID for Reports.Status.Poll(...) or Actions.Abort.SendRequest(...), does not throw and does not cause an HTTP request. Instead the Promise resolves to an ErrorResponseDTO with Result: "Error" and a readable ErrorMessage such as ["Missing MessageID"].

import { ErrorResponseDTO } from 'bestsms';

const response = await client.Reports.Status.Poll({ MessageID: "" });

if (response instanceof ErrorResponseDTO) {
    console.log(response.ErrorMessage); // ["Missing MessageID"]
}

The same applies to other local checks: a ToNumber that is not a mobile number, an unparseable SendTime, or a paging value out of range. The SMS, Reports and Actions sections list the checks that belong to each call. The Addressbook and OptOut calls take the same approach.

Common Response Values

Two exported TypeScript enums are used on the request side, and both can be imported from 'bestsms':

import { WebhookCallbackFormat, NotificationType } from 'bestsms';

Mode is not an enum. It is typed as the string literal 'Test', which is the only value it accepts.

Result fields that describe job and recipient state are declared as plain string, so no enum is available for them. The values the API returns are:

The Destination Model

There is no destination class to construct. SMS describes a recipient with the plain interface ISMSDestination, so you simply write object literals. IMessagingDestination is exported as well, and is currently an alias of ISMSDestination.

const destinations = [
    { ToNumber: "+61491570006", FirstName: "Alice" },
    { ToNumber: "+61491570007", FirstName: "Bob" },
];

await client.Messaging.SMS.SendMessage({
    Message: "Hello [[FirstName]], your order is on its way.",
    Destinations: destinations
});

These are the fields of ISMSDestination. All of them are optional strings:

Shorthand for simple sends

When a full Destinations array is overkill, SendMessage(...) accepts four single-field shorthands: Destination, ToNumber, ContactID and GroupID. Each one may hold several comma-separated values, and every value becomes its own destination:

await client.Messaging.SMS.SendMessage({
    Message: "Depot closed Monday for the public holiday.",
    Destination: "+61491570006,+61491570007"
});

Adding recipients with the builder

AddRecipient(...) on client.Messaging.SMS accepts a string (treated as { ToNumber }), an ISMSDestination, or an array mixing both, and it returns the channel so calls can be chained. Recipients added this way come first, followed by any in the Destinations you give to SendMessage(...):

const response = await client.Messaging.SMS
    .AddRecipient("+61491570006")
    .AddRecipient({ ToNumber: "+61491570007", FirstName: "Alice", Company: "Example Company" })
    .SendMessage({ Message: "Hello [[FirstName]], thanks for your order." });

Remember that a destination which is not a valid mobile number resolves to an error (Invalid ToNumber - must be mobile number - ...) before any request is made, and that a send with no destinations at all resolves to Empty Destination(s). See SMS for the complete argument list.

Actions & Reports

The SMS channel object only sends. client.Messaging.SMS has no Status, Reply, Received, Abort or Reschedule methods of its own, so polling goes through Reports (client.Reports.Status.Poll(...), client.Reports.SMSReply.Poll(...) and client.Reports.SMSReceived.Poll(...)) and changes to a delayed message go through Actions (client.Actions.Abort.SendRequest(...) and client.Actions.Reschedule.SendRequest(...)):

const response = await client.Actions.Reschedule.SendRequest({
    MessageID: "ID123456",
    SendTime: "2026-11-03T09:00"
});

SMS

The SMS module of the bestsms package sends text messages through the BestSMS REST API, to one recipient or to thousands. Texting works in both directions. You can watch each message move through delivery (covered under Poll for status further down) and collect what people text back, either by polling (covered under Poll for inbound SMS) or by letting BestSMS push each reply to your server, which is covered in Webhooks.

Every call is a Promise. It resolves to either a typed success object or an ErrorResponseDTO, and it does not reject for validation or API problems. Check the outcome with instanceof ErrorResponseDTO; Getting Started explains the result values.

Message Body Tokens

On top of the personalisation tokens listed under Destination Fields, the text in Message can carry these inline tokens, which BestSMS expands when it sends:

• [[Link:https://example.com/page]]: swaps the URL for a short link and records who clicks it.
• [[File1]]: is replaced by a link pointing at your first attached file, whether it came in through Attachments or AddAttachment(...). Additional files use [[File2]], [[File3]] and so on.
• [[REPLY]]: becomes a tappable link the recipient can use to answer, including from handsets that have no SMS reply feature of their own.

import { BestSMS } from 'bestsms';

const client = new BestSMS({ AuthToken: "[Your Auth Token]" });

await client.Messaging.SMS.SendMessage({
    Destination: "+61491570006",
    Message: "Your invoice is ready: [[Link:https://example.com/invoice/123]] Reply here: [[REPLY]]. Reply STOP to opt out.",
    Mode: "Test" // nothing is delivered in Test mode
});

Quick Example

If you leave AuthToken out, the constructor falls back to the BESTSMS_AUTH_TOKEN environment variable and throws if neither is present.

import { BestSMS, ErrorResponseDTO } from 'bestsms';

const client = new BestSMS({ AuthToken: "[Your Auth Token]" });

const response = await client.Messaging.SMS.SendMessage({
    Destination: "+61491570006",
    Message: "Test SMS",
    Reference: "Test",
    Mode: "Test" // nothing is delivered in Test mode
});

if (response instanceof ErrorResponseDTO) {
    console.error(response.Result, response.ErrorMessage);
} else {
    console.log(`Success - MessageID: ${response.MessageID}`);
}

Parameters

These are the fields of the ISMSArgs object accepted by SendMessage(...).

*Supply Message or TemplateID.
†Recipients come from Destinations, from the Destination/ToNumber/ContactID/GroupID shorthand, or from AddRecipient(...) on the builder. All of these are combined, so you can use them together.
‡Required only when WebhookCallbackURL is set.

The text, destination and file limits above (Message 1000 characters, MessageID 40, Reference 100, WebhookCallbackURL 500, SubAccount/Department 40, a single Destination 60) are enforced by the BestSMS API. The SDK does not count characters beforehand, so an over-long value comes back as an error from the server. Each attached file may have a name of up to 255 characters and up to 1,398,102 base64 characters of data (about 1 MB of file).

Checks made before anything is sent: when one of these fails, SendMessage(...) resolves to an ErrorResponseDTO with Result set to "Error" and no request goes out. The checks are: neither Message nor TemplateID given; no destination at all; a ToNumber that is not a valid mobile number (the SDK tries New Zealand then Australian numbering, then international format, so write numbers as +61...); WebhookCallbackURL without a valid WebhookCallbackFormat; a SendTime that doesn't parse as a date; a Mode other than Test; and an attachment path that does not exist. Only ToNumber values are checked this way. ContactID and GroupID are passed straight to the API.

Two calling styles: you can hand every field above to SendMessage({ ... }) as a single object. Or you can queue recipients and files first with client.Messaging.SMS.AddRecipient(...) and AddAttachment(...), each of which returns the same object so calls chain, and then finish with SendMessage({ ... }). Items queued on the builder go first, followed by any in the object you pass, and your object and its arrays are never modified. The queue is emptied by each SendMessage(...) call. Because the queue lives on the shared client.Messaging.SMS object, write the whole chain, including SendMessage, as one expression instead of adding recipients and then awaiting something unrelated before sending. AddAttachment(...) looks for the file straight away. A missing path is remembered, and the next SendMessage(...) resolves to { Result: "Error", ErrorMessage: ["Attachment file not found: <path>"] }.

Destination Fields (ISMSDestination)

Each entry of Destinations is an ISMSDestination object. When you give AddRecipient(...) a plain string, it is stored as { ToNumber: "<the string>" }; it also takes an ISMSDestination or an array mixing both. The interface lists a fixed set of fields, so the compiler flags a misspelt property in an object literal. That check exists only at build time, though: nothing stops an unknown key at runtime.

Code Samples

Single destination shorthand

The shortest route to a send is a message plus a Destination. Put several numbers in the string, separated by commas, to reach more than one person this way.

const response = await client.Messaging.SMS.SendMessage({
    Destination: "+61491570006,+61491570007",
    Message: "The office is closed today.",
    Mode: "Test" // nothing is delivered in Test mode
});

Multiple destinations, via the builder

Use AddRecipient(...) when recipients are gathered in several steps, or when raw numbers need to sit alongside Addressbook contacts and groups. Each call can take a string, an object, or a list that mixes the two.

const response = await client.Messaging.SMS
    .AddRecipient("+61491570006")
    .AddRecipient({ ToNumber: "+61491570007", FirstName: "Bob" })
    .AddRecipient([{ ContactID: "[Contact ID]" }, { GroupID: "[Group ID]" }])
    .SendMessage({
        Message: "Hi [[FirstName]]!",
        Reference: "Test SMS - Builder sample",
        Mode: "Test" // nothing is delivered in Test mode
    });

Addressbook ContactID/GroupID

When only one group or contact is involved, the top-level GroupID or ContactID is enough. To mix several groups, contacts and loose numbers in one send, list them all in Destinations.

// Everyone in one Addressbook group
const toGroup = await client.Messaging.SMS.SendMessage({
    Message: "Reminder: your subscription renews tomorrow.",
    GroupID: "[Group ID]",
    Mode: "Test" // nothing is delivered in Test mode
});

// One Addressbook contact
const toContact = await client.Messaging.SMS.SendMessage({
    Message: "Hi [[FirstName]], your order has shipped!",
    ContactID: "[Contact ID]",
    Mode: "Test"
});

// Groups, contacts and a plain number together
const bulk = await client.Messaging.SMS.SendMessage({
    Message: "Reminder: your subscription renews tomorrow.",
    Destinations: [
        { GroupID: "[Group ID 1]" },
        { GroupID: "[Group ID 2]" },
        { ContactID: "[Contact ID 1]" },
        { ToNumber: "+61491570006" }
    ],
    Mode: "Test"
});

Bulk send with per-destination personalisation

A single message can go to many people with each copy filled in for its own recipient, by putting the personalisation values on each ISMSDestination.

const response = await client.Messaging.SMS.SendMessage({
    Message: "Hi [[FirstName]], your appointment is on [[Custom1]].",
    Destinations: [
        { ToNumber: "+61491570006", FirstName: "Alice", Custom1: "Monday 3pm" },
        { ToNumber: "+61491570007", FirstName: "Bob", Custom1: "Tuesday 10am" }
    ],
    Mode: "Test" // nothing is delivered in Test mode
});

Send from a template, with sender options

When a message template already exists in your Dashboard, pass its TemplateID instead of Message. The sample also sets the sender ID, the address that gets reply notifications, and character conversion.

const response = await client.Messaging.SMS.SendMessage({
    TemplateID: "[Template ID]",
    Destinations: [{ ContactID: "[Contact ID]" }],
    FromNumber: "61408080909", // E.164 without the leading +
    SMSEmailReply: "[email protected]",
    CharacterConversion: true,
    Mode: "Test" // nothing is delivered in Test mode
});

Send a file via MessageLink

Name a local file in Attachments (or call AddAttachment(...)) and mention it in the text as [[File1]]. What the recipient receives is an SMS holding a link; the file is not embedded.

Security note: attachment paths are read from disk as given, with only a check that the file exists. Never build a path from unchecked user input. Resolve it against a folder you trust, and reject anything that escapes that folder, which is the same discipline any server-side file access calls for.

const response = await client.Messaging.SMS.SendMessage({
    Message: "Here is the photo you asked for: [[File1]]",
    Destination: "+61491570006",
    Attachments: ["path/to/photo.jpg"],
    Mode: "Test" // nothing is delivered in Test mode
});

// The same thing with the builder, and two files
const twoFiles = await client.Messaging.SMS
    .AddAttachment("path/to/photo.jpg")
    .AddAttachment("path/to/receipt.pdf")
    .SendMessage({
        Message: "Your files: [[File1]] [[File2]]",
        Destination: "+61491570006",
        Mode: "Test"
    });

Scheduled send with webhook callback

Pair SendTime/Timezone, which hold the message back, with WebhookCallbackURL, which tells you the moment it has finished. You then have no need to poll for status.

import { NotificationType, WebhookCallbackFormat } from 'bestsms';

const response = await client.Messaging.SMS.SendMessage({
    Message: "Don't forget your appointment.",
    Destination: "+61491570006",
    SendTime: "2026-12-31T09:00",
    Timezone: "AUS Eastern",
    NotificationType: NotificationType.Webhook,
    WebhookCallbackURL: "https://yourapp.example.com/webhooks/bestsms/result",
    WebhookCallbackFormat: WebhookCallbackFormat.JSON,
    Mode: "Test" // nothing is delivered in Test mode
});

Poll for status

At any point after sending you can ask how the job is going and what happened to each recipient. Reports live on their own facade (see Reports), so the call is client.Reports.Status.Poll(...). BestSMS suggests giving up if a message still has no result after 6 hours, and polling no more often than once a second.

import { ErrorResponseDTO } from 'bestsms';

// MessageID as returned by SendMessage
const status = await client.Reports.Status.Poll({ MessageID: "[Message ID]" });

if (status instanceof ErrorResponseDTO) {
    console.error(status.ErrorMessage.join("; "));
} else {
    console.log(`JobStatus: ${status.JobStatus}`);
    for (const recipient of status.Recipients) {
        console.log(` -> ${recipient.Destination}: ${recipient.Status} (${recipient.Result})`);
    }
}

You may also pass RecordsPerPage (default 100) and Page (default 1) to move through the Recipients of a large job. The SDK rejects a RecordsPerPage outside 1–999 and a Page below 1 with Result: "Error". The API specification does not document paging parameters for this endpoint, so look at TotalRecords and PageCount in the response to see whether paging took effect. Passing an empty MessageID also gives an "Error" result, as the note on required IDs in Getting Started describes.

Each recipient returned by Status.Poll(...) carries its replies in SMSReplies when the program runs, yet the declared type of Recipients leaves that property out. The next sample shows one way to get typed access. Otherwise use Reports.SMSReply.Poll(...), shown further down, whose types already include it.

import { ErrorResponseDTO } from 'bestsms';
import type { SMSReplyApiResponseDTO } from 'bestsms';

type ReplyRecipient = SMSReplyApiResponseDTO['Recipients'][number];

const status = await client.Reports.Status.Poll({ MessageID: "[Message ID]" });

if (!(status instanceof ErrorResponseDTO)) {
    for (const recipient of status.Recipients) {
        for (const reply of (recipient as ReplyRecipient).SMSReplies) {
            console.log(`    reply: ${reply.MessageText}`);
        }
    }
}

Poll for inbound SMS

This collects the replies that arrived during the last TimePeriod minutes (1–1440, default 1440) and is the polling alternative to a webhook. To use a calendar window instead, give both DateFrom and DateTo as YYYY-MM-DDThh:mm in your local time, covering at most 7 days; once both are present, TimePeriod is ignored. Giving only one of the two dates, or a TimePeriod outside its range, resolves to an ErrorResponseDTO and never throws. RecordsPerPage and Page work as they do for status (default 100 and 1), and one call returns just the page you asked for. Polling more than once a second risks hitting the rate limit.

import { ErrorResponseDTO } from 'bestsms';

const received = await client.Reports.SMSReceived.Poll({
    TimePeriod: 1440 // look back this many minutes
});

if (!(received instanceof ErrorResponseDTO)) {
    for (const message of received.Messages) {
        console.log(`From ${message.From}: ${message.MessageText}`);
    }
}

Poll for replies to a specific message

client.Reports.SMSReply.Poll(...) requests the same data as Status.Poll(...), since both read GET /sms/{MessageID}. Its response type declares SMSReplies on every recipient, so no cast is needed.

import { ErrorResponseDTO } from 'bestsms';

const replies = await client.Reports.SMSReply.Poll({ MessageID: "[Message ID]" });

if (!(replies instanceof ErrorResponseDTO)) {
    for (const recipient of replies.Recipients) {
        for (const reply of recipient.SMSReplies) {
            console.log(`${recipient.Destination} replied: ${reply.MessageText}`);
        }
    }
}

Actions

A message that is still waiting to go out can be rescheduled or aborted. Both live on the client.Actions facade and are described in Actions; each takes an object holding the MessageID.

Reschedule

Give a delayed message a new SendTime, written YYYY-MM-DDThh:mm (or YYYY-MM-DD hh:mm). It is interpreted in the timezone the message already has.

import { ErrorResponseDTO } from 'bestsms';

const rescheduled = await client.Actions.Reschedule.SendRequest({
    MessageID: "[Message ID]",
    SendTime: "2026-12-31T12:00"
});

if (!(rescheduled instanceof ErrorResponseDTO)) {
    console.log(`Action: ${rescheduled.Action}, Status: ${rescheduled.Status}`);
}

Abort

Cancels a delayed message so that it is never sent.

await client.Actions.Abort.SendRequest({ MessageID: "[Message ID]" });

Response

The success types are exported from the package as types, for example import type { StatusApiResponseDTO } from 'bestsms'. ErrorResponseDTO is exported as a class, which is what lets instanceof work.

SendMessage(...) response (MessagingApiSuccessResponseDTO)

A success only tells you BestSMS accepted the request. It does not confirm delivery, so use status polling or the send-result webhook for that.

Error response (ErrorResponseDTO)

Status.Poll(...)/SMSReply.Poll(...) response (StatusApiResponseDTO/SMSReplyApiResponseDTO)

Both types hold the same fields. They differ only in how Recipients is typed.

Recipient object (each entry in Recipients)

SMSReplies object (each entry in Recipients[].SMSReplies)

SMSReceived.Poll(...) response (SMSReceivedApiResponseDTO)

Message object (each entry in Messages)

Reschedule/Abort response (ActionApiResponseDTO)

Reports

All polling lives under client.Reports. The SMS channel object (client.Messaging.SMS) is only for sending, and has no Status(...), Reply(...) or Received(...) method. Whenever you need to know how a message went, or want to fetch inbound texts, come here.

Three properties are available on client.Reports: .Status, .SMSReply and .SMSReceived. Each is one long-lived request object, and its internal state is cleared after every Poll(...), which means you can call the same property again and again with different arguments.

BestSMS asks that you poll no more than once per second. If a message still has no result after 6 hours, stop polling for it. Where you can, use Webhooks, which push the same information to you and are more efficient than polling.

Methods

Every method resolves to an ErrorResponseDTO when something goes wrong. These reports cover SMS only, so none of them has a Channel argument. RecordsPerPage defaults to 100 and Page to 1; they are sent as the recordsPerPage and page query parameters. The SDK itself accepts a RecordsPerPage from 1 to 999 and a Page of at least 1, and rejects anything else before sending, but the REST API definition documents 5 to 100 for list calls, so staying inside that range is the safer habit. A call returns only the page you asked for: check PageCount and TotalRecords and request further pages yourself.

MessageID is mandatory for Status.Poll and SMSReply.Poll. When it is missing or empty, the Promise resolves to an ErrorResponseDTO ("Missing MessageID") and no request goes out. SMSReceived.Poll takes no MessageID.

Code Samples

Poll for message status

const response = await client.Reports.Status.Poll({ MessageID: 'ID123456' });

if (response.Result === 'Success') {
    console.log(`JobStatus: ${response.JobStatus}`);
    for (const recipient of response.Recipients) {
        console.log(` -> ${recipient.Destination}: ${recipient.Status} (${recipient.Result})`);
    }
}

Read every page of a large job

import { ErrorResponseDTO } from 'bestsms';

let page = 1;
let pageCount = 1;

do {
    const response = await client.Reports.Status.Poll({
        MessageID: 'ID123456',
        RecordsPerPage: 100,
        Page: page,
    });

    if (response instanceof ErrorResponseDTO) {
        console.error(`Page ${page} failed:`, response.ErrorMessage);
        break;
    }

    pageCount = response.PageCount ?? 1;
    for (const recipient of response.Recipients) {
        console.log(`${recipient.Destination}: ${recipient.Status}`);
    }
    page++;
} while (page <= pageCount);

Poll for inbound SMS

This call lists SMS received during a period. It also returns texts that answer no particular outbound MessageID, so it can stand in for a webhook. Pass DateFrom and DateTo together, written as {date}T{time} in the API user's local time, spanning no more than 7 days. Leave them out and TimePeriod applies instead: a number of minutes from 1 to 1440, defaulting to 1440, which is the last 24 hours.

• When both dates are present they are used and TimePeriod is not sent.
• Supplying only one of the two dates resolves to an error ("DateFrom and DateTo must be supplied together").
• A TimePeriod outside 1–1440 resolves to an error ("TimePeriod must be between 1 and 1440 minutes") and does not reach the server.
• Each date needs a leading YYYY-MM-DD part and must parse as a date-time. It is sent unchanged. The 7-day limit is not checked in the SDK, so a longer range is left for the API to refuse.

const response = await client.Reports.SMSReceived.Poll({
    DateFrom: '2026-10-05T00:00:00',
    DateTo: '2026-10-12T00:00:00',
});

if (response.Result === 'Success') {
    for (const message of response.Messages) {
        console.log(`Received from ${message.From}: ${message.MessageText}`);
    }
}

For a rolling window instead, such as every text received in the past hour:

const recent = await client.Reports.SMSReceived.Poll({ TimePeriod: 60 });

Poll for replies to one message

SMSReply.Poll(...) sends exactly the same request as Status.Poll(...) (GET /sms/{MessageID}), and so the result has the same fields. What differs is the declared type: its Recipients are typed with a SMSReplies array, which Status.Poll does not expose to the compiler. Replies show up in Recipients[].SMSReplies. Use SMSReply.Poll whenever your code reads replies, so that TypeScript knows about them.

const response = await client.Reports.SMSReply.Poll({ MessageID: 'ID123456' });

if (response.Result === 'Success') {
    for (const recipient of response.Recipients) {
        for (const reply of recipient.SMSReplies) {
            console.log(`${recipient.Destination} replied: ${reply.MessageText}`);
        }
    }
}

Response

Each response has a Result field. Check response.Result === "Success" (or use instanceof ErrorResponseDTO) before reading any other field. Details are in Getting Started.

Status.Poll(...) and SMSReply.Poll(...)

Both resolve to an object with these fields. Only the type of Recipients differs, as explained in the recipient tables below.

Every entry in Recipients has these fields (none is guaranteed to be present):

SMSReplyRecipientDTO adds one field to the list above:

Fields of each reply (SMSReplyRecipientSMSReplyDTO):

SMSReceived.Poll(...)

The result is an SMSReceivedApiResponseDTO:

Fields of each message (SMSReceivedDTO):

Failure

Actions

client.Actions changes an SMS that has already been submitted but has not yet gone out. Identify the message by its MessageID and choose what to do with it. The SMS channel object (client.Messaging.SMS) only sends, so client.Actions is the one place these calls exist.

Two properties are available, .Abort and .Reschedule. Each is one long-lived request object whose internal state is cleared after every SendRequest(...), so reusing it for several independent calls is safe.

Methods

Both resolve to an ActionApiResponseDTO or, on failure, an ErrorResponseDTO. Only these two actions exist in the v3.00 library. Resubmit from the 2.x package is no longer offered, and there is no Channel argument, since every action targets SMS.

Validation happens in the SDK before anything is sent, and a failure resolves to an ErrorResponseDTO with Result: "Error" instead of throwing:

• MessageID is required for both actions ("Missing MessageID").
• SendTime is required for Reschedule ("Missing SendTime"). The value needs a leading YYYY-MM-DD part and must parse as a date-time; if it does not, the error reads "Unable to parse SendTime. Use YYYY-MM-DDThh:mm or YYYY-MM-DD hh:mm format."

A valid SendTime is passed on exactly as written, and it is read in the message's existing Timezone (for example AUS Eastern). The SDK does not check that the time is in the future or that the message is actually still delayed. Those decisions are left to the API, whose answer comes back as an ordinary error response.

Code Samples

Abort a delayed message

const response = await client.Actions.Abort.SendRequest({ MessageID: 'ID123456' });

if (response.Result === 'Success') {
    console.log(`Action: ${response.Action}, Status: ${response.Status}`);
}

Reschedule a delayed message

const response = await client.Actions.Reschedule.SendRequest({
    MessageID: 'ID123456',
    SendTime: '2026-11-03T09:00',
});

if (response.Result === 'Success') {
    console.log(`Action: ${response.Action}, Status: ${response.Status}`);
}

Handling a failure

A rejected action never throws. Branch on instanceof ErrorResponseDTO and read ErrorMessage, which is always an array:

import { ErrorResponseDTO } from 'bestsms';

const response = await client.Actions.Reschedule.SendRequest({
    MessageID: 'ID123456',
    SendTime: 'next Tuesday',
});

if (response instanceof ErrorResponseDTO) {
    console.log(response.ErrorMessage);
    // ["Unable to parse SendTime. Use YYYY-MM-DDThh:mm or YYYY-MM-DD hh:mm format."]
} else {
    console.log(`${response.MessageID}: ${response.ActionResult}`);
}

Response

Each response has a Result field. Check response.Result === "Success" (or use instanceof ErrorResponseDTO) before reading any other field. Details are in Getting Started.

Success

Either action returns an ActionApiResponseDTO. The reply counts as a success when the HTTP status is 200, or when its ActionResult is "Success".

Failure

Comes back when SDK validation stops the call (Result: "Error"), when the API rejects it (typically "Failed", "Unauthorized" or "RecordNotFound"), or when the request cannot be completed.

Inbound Webhooks

A webhook is BestSMS calling you. When a message finishes sending, or when a customer texts you back, BestSMS posts the details to a URL on your server within moments. Your code no longer has to run Reports.Status.Poll(...) or Reports.SMSReceived.Poll(...) on a schedule, and delivery receipts and replies arrive without the constant background requests that polling needs.

"Inbound" is from your application's point of view: BestSMS sends an HTTP POST to a server you run. For one message, name that server with WebhookCallbackURL and WebhookCallbackFormat on SendMessage(...) (see SMS). Alternatively rely on your User's default webhook settings. The SDK does not receive anything itself. What it ships for this feature is a small kit for your own endpoint: the parseWebhook(...) and isInboundSMSWebhook(...) functions plus the types ISendResultWebhook, IInboundSMSWebhook, BestSMSWebhook and IWebhookHeaders, all exported from bestsms.

Security note: parseWebhook(...) does not authenticate anything. It only confirms that the body is a JSON object with a recognised Type. Every request carries an Authorization header plus X-Sender and X-Timestamp headers, and the payload itself names the sender in Sender and APIKey. Check these in your own handler before you act on a payload, otherwise anyone who learns your callback URL can post a forged event to it. The Configuring API Webhooks article explains how webhook authentication is set up on the BestSMS side. Whatever secret you configure there is what your handler should compare the Authorization header against.

All examples here parse a JSON body, so choose WebhookCallbackFormat.JSON when you send (or in your User's webhook settings). A callback in XML, POST or GET format would need parsing code of your own, because parseWebhook(...) reads JSON only. Events can reach you out of order, so decide by the contents of each event and not by when it arrived.

WebhookCallbackFormat

Import the WebhookCallbackFormat enum from bestsms to select how the callback body is encoded. Passing WebhookCallbackURL without a valid format makes SendMessage(...) resolve to an ErrorResponseDTO (Result: "Error") before any request is made.

Request Headers

IWebhookHeaders describes the headers BestSMS adds to every webhook call. All three are optional in the type, because the SDK cannot guarantee what an arbitrary request carries.

Payload Fields

BestSMS posts two kinds of event. The send result (ISendResultWebhook, Type "SMS") reports how one destination ended up. The inbound SMS (IInboundSMSWebhook, Type "SMSReply" or "SMSInbound") carries a text someone sent you. The two share most field names; the table notes where they part ways. Both types extend one common base and every field other than Type is optional in the typings. BestSMSWebhook is the union of the two.

parseWebhook and isInboundSMSWebhook

parseWebhook(body: string | object): BestSMSWebhook accepts the raw body text or an object your framework has already decoded. It throws an Error with a descriptive message when the text is not valid JSON, when the value is not a JSON object (an array, a string or null, for instance), or when Type is missing or not one of the three known values. For anything else it hands back the very same object, typed as BestSMSWebhook. It copies nothing, converts nothing and never checks the other fields, which is why code that depends on them should still be defensive. Keys the typings don't list simply stay on the object, so a field added by BestSMS later cannot make parsing fail.

isInboundSMSWebhook(webhook) is a type guard. It returns true for "SMSReply" and "SMSInbound" payloads and narrows the value to IInboundSMSWebhook. In its else branch the value is an ISendResultWebhook.

Code Samples

Parse and branch on the event type

In this sample rawBody stands for the body text of the request, however your server hands it over.

import { parseWebhook, isInboundSMSWebhook } from 'bestsms';

const webhook = parseWebhook(rawBody);

if (isInboundSMSWebhook(webhook)) {
    // Type is "SMSReply" (matched an outbound MessageID) or "SMSInbound"
    console.log(`${webhook.Type} from ${webhook.Destination}: ${webhook.Message}`);
} else {
    // Type is "SMS": the outcome for one destination
    console.log(`${webhook.MessageID} to ${webhook.Destination}: ${webhook.Status} (${webhook.Result})`);
}

Node http receiver

A full receiver written against the standard-library http module. It insists on a POST, checks the Authorization header, limits the body size, and then lets parseWebhook(...) sort send results from inbound texts. Put the secret you configured for the webhook in the BESTSMS_WEBHOOK_SECRET environment variable. It is compared with the whole raw header, so include any scheme prefix, such as Bearer , that BestSMS sends. Both values are hashed first, so the comparison takes the same time whatever the header contains and timingSafeEqual never sees two buffers of different lengths.

import { createServer } from 'http';
import { createHash, timingSafeEqual } from 'crypto';
import { parseWebhook, isInboundSMSWebhook } from 'bestsms';

const expectedAuth = process.env.BESTSMS_WEBHOOK_SECRET ?? '';
const MAX_BODY_BYTES = 64 * 1024; // webhook payloads are small

const digest = (value: string) => createHash('sha256').update(value).digest();

const isAuthorized = (header: string | undefined): boolean =>
    expectedAuth !== '' && header !== undefined && timingSafeEqual(digest(header), digest(expectedAuth));

const server = createServer((req, res) => {
    if (req.method !== 'POST') {
        res.writeHead(405).end();
        return;
    }
    if (!isAuthorized(req.headers['authorization'])) {
        res.writeHead(401).end();
        return;
    }

    let rawBody = '';
    let tooLarge = false;
    req.setEncoding('utf8');
    req.on('data', (chunk: string) => {
        if (tooLarge) return;
        rawBody += chunk;
        if (Buffer.byteLength(rawBody) > MAX_BODY_BYTES) {
            tooLarge = true;
            res.writeHead(413, { Connection: 'close' });
            res.end(() => req.destroy());
        }
    });
    req.on('end', () => {
        if (tooLarge) return;
        try {
            const webhook = parseWebhook(rawBody);

            if (isInboundSMSWebhook(webhook)) {
                console.log(`${webhook.Type} from ${webhook.Destination}: ${webhook.Message}`);
            } else {
                console.log(`${webhook.MessageID} is now ${webhook.Status} (${webhook.Result})`);
            }

            res.writeHead(200).end();
        } catch (err) {
            console.error('Rejected webhook:', (err as Error).message);
            res.writeHead(400).end();
        }
    });
});

server.listen(3000);

Reply 200 as soon as you have accepted an event. BestSMS treats any other answer as a rejection and tries the same webhook again every 5 minutes for 24 hours, so hand slow work to a queue instead of holding the response open.

Express receiver

The SDK has no dependency on a web framework, and any one that gives you the decoded JSON body will do. This Express route passes req.body straight to parseWebhook(...), which accepts objects as well as strings. The isAuthorized helper is the one from the Node sample above.

import express from 'express';
import { createHash, timingSafeEqual } from 'crypto';
import { parseWebhook, isInboundSMSWebhook } from 'bestsms';

const expectedAuth = process.env.BESTSMS_WEBHOOK_SECRET ?? '';
const digest = (value: string) => createHash('sha256').update(value).digest();
const isAuthorized = (header: string | undefined): boolean =>
    expectedAuth !== '' && header !== undefined && timingSafeEqual(digest(header), digest(expectedAuth));

const app = express();

app.post('/webhooks/bestsms', express.json({ limit: '64kb' }), (req, res) => {
    if (!isAuthorized(req.headers.authorization)) {
        res.sendStatus(401);
        return;
    }

    try {
        const webhook = parseWebhook(req.body);

        if (isInboundSMSWebhook(webhook)) {
            console.log(`${webhook.Destination} replied: ${webhook.Message}`);
        } else {
            console.log(`Message ${webhook.MessageID} status: ${webhook.Status}`);
        }
        res.sendStatus(200);
    } catch (err) {
        console.error('Rejected webhook:', (err as Error).message);
        res.sendStatus(400);
    }
});

app.listen(3000);

Note on Price: the typings declare it as string | null, matching the API specification (a text of up to 10 characters, null when there is no cost). Yet a TypeScript type is erased at runtime and parseWebhook(...) neither validates nor converts values. If a callback carries Price as a JSON number (the specification's own example is written as the bare number 0.10), your code receives a number whatever the declaration says. Code that assumes a string, such as calling .trim() on it, could therefore throw. When you need one consistent type, convert it yourself, for example webhook.Price == null ? null : Number(webhook.Price).

Addressbook

The Addressbook lets you keep recipient data in the one place, so your integration stays small and your SMS messages can be personalised. You can look after contacts, groups and the memberships between them, mirror records from a CRM, payroll system or spreadsheet, and reach a whole list of people through a single GroupID. Sending by ContactID or GroupID also shrinks each request, because the full recipient details don't have to travel with every send. Those same IDs work as the ContactID and GroupID values on a destination in SMS. A contact's FirstName, Company and Custom1–Custom4 values can be placed in a message body as merge tags such as [[FirstName]]. Whatever you create through this library also shows up in the BestSMS Dashboard. A group holds no custom fields of its own, so any merge values are read from each member contact.

client.Addressbook has four members: .Contact, .Group, .ContactGroup and .GroupContact. The layout is flat. Membership is handled by ContactGroup and GroupContact, which sit next to the other two on client.Addressbook, so there is no chaining from Contact or Group into them. Each member is created once with the client and reused. Every method takes a single options object (which you may omit when none of its fields are required) and gives back a Promise, and the same method may be called repeatedly, even concurrently, because each call copies its options before anything is sent.

A method resolves to either a success object (such as ContactApiResponseDTO) or an ErrorResponseDTO. Problems found before sending, such as a missing ID or a malformed email address, do not throw. They come back as an ErrorResponseDTO with Result set to "Error" and no HTTP request is made. The same applies to network failures and replies the library cannot parse. Narrow the result with instanceof ErrorResponseDTO; Getting Started covers the wider picture. The one deliberate exception is the BestSMS constructor, which throws when no Auth Token can be found.

Contact

Fields

None of these fields is mandatory, and each one is typed as a plain string. There is no enum or union type for ViewBy, EditBy, AccessControl or Title, and the library does not check them against the lists above, so the server decides whether a value is acceptable. The options object also accepts a Timezone string, but the API specification only returns Timezone on a contact and does not list it as something you can send, so leave it out. This library has no DirectPhone field: the phone fields stop at MainPhone and AltPhone1–AltPhone8.

Create

Pass the fields in one object. All of them are optional, so a contact can be created with only a name or only a number. The stored record comes back under .Contact, and it is typed as optional, which is why the samples read it with ?..

import { BestSMS, ErrorResponseDTO } from 'bestsms';

const client = new BestSMS({ AuthToken: process.env.BESTSMS_AUTH_TOKEN });

const created = await client.Addressbook.Contact.Create({
    Attention: 'Jane Citizen',
    FirstName: 'Jane',
    LastName: 'Citizen',
    MobilePhone: '+61491570006',
    EmailAddress: '[email protected]',
    MainPhone: '+61291570011',
    Company: 'Harbour Plumbing Pty Ltd',
});

if (created instanceof ErrorResponseDTO) {
    console.error(created.Result, created.ErrorMessage.join('; '));
} else {
    console.log(`Created ContactID=${created.Contact?.ContactID}`);
}

Detail

Fetch one contact by ContactID. The ID goes inside an object, and a bare string is not accepted. If the ID is missing or empty, the result is an ErrorResponseDTO with the message Missing ContactID and nothing is sent. A successful Detail result also carries Groups, a list of the GroupID values the contact belongs to.

import { ErrorResponseDTO } from 'bestsms';

const details = await client.Addressbook.Contact.Detail({ ContactID: contactID });

if (!(details instanceof ErrorResponseDTO)) {
    const contact = details.Contact;
    console.log(`${contact?.FirstName} ${contact?.LastName}, ${contact?.EmailAddress}`);
    console.log(`Member of ${details.Groups?.length ?? 0} group(s)`);
}

Update and Delete

Both calls need the ContactID in the options object. A previous result can't stand in for the ID, so read it from result.Contact?.ContactID first. Update sends only the fields you include and leaves the rest of the record alone, and the ContactID is used in the URL and is not repeated in the request body. Delete returns the details of the contact it removed.

import { ErrorResponseDTO } from 'bestsms';

const updated = await client.Addressbook.Contact.Update({
    ContactID: contactID,
    Position: 'Operations Manager',
    Custom1: 'Gold plan',
});

const removed = await client.Addressbook.Contact.Delete({ ContactID: contactID });

if (removed instanceof ErrorResponseDTO) {
    console.error(removed.Result, removed.ErrorMessage);
}

Search and List

Search filters on any combination of EmailAddress (matched exactly) and MobilePhone, MainPhone, Attention, FirstName, LastName and Company (matched partially). List returns every contact you hold, one page at a time. Both calls start from RecordsPerPage: 100 and Page: 1 when you leave those out, and each fetches just the page you ask for. Nothing is walked automatically, so loop over PageCount yourself when you need the lot.

Page size: the API specification allows RecordsPerPage from 5 to 100 for contact and group lists, and the default of 100 is the top of that range. The library does not enforce the range for Addressbook calls, so a value outside it is a matter for the server to reject.

import { ErrorResponseDTO } from 'bestsms';

const found = await client.Addressbook.Contact.Search({
    FirstName: 'Alice',
    Company: 'Harbour Plumbing',
    RecordsPerPage: 50,
    Page: 1,
});

if (!(found instanceof ErrorResponseDTO)) {
    for (const contact of found.Contacts) {
        console.log(`${contact.ContactID}: ${contact.FirstName} ${contact.LastName}`);
    }
}

// Walk every page of the full contact list
let pageNumber = 1;
let pageCount = 1;

do {
    const page = await client.Addressbook.Contact.List({ RecordsPerPage: 100, Page: pageNumber });

    if (page instanceof ErrorResponseDTO) {
        console.error(page.Result, page.ErrorMessage);
        break;
    }

    for (const contact of page.Contacts) {
        console.log(`${contact.ContactID}: ${contact.FirstName} ${contact.LastName}`);
    }

    pageCount = page.PageCount ?? 1;
    pageNumber++;
} while (pageNumber <= pageCount);

Group

Fields

Create

Groups follow the same single-object style as contacts. If GroupName is empty, the result is an ErrorResponseDTO with the message Missing GroupName. You can't choose the GroupID or the GroupCode, because the server generates both and returns them on .Group.

import { ErrorResponseDTO } from 'bestsms';

const group = await client.Addressbook.Group.Create({
    GroupName: 'Melbourne Customers',
    SubAccount: 'SALES',
    ViewEditBy: 'SubAccount',
});

if (!(group instanceof ErrorResponseDTO)) {
    console.log(`Created GroupID=${group.Group?.GroupID}, GroupCode=${group.Group?.GroupCode}`);
}

Detail, Update, Delete, and List

These work as they do for contacts: fetch one group, rename it, remove it, or step through all of them. Detail, Update and Delete need a GroupID in the options object, and a missing one resolves to Missing GroupID or GroupCode. The library will also take a GroupCode in its place and put it in the URL, but the API specification only defines paths by GroupID, so use the ID. List starts from RecordsPerPage: 100 and Page: 1.

import { ErrorResponseDTO } from 'bestsms';

const details = await client.Addressbook.Group.Detail({ GroupID: groupID });

await client.Addressbook.Group.Update({ GroupID: groupID, GroupName: 'Sydney Customers' });

await client.Addressbook.Group.Delete({ GroupID: groupID });

const groups = await client.Addressbook.Group.List({ RecordsPerPage: 100, Page: 1 });

if (!(groups instanceof ErrorResponseDTO)) {
    for (const g of groups.Groups ?? []) {
        console.log(`${g.GroupID}: ${g.GroupName}`);
    }
}

Contact ↔ Group relationships

ContactGroup approaches membership from the contact's side and GroupContact from the group's side, and both read and change the same underlying data. Each has four methods: List, Create, Delete and Detail. They are named Create and Delete, not Add and Remove, and every one takes an options object. ContactGroup.Create and GroupContact.Create send the same request, and so do the two Delete methods, so choose whichever reads better where you call it.

For Create, Delete and Detail you can give either the ID strings or the model objects from an earlier result. Passing Contact: result.Contact and Group: result.Group works because the library copies the ID out of each object for you. GroupContact.List will unwrap a Group object too. ContactGroup.List is the exception. Its options type has a Contact field, but the code only reads ContactID, so a call with just a Contact object compiles and then resolves to Missing ContactID. Always pass the ID string to that one method.

Note: Detail on both classes is a dedicated request for the one contact–group pair. It does not fetch a list page and search through it, and it takes no paging options. That endpoint, GET /addressbook/contact/{ContactID}/group/{GroupID}, is missing from the published API specification, which defines only DELETE for that path, and the library has not been run against a live BestSMS server. If you need to know whether a contact is in a group, ContactGroup.List or GroupContact.List follows the documented endpoints. In the same way, GroupContact.Create, Delete and Detail are not separately described in the specification; they reuse the contact-side paths above.

On paging, the specification gives the two relation lists a Pagination block in their replies but declares no page or recordsPerPage query parameters for them. The library sends both anyway, using the usual defaults of 100 and 1, so you can pass RecordsPerPage and Page on ContactGroup.List and GroupContact.List. Whether the server honours them is unverified.

import { ErrorResponseDTO } from 'bestsms';

// The groups a contact belongs to
const memberships = await client.Addressbook.ContactGroup.List({ ContactID: contactID });

if (!(memberships instanceof ErrorResponseDTO)) {
    for (const g of memberships.Groups ?? []) {
        console.log(`${g.GroupID}: ${g.GroupName}`);
    }
}

// Put a contact into a group, working from the contact
const added = await client.Addressbook.ContactGroup.Create({ ContactID: contactID, GroupID: groupID });

if (!(added instanceof ErrorResponseDTO)) {
    console.log(`Added to group: ${added.Group?.GroupName}`);
}

// Check one contact-group pair (not in the published specification, see the note above)
const relation = await client.Addressbook.ContactGroup.Detail({ ContactID: contactID, GroupID: groupID });

// Take a contact out of a group
await client.Addressbook.ContactGroup.Delete({ ContactID: contactID, GroupID: groupID });

// The contacts that sit in a group
const members = await client.Addressbook.GroupContact.List({ GroupID: groupID, RecordsPerPage: 100, Page: 1 });

if (!(members instanceof ErrorResponseDTO)) {
    for (const contact of members.Contacts ?? []) {
        console.log(`${contact.FirstName} ${contact.LastName}`);
    }
}

// Put a contact into a group, working from the group (same request as ContactGroup.Create)
const groupAdded = await client.Addressbook.GroupContact.Create({ GroupID: groupID, ContactID: contactID });

if (!(groupAdded instanceof ErrorResponseDTO)) {
    const contact = groupAdded.Contact;
    console.log(`Added ${contact?.FirstName} ${contact?.LastName} to the group`);
}

// Take a contact out of a group, working from the group
await client.Addressbook.GroupContact.Delete({ GroupID: groupID, ContactID: contactID });

// Check one group-contact pair
const groupRelation = await client.Addressbook.GroupContact.Detail({ GroupID: groupID, ContactID: contactID });

// Model objects from earlier results can stand in for the IDs
// (details comes from Contact.Detail and group from Group.Create above)
if (!(details instanceof ErrorResponseDTO) && !(group instanceof ErrorResponseDTO)) {
    await client.Addressbook.ContactGroup.Create({
        Contact: details.Contact,
        Group: group.Group,
    });
}

Response

A success object always has Result equal to "Success". An ErrorResponseDTO has a Result of "Error" (caught by the library before sending, or a network or parsing failure), "Failed" or "Unauthorized" (reported by the API), or another status string the API returns, such as "RecordNotFound" for a 404. Its ErrorMessage is always a string[], even when the API sent a single string. See Getting Started. List results also carry TotalRecords, RecordsPerPage, PageCount and Page (all number) for paging. In the API's JSON body the contact and group fields are not nested. The library gathers them into a typed .Contact or .Group object, and that is the property to read.

Contact.Create(...)/Detail(...)/Update(...)/Delete(...) response

Contact.Search(...)/List(...) response

Group.Create(...)/Detail(...)/Update(...)/Delete(...) response

Group.List(...) response

ContactGroup.List(...) response

GroupContact.List(...) response

ContactGroup.Create(...)/Delete(...)/Detail(...) response

GroupContact.Create(...)/Delete(...)/Detail(...) response

These last two results have no paging fields, which sets them apart from the List results above. Each describes a single contact–group pairing.

OptOut

OptOut is the part of the library that keeps your suppression list, meaning the people who have told you to stop messaging them, which supports your obligations under Australian spam rules. An entry applies to one message type (DestType) and can optionally be limited to a single SubAccount and Department. You reach it straight from client.OptOut, because this library has no Configuration object in between.

Sending to an opted-out destination is not rejected. The API still accepts the request, but it holds back delivery and reports the result as "Destination is blacklisted", so you end up with an audit trail instead of an error. To export the whole suppression list for an audit or to sync it with your own CRM, use List, described below.

DestType is an ordinary string. There is no enum or union type for it. The only message type the API supports is "SMS". The library checks just that the value is not empty, and a missing one resolves to an ErrorResponseDTO with Result "Error" and the message Missing DestType. Any other value is passed through for the server to refuse, and the API specification shows that refusal as a 400 reply with Result "Failed" and the message Unsupported DestType - Supported DestType: SMS.. Every method resolves to a success object or an ErrorResponseDTO and none of them throw for validation problems, as Getting Started explains.

Fields

Code samples

Create a single OptOut entry

Use this to block later sends to one destination. DestType is required, and so is exactly one of Destination or ContactID. Create checks all of this before sending, and the messages it can resolve to are Missing DestType, Missing Destination or ContactID and Use either Destination or ContactID, not both.

import { BestSMS, ErrorResponseDTO } from 'bestsms';

const client = new BestSMS({ AuthToken: process.env.BESTSMS_AUTH_TOKEN });

const created = await client.OptOut.Create({
    DestType: 'SMS',
    Destination: '+61491570006',
    Notes: 'Asked to be removed by phone',
});

if (created instanceof ErrorResponseDTO) {
    console.error(created.Result, created.ErrorMessage.join('; '));
} else {
    console.log(`Created OptOut ID=${created.ID}`);
}

Opt out an addressbook contact

A contact from the Addressbook can be blocked by its ContactID, with no raw destination needed. Supply ContactID or Destination, never both.

const contactOptOut = await client.OptOut.Create({
    DestType: 'SMS',
    ContactID: contactID,
    SubAccount: 'SALES',
});

Opt out several destinations at once

The method is called Batch. Its options are DestType, Destination, Destinations (string[]), ContactID, ContactIDs (string[]), SubAccount and Department. DestType is required, along with at least one of Destination, Destinations, ContactID or ContactIDs, otherwise the result is Missing Destination, Destinations, ContactID or ContactIDs. One request may mix those four, and unlike Create it does not stop you from combining destinations with contacts. SubAccount and Department narrow the scope just as they do for a single entry. Batch has no StopMessage or Notes option.

import { ErrorResponseDTO } from 'bestsms';

const batch = await client.OptOut.Batch({
    DestType: 'SMS',
    Destinations: ['+61491570006', '+61491570008'],
    ContactIDs: [contactID],
    Department: 'Support',
});

if (!(batch instanceof ErrorResponseDTO)) {
    console.log(`Batch opt-out created: ID=${batch.ID}`);
}

Note: Batch resolves to a single result with one ID, shaped like the results of Create and Detail. It is not an array with an item for each destination you submitted. To see the individual entries a batch produced, query them with List afterwards, filtering on TimePeriod, DestType or ContactID. List has no way to filter by destination, so match the entries against the numbers you submitted in your own code.

Update

Update changes an existing entry. It needs the OptOutID in the options object, because a response object can't be passed in its place, and the message Missing OptOutID comes back if it is empty. The OptOutID is put in the URL, and the remaining fields you pass form the request body, so anything you leave out is not sent. Unlike Create, Update makes no demands on DestType or the destination fields in the library. Be aware that the API specification reuses one schema for create and update and lists DestType as required in it. If the server turns down an update that has no DestType, include it. This behaviour has not been checked against a live server.

const updated = await client.OptOut.Update({
    OptOutID: optOutID,
    DestType: 'SMS',
    Notes: 'Verified during a second call',
});

Detail, Delete, and List

Use these to read one entry, remove an entry, or step through the suppression list. Detail and Delete each take an object holding the OptOutID (a string value, not a bare argument) and resolve to Missing OptOutID when it is empty. Delete returns the details of the entry it removed. The fetch method is spelled Detail here and on every Addressbook class.

import { ErrorResponseDTO } from 'bestsms';

const detail = await client.OptOut.Detail({ OptOutID: optOutID });

const removed = await client.OptOut.Delete({ OptOutID: optOutID });

const list = await client.OptOut.List({ DestType: 'SMS', TimePeriod: 30 });

if (!(list instanceof ErrorResponseDTO)) {
    for (const entry of list.OptOuts) {
        console.log(`${entry.Destination}, ${entry.DestType}`);
    }
}

List accepts DestType, TimePeriod (a whole number of days, so entries created in the last x days), ContactID, RecordsPerPage and Page, and every one of them is optional. RecordsPerPage starts at 100 and Page at 1. Only the page you request is returned; the library never fetches the remaining pages for you, so use PageCount to loop when you need all of them. The API documents a poll rate of no more than one call per second for this endpoint.

Page size: the API specification allows RecordsPerPage from 5 to 1000 for OptOut, a wider range than the 5 to 100 that applies to the Addressbook lists. The library does not check the bounds, so a value outside that range is refused by the server and not by the library.

Response

A success object has Result equal to "Success". Anything else arrives as an ErrorResponseDTO with Result set to "Error", "Failed", "Unauthorized" or another status string from the API such as "RecordNotFound", plus an ErrorMessage that is always a string[]. Narrow with instanceof ErrorResponseDTO before reading other fields; Getting Started has more.

Create(...)/Detail(...)/Update(...)/Delete(...)/Batch(...) response

The fields sit directly on the result, with no nested object, which differs from how Addressbook results wrap a Contact or Group. The result of Batch(...) has this same shape; see the note above. It is not a list of the destinations you submitted.

List(...) response