Send your first SMS

Send a text message to a simulated recipient with the Bird Node.js SDK, then read its delivery status. You need a Bird workspace, an API key, an eligible US sender, and balance for the send. Simulated SMS sends are billed at the normal destination rate; they do not reach a handset.

1. Prepare your workspace

Create an API key under Developers > API keys. Keep the key on your server.

Enable the United States under SMS > Destinations. Prepare an SMS-capable number that your workspace owns and that is eligible to send to the US. Complete the registration required for its sender type. An alphanumeric sender ID does not work for this destination. See sender setup and US sender requirements.

The recipient +15005550006 produces a simulated delivery outcome. It uses normal API credentials and still passes through destination and sender validation. See simulated destinations for the available outcomes and billing behavior.

2. Install and configure

Use Node.js 20.3 or later. In a new directory, install the SDK and a TypeScript runner:

Contoh kode

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 two values with your workspace key and owned sender number in E.164 format. The SDK selects the regional API host from the key prefix.

3. Send one message

Save this as send.mts:

Contoh kode

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

const apiKey = process.env.BIRD_API_KEY;
const from = process.env.BIRD_SMS_FROM;
if (!apiKey || !from) {
  throw new Error("Set BIRD_API_KEY and BIRD_SMS_FROM before running this sample.");
}

const bird = new BirdClient({ apiKey });
const message = await bird.sms.send({
  from,
  to: "+15005550006",
  text: "Your studio visit is tomorrow at 14:00. See you soon!",
  category: "transactional",
  metadata: { booking: "FN-1042" },
});

console.log(message.id, message.status);

Run it once:

Contoh kode

npx tsx send.mts

A successful call prints the message ID and accepted. The HTTP response is 202 Accepted: the message is queued. It does not establish delivery. Keep the ID for the next step; running the script again creates another logical send.

4. Read the outcome

Save this as read.mts and run it with the returned message ID:

Contoh kode

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

const apiKey = process.env.BIRD_API_KEY;
const messageId = process.argv[2];
if (!apiKey || !messageId) {
  throw new Error("Set BIRD_API_KEY and pass the message ID as the first argument.");
}

const bird = new BirdClient({ apiKey });
const message = await bird.sms.get(messageId);
console.log(message.id, message.status, message.segments);

Contoh kode

npx tsx read.mts YOUR_MESSAGE_ID

The simulated recipient produces sent and then delivered after processing. If your first read is still accepted or sent, read it again later rather than resending. For a production integration, consume signed SMS events. Deduplicate webhook retries by webhook-id and use event timestamps when observations arrive out of order.

Troubleshoot the first send

What you see	What to check
Authentication fails	Use an active key for this workspace. The SDK derives its host from the key.
SMSDestinationNotEnabled	Enable the United States in the workspace destination settings.
Sender validation fails	Use an owned US-eligible numeric sender and complete the required registration.
Accepted, then rejected	Read the message and error in the SMS log, including balance and policy checks.
No final receipt	Keep the outcome pending and inspect the message log. A missing receipt establishes neither delivery nor failure.

For request errors, read the error reference. If a response is lost, follow the idempotency guidance before starting another send.

Next steps

Use cURL, Node.js or Python for the same first send.
Send with the SMS API: product capabilities, customer proof, and pricing paths.
Sending SMS: payload fields, batches, segments, and billing.
Send endpoint reference: request and response contract.
SMS events: delivery outcomes and incoming replies.
Current SMS rates: destination rates and additional fees.

Before sending to customers, test with a handset you control, confirm the sender and content, and apply the permission and opt-out requirements for your message category and destination.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaSending your first SMS Pahami konsepnyaWhat does SMS mean?Jelajahi kemampuannyaSMS Ikuti jalur pembelajaranBuild your first integration

Coba praktiknya dan dapatkan ringkasan implementasi