Pendahuluan
Bird API adalah REST API terpadu untuk semua yang dilakukan platform. Referensi ini mendokumentasikan setiap endpoint publik, dihasilkan dari spesifikasi OpenAPI yang sama yang menggerakkan SDK resmi, sehingga bentuk request dan response di sini persis sama dengan yang dikirim melalui jaringan.
Sidebar referensi mengelompokkan resource yang paling sering digunakan berdasarkan produk: Email, SMS, Voice, Realtime, Verify, dan developer tools (Webhooks dan Documentation, API pencarian dokumentasi). Endpoint publik lainnya, termasuk sending domain, inbound email, kontak dan audiens, serta WhatsApp, dapat dijangkau melalui pencarian dan deep link di panduan masing-masing. Bagian Voice mencakup panggilan, log leg, trunk, nomor, caller ID, destinasi, dan kredensial sesi SIP. Statistik Voice tetap tersedia melalui dashboard dan CLI. Pengaturan workspace, kunci API, dan IP khusus dikelola di dashboard, bukan melalui API publik.
Halaman resource di-deep-link dari panduan: ketika sebuah panduan menyebut endpoint, tautannya mengarah ke entri referensinya di sini.
Konvensi
Setiap endpoint mengikuti konvensi yang sama. Konvensi ini dinyatakan sekali di sini, bukan diulang di setiap halaman.
- Base path: semua endpoint berada di bawah /v1 pada host regional seperti https://us1.platform.bird.com. Lihat Base URL dan region.
- Autentikasi: request membawa kunci API sebagai bearer token: Authorization: Bearer bk_us1_.... Lihat Autentikasi.
- JSON, snake_case: body request dan response berformat JSON dengan nama field snake_case (created_at, workspace_id), dan request harus menyetel Content-Type: application/json.
- Timestamp: semua timestamp adalah string RFC 3339 dalam UTC, pada field berakhiran _at (created_at, delivered_at). Timestamp resource seperti created_at ditetapkan oleh server dan bersifat read-only; beberapa field request, seperti scheduled_at, adalah timestamp yang Anda berikan.
- ID resource bertipe: setiap ID membawa prefiks tipe: em_ untuk pesan email, dom_ untuk sending domain, whk_ untuk endpoint webhook, sup_ untuk suppression, dan seterusnya. Prefiks membuat ID mendeskripsikan dirinya sendiri di log dan mencegah penggunaan ID satu resource di tempat resource lain.
- Pembaruan parsial menggunakan PATCH: permintaan PATCH hanya mengubah field yang Anda sertakan; field yang tidak disertakan tetap tidak berubah. Beberapa subresource yang Anda tuju berdasarkan nama di URL ditulis dengan PUT, yang menggantikan subresource tersebut secara keseluruhan.
- Query parameter bersifat ketat: request yang membawa query parameter yang tidak didokumentasikan oleh endpoint akan ditolak dengan 422 (E01029), bukan diabaikan. Periksa ejaan terhadap daftar parameter endpoint.
- Error: setiap respons error membawa envelope yang sama, dengan type untuk percabangan umum, code yang stabil, message yang dapat dibaca manusia, dan request_id untuk dikutip saat menghubungi dukungan. Lihat Respons error.
- Paginasi: endpoint list menggunakan paginasi berbasis cursor dengan set parameter bersama. Lihat Paginasi.
- Idempotensi: endpoint yang mengubah data menerima header Idempotency-Key agar percobaan ulang aman. Lihat Header Idempotency-Key.
- Deprecation: field yang diganti nama tetap berfungsi dengan nama lamanya, dan respons memberitahukannya melalui header Deprecation. Lihat Deprecation.
Klien yang direkomendasikan
Anda dapat memanggil API dengan klien HTTP apa pun, tetapi klien resmi menangani autentikasi, pemilihan region, percobaan ulang, dan paginasi untuk Anda:
- SDK resmi untuk TypeScript, Go, dan Python: metode bertipe di atas permukaan publik yang dikurasi
- Bird CLI: API dari terminal Anda, juga cocok untuk skrip dan agen
Jalankan di Postman
Seluruh API juga tersedia sebagai koleksi Postman, dikonversi dari spesifikasi yang sama, dengan contoh request dan response di setiap endpoint. Impor environment untuk region Anda, setel apiKey ke kunci API workspace, dan kirim request apa pun.
Baca selanjutnya
- Autentikasi: cara request melakukan autentikasi di tingkat jaringan
- Base URL dan region: host regional dan model region
- Paginasi: cursor, ukuran halaman, dan pengurutan
- Header Idempotency-Key: percobaan ulang yang aman untuk request yang mengubah data
- Respons error: envelope error dan katalog error lengkap
- Deprecation: apa yang masih dilakukan nama field yang digantikan, dan cara bermigrasi darinya
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.