Sign inGet Started

Kirim SMS pertama Anda

Kirim pesan teks ke ponsel Anda sendiri dengan Bird SMS, lalu baca kembali pesan tersebut untuk melihat apakah berhasil terkirim. Panduan cepat ini menggunakan template bawaan yang menyediakan teks, kategori, dan pengirim bersama yang dipilih Bird untuk tujuan pengiriman. Anda tidak memerlukan sender ID atau registrasi pengirim untuk ini.

Sebelum memulai, pastikan dompet organisasi Anda memiliki saldo. Pengiriman SMS mengambil dana dari dompet, dan Bird menolak pengiriman yang tidak dapat ditanggung saldonya dengan 402 WalletInsufficientBalance. Metode pembayaran dan dompet menjelaskan cara mengisi ulang.

Jika Anda belum memiliki akun, pendaftaran mandiri membuatnya dari terminal dengan CLI atau curl, tanpa browser. Jika kode Anda memanggil MessageBird API di rest.messagebird.com, API tersebut beserta kunci aksesnya terpisah dari API dalam panduan cepat ini. Beralih dari MessageBird menjelaskan hubungan antara akun-akun tersebut, dan Migrasi SMS dari Bird Connectivity Platform memetakan setiap field dari panggilan pengiriman lama.

1. Buat kunci API

Di dashboard, buka Platform tools > Kunci API dan buat kunci dengan cakupan sms:write, yang mencakup pengiriman dan pembacaan pesan. Kunci yang hanya memiliki cakupan tersebut tidak dapat mengaktifkan negara tujuan SMS, mengubah batas pengeluaran harian SMS, atau menambahkan dana: Agent controls mencantumkan batasan yang berlaku untuk kunci pengiriman. Kunci terikat pada suatu region dan berbentuk seperti bk_us1_... atau bk_eu1_.... Region pada prefiks menunjukkan host API yang harus dipanggil: https://us1.platform.bird.com atau https://eu1.platform.bird.com.

Halaman Kunci API di dashboard Bird, menampilkan daftar kunci beserta prefiks tersamar, cakupan, dan waktu terakhir digunakan

Dari terminal, bird api-keys create di Bird CLI menerbitkan kunci yang sama. Penerbitan kunci memerlukan cakupan api_keys:write, dan login CLI hanya dapat memberikan cakupan yang dimilikinya sendiri pada kunci. Login ini juga meminta sms_management:write, yang diperlukan pada langkah 2. Jika Anda membuat akun dari terminal dengan bird auth create-org, lewati baris login: kredensial yang disimpan saat pendaftaran sudah memiliki cakupan ini, dan login baru akan menggantinya dengan kredensial yang cakupannya lebih sempit.

Contoh kode
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:write

Kunci lengkap ditampilkan sekali saja, pada saat pembuatan. Salin ke tempat yang aman, lalu ekspor untuk contoh cURL:

Contoh kode
export BIRD_API_KEY="bk_us1_..."

Selama BIRD_API_KEY diatur, CLI menggunakan kunci tersebut sebagai pengganti login Anda. Kunci ini tidak dapat mengubah tujuan SMS, jadi jalankan perintah CLI pada langkah 2 di shell yang tidak mengatur variabel tersebut.

2. Aktifkan negara tujuan

Bird mengirim SMS hanya ke negara yang diaktifkan untuk workspace Anda. Pengiriman ke negara lain gagal dengan 422 SMSDestinationNotEnabled. Aktifkan negara nomor telepon Anda di SMS > Destinations. Jika sudah ditampilkan sebagai aktif, lanjutkan ke langkah 3.

Dari terminal, Bird CLI melakukan perubahan yang sama. Masukkan kode ISO dua huruf negara tersebut, misalnya US untuk Amerika Serikat. Jika login CLI Anda tidak memiliki akses ke pengaturan SMS, perintah tersebut mencetak perintah bird auth login untuk menambahkannya:

Contoh kode
bird sms destinations update --destination US=true

Agen yang terhubung ke server MCP menggunakan tool sms_destinations_update. API publik tidak memiliki operasi untuk destinasi. Perubahan bisa memerlukan waktu hingga satu menit untuk berlaku pada pengiriman.

3. Kirim pesan

Kirim template bawaan bird_otp_verification ke ponsel Anda. Template ini ditampilkan sebagai "493021 is your verification code. Do not share it." dengan nilai code yang Anda masukkan. Instal Bird SDK untuk bahasa Anda dengan mengikuti quickstart SDK.

Di tab SDK, ganti contoh kunci API, dan ganti +14155550100 dengan nomor ponsel Anda dalam format E.164. CLI menggunakan login Anda, atau BIRD_API_KEY selama variabel tersebut diatur, dan tab cURL menggunakan BIRD_API_KEY.

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

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

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

Jika kunci Anda diawali dengan bk_eu1_, panggil https://eu1.platform.bird.com sebagai gantinya.

API merespons dengan 202 Accepted beserta pesan. id-nya diawali dengan sms_, dan status-nya adalah accepted: Bird sudah menerima pesan dan mengirimkannya secara asinkron. Simpan id untuk langkah berikutnya. Pesan tiba dari pengirim bersama yang dipilih Bird untuk negara Anda.

4. Periksa status pengiriman

Ambil pesan berdasarkan ID-nya. Pembacaan tepat setelah pengiriman dapat mengembalikan 404 sampai pesan terlihat di endpoint baca, yang terjadi sesaat setelah 202. Baca lagi beberapa saat kemudian. Ganti SMS_MESSAGE_ID dengan id dari langkah 3, dan ganti contoh kunci API di tab SDK dengan milik Anda. SDK Go tidak memiliki method bertipe untuk membaca pesan SMS, jadi tab Go memanggil path API melalui method request client.Get milik SDK.

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

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.sms.get("SMS_MESSAGE_ID");

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

Field status menunjukkan posisi pesan saat ini:

  • accepted: Bird menyimpan pesan dan belum menyerahkannya ke operator.
  • sent: operator menerima pesan, dan sent_at mencatat waktu Bird menyerahkannya.
  • delivered: operator telah mengonfirmasi pengiriman, dan delivered_at mencatat waktunya.
  • undelivered, failed, rejected, atau expired: pesan tidak sampai ke ponsel. last_error memberikan alasannya, dan Kesalahan pengiriman menjelaskan masing-masing.

Lakukan polling sampai status berpindah dari accepted dan sent, atau subscribe ke event SMS untuk menerima setiap perubahan melalui webhook. Setiap pesan juga muncul di halaman Messages beserta timeline event-nya.

Memperbaiki pengiriman yang gagal

  • 422 SMSDestinationNotEnabled: negara penerima belum diaktifkan untuk workspace Anda. Aktifkan seperti di langkah 2, tunggu hingga satu menit, lalu kirim ulang.
  • 402 WalletInsufficientBalance: saldo dompet tidak cukup untuk pesan ini. Isi ulang dompet, lalu kirim ulang.
  • 403 InsufficientScope: kunci API tidak memiliki cakupan sms. Edit cakupan kunci tersebut atau buat kunci dengan sms:write.

Langkah selanjutnya

  • Mengirim SMS: kirim teks Anda sendiri dengan pengirim dan kategori, secara batch, dan dengan percobaan ulang yang aman.
  • Sender ID SMS: pilih pengirim untuk setiap negara dan daftarkan jika negara tersebut mewajibkannya.
  • Template SMS: katalog template bawaan beserta variabelnya.
  • Event SMS: jenis event dan pengiriman webhook untuk setiap perubahan status.
  • Referensi SMS API: skema permintaan dan respons lengkap.

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.