Sebelum mengirim
Kirim SMS atau MMS yang didukung menggunakan nomor pengirim yang dikonfigurasi untuk akun Anda. Ini adalah operasi di lingkungan produksi yang dapat menghubungi penerima dan menimbulkan biaya. Kirim hanya kepada penerima yang telah mengizinkan dan gunakan hanya lalu lintas pesan yang telah disetujui; nomor dan referensi contoh di bawah ini bersifat fiktif.
Akun Anda memerlukan persetujuan pengiriman pesan keluar serta izin pengirim, negara, dan lalu lintas pesan yang berlaku. Kredensial langsung pengguna Pribadi/Konsumen tidak memenuhi syarat untuk API ini. Kredensial API khusus yang telah disetujui memiliki jalur kelayakan tersendiri; pengirim P2P seluler dapat memerlukan izin tambahan untuk P2P dan AS/Kanada. Konfirmasikan konfigurasi akun yang benar dengan MultiTEL, alih-alih menganggap kredensial API sebagai izin otomatis untuk mengirim segala jenis lalu lintas pesan.
Kirim permintaan
Lakukan autentikasi melalui HTTPS menggunakan akun API yang diaktifkan dari alamat IP sumber yang diizinkan untuk akun tersebut. Simpan kredensial dalam penyimpanan rahasia di sisi server. Gunakan POST dengan kolom yang dikodekan sebagai formulir, atau objek JSON jika tidak ada kolom formulir maupun parameter kueri yang disertakan. Jangan masukkan kredensial atau teks pesan ke dalam URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Kolom | Wajib | Keterangan |
|---|---|---|
| from | Ya | Nomor pengirim yang telah Anda konfigurasikan, sebaiknya berupa deretan digit internasional lengkap. |
| to | Ya | Satu tujuan, beberapa tujuan yang dipisahkan koma, atau larik JSON. Sebaiknya gunakan deretan digit internasional lengkap. Permintaan grup dapat ditolak karena batas P2P/negara yang berlaku; API ini bukan API pengiriman massal tanpa batasan. |
| text | Untuk SMS | Teks pesan UTF-8. Setidaknya harus ada teks yang tidak kosong atau media. Kirim karakter dan pergantian baris yang sebenarnya, bukan HTML atau teks dengan pengodean escape persen. Beberapa jalur operator menormalisasi string escape literal. |
| media | Untuk MMS yang hanya berisi media | Isi media yang dikodekan dalam Base64, bukan URL atau jalur berkas. Ketersediaan, format, dan ukuran MMS bergantung pada rute yang dikonfigurasi. Konfirmasikan media yang didukung dengan MultiTEL; penangan ini tidak menetapkan batas ukuran media yang berlaku secara universal. |
| reference | Disarankan | Label korelasi Anda, yang disimpan dalam catatan/callback. Sertakan label ini untuk membantu pemecahan masalah. Label ini bukan kunci idempotensi. |
| notifyurl | Tidak | Penerima callback HTTPS Anda. Penangan dapat mengirim hasil awal melalui POST setelah pemrosesan. Penerima tersebut harus berada di bawah kendali Anda dan tidak boleh berupa URL layanan internal. |
Untuk larik JSON, gunakan larik yang sebenarnya pada to; jangan masukkan string larik JSON ke dalam kolom formulir. Gunakan pengiriman ke satu penerima sebagai uji integrasi awal. Dukungan grup dan MMS berbeda menurut rute, jadi konfirmasikan kombinasi yang didukung sebelum menggunakannya.
Baca hasil selengkapnya
Hanya kolom pilihan sebagai ilustrasi; biaya yang ditampilkan bukan penawaran harga.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Periksa status HTTP, status.code dalam JSON, dan status/message dalam respons secara bersamaan. Kode hasil dapat berupa string. Simpan sms_log_id_ori serta nilai pesan/referensi yang dikembalikan untuk korelasi saat meminta dukungan. Nilai uniqueid dan pid pada sistem lama berbeda menurut rute; jangan menyimpulkan formatnya atau menganggapnya sebagai token idempotensi klien.
Success atau Message queued biasanya menunjukkan penerimaan oleh rute yang dipilih, bukan penerimaan di ponsel seseorang. Status callback awal seperti sent tidak dengan sendirinya membuktikan pengantaran akhir.
Segmen dan biaya
Gunakan Analisis panjang SMS pada seluruh teks akhir sebelum mengirim. Harga SMS bergantung pada tujuan dan layanan akun; biaya operator yang berlaku ditambahkan per segmen. Alur pengiriman menjumlahkan harga untuk penerima dan biaya yang berlaku, lalu mengalikannya dengan jumlah segmen SMS yang dihitung. Untuk perhitungan ini, permintaan MMS diperlakukan sebagai satu pesan.
cost dan permsg adalah string nilai uang yang telah diformat dalam respons sistem lama. carrier_fee_usd melaporkan komponen biaya operator dalam USD dan sudah termasuk dalam total biaya pengiriman yang dihitung; jangan menambahkannya lagi. Harga akun yang sebenarnya dan ketersediaan rute harus diperiksa untuk akun Anda. Permintaan ini bukan operasi yang hanya memeriksa harga.
Kode yang ditinjau mendebit saldo setelah alur pengiriman melalui operator berhasil, tetapi penerimaan oleh operator, penyimpanan permanen lokal, dan penagihan bukan satu transaksi. Kesalahan atau habis waktu dapat terjadi setelah permintaan diterima oleh sistem hulu. Tidak ada kunci idempotensi klien yang disediakan: penggunaan ulang referensi yang sama dapat mengirim pesan dan membebankan biaya lagi.
Pengantaran lokal dan hasil campuran
Nomor yang dihosting secara lokal dapat diterima (accepted) ke dalam alur pesan masuk MultiTEL tanpa pengiriman melalui operator eksternal. Untuk permintaan yang seluruh tujuannya lokal, respons dapat mencakup accepted, message_id, provider dan delivery_status. Penerimaan lokal tidak menjamin bahwa tujuan penerusan yang dikonfigurasi oleh penerima telah berfungsi.
Periksa local_delivery_results dan partial jika ada. Seorang penerima dapat menampilkan accepted bernilai true meskipun hasil penerusannya tidak berhasil. Dalam permintaan campuran, penerima melalui operator dapat berstatus diterima (accepted) sementara bagian lokal gagal. Jangan otomatis mencoba ulang seluruh kumpulan pengiriman: rekonsiliasi hasil setiap penerima terlebih dahulu.
Penerimaan permintaan yang seluruh tujuannya lokal melaporkan biaya keluar nol pada alur ini, sementara penerima tetap dapat dikenai biaya pesan masuk normal. Jangan mengartikan biaya keluar nol sebagai jaminan bahwa tidak ada akun yang dikenai biaya.
Callback dan korelasi
Jika notifyurl disertakan, callback awal memiliki pembungkus status dan kolom respons yang mencakup message_id, reference, from, to, status, status_text, error_code, timestamp dan accepted. Hasil lokal juga dapat disertakan. Simpan informasi korelasi tanpa mencatat kredensial API atau isi pesan yang tidak diperlukan ke dalam log.
Penangan ini tidak menambahkan kolom tanda tangan ke callback awal tersebut. Jangan gunakan callback yang belum diverifikasi sebagai satu-satunya dasar otorisasi untuk tindakan lain. Rujuk konfigurasi integrasi/webhook yang didukung untuk akun Anda dan rekonsiliasi hasil yang belum pasti dengan catatan portal atau bantuan tim dukungan. Jangan menganggap callback hanya tiba sekali atau sesuai urutan pengantaran akhir.
Kegagalan dan pemulihan yang aman
Kegagalan validasi dapat menggunakan kode API 403. Penolakan terkait persetujuan akun, P2P, dan kebijakan negara juga dapat menetapkan HTTP 403 serta menyertakan response.code yang dapat dibaca mesin. Pembatasan laju dapat menggunakan 429 dengan informasi percobaan ulang. Kebijakan yang tidak tersedia atau kegagalan pengiriman/penyimpanan permanen lokal dapat menggunakan 503 atau 500; saldo tidak mencukupi pada sistem lama juga dapat mengembalikan 500.
Untuk 429, patuhi Retry-After dan nilai response.retry_after apa pun yang diberikan. Untuk penolakan terkait akun, pengirim, negara, atau penerima, perbaiki penyebabnya sebelum mencoba ulang. Jika terjadi habis waktu atau hasil pengiriman tidak jelas, simpan waktu permintaan, referensi, dan pengenal yang dikembalikan, periksa portal, lalu hubungi tim dukungan sebelum mengirim ulang. Tidak adanya entri log saja bukan bukti bahwa tidak ada operator yang menerima permintaan tersebut.