Send an SMS with Node.js

Send one message to a simulated recipient, then keep its ID for delivery tracking.

1. Prepare the workspace

Prepare an owned US-eligible SMS number, enable the US destination, complete its required registration and fund the workspace. The test recipient +15005550006 simulates delivery and is billed at the normal destination rate; it does not reach a handset. Follow workspace setup before running this sample.

2. Install and configure

Use Node.js 20.3 or later. In a new project directory:

Exemple de code

npm init -y
npm install @messagebird/sdk tsx
export BIRD_API_KEY="YOUR_API_KEY"
export BIRD_SMS_FROM="YOUR_ELIGIBLE_US_NUMBER"

Replace the environment values with your workspace key and eligible sender number. The SDK selects the API region from the key. Run this example on your server or development machine.

3. Run the example

Save as sms.mts:

Exemple de code

import { BirdClient } from "@messagebird/sdk";

const apiKey = process.env.BIRD_API_KEY;
if (!apiKey) throw new Error("Set BIRD_API_KEY before running the sample.");
const bird = new BirdClient({ apiKey });

const from = process.env.BIRD_SMS_FROM;
if (!from) throw new Error("Set BIRD_SMS_FROM to your eligible sender.");
const message = await bird.sms.send({
  from,
  to: "+15005550006",
  text: "Your studio visit is tomorrow at 14:00.",
  category: "transactional",
  metadata: { booking: "FN-1042" },
});
console.log(message.id, message.status);

Exemple de code

npx tsx sms.mts

4. Inspect the outcome

The response prints a message ID and the accepted status. Processing and delivery happen afterward. Inspect the ID in the SMS log or use the read example in your first SMS. The simulated destination progresses through its delivery outcome without contacting a handset.

Running this script again creates another logical send. If the result of a request is uncertain, follow idempotency guidance before sending again.

Next steps

Use this operation in Next.js or Express to send and inspect messages through an application route.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptOne-way and two-way SMS Utiliser l'outilCheck your message segments Explorer la fonctionnalitéTwo-way SMS Suivre le parcours d'apprentissageBuild your first integration

Obtenir un guide d'implémentation