Menetapkan nomor ke kampanye pesan

Menetapkan nomor pengirim ke kampanye

Gunakan operasi ini setelah merek pesan dan kampanye produksi Anda terdaftar dan kampanye tersebut aktif. Operasi ini mengaitkan satu nomor berkemampuan SMS di akun Anda dengan kampanye. Operasi ini tidak membuat merek, tidak membuat atau menyetujui kampanye, tidak membeli nomor, dan tidak mengirim pesan.

Portal saat ini menggunakan rute ini ketika menetapkan kampanye ke sebuah nomor. API publik menerima pengenal kampanye; API menurunkan merek dari kampanye milik akun, bukan menerima pengenal merek terpisah.

Permintaan

Kirim POST berenkode form melalui HTTPS menggunakan akun API Anda yang diaktifkan dan alamat IP sumber yang diizinkan. Gunakan pengenal nomor dan kampanye yang sebenarnya dari akun Anda. Nomor dalam contoh ini bersifat fiktif.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Parameter penetapan kampanye
Parameter	Wajib	Arti
action	Ya	Gunakan add untuk menetapkan atau delete untuk menghapus kaitan kampanye nomor saat ini. Huruf besar/kecil dan spasi di sekitarnya dinormalisasi.
campaign	Untuk add	campaignId dari kampanye ACTIVE yang dimiliki oleh akun terautentikasi. Mereknya juga harus milik akun tersebut. Kampanye yang secara eksplisit ditandai sebagai sandbox tidak dapat ditetapkan ke nomor pengirim langsung. Hilangkan parameter ini untuk delete; penghapusan menggunakan kaitan nomor yang sudah ada.
number	Ya	Nomor pengirim yang dimiliki, aktif, tidak dibatalkan (non-void), dan berkemampuan SMS. Untuk nomor Amerika Utara, gunakan kode negara 1 diikuti sepuluh digitnya, tanpa tanda plus. Handler menghapus karakter non-digit dan juga mencari padanan berawalan plus dan sepuluh digit. Normalisasi ini bukan pemeriksaan validitas nomor telepon secara umum.

Operasi ini mengubah satu nomor. Operasi ini tidak memiliki paginasi, parameter batch, atau opsi dry-run. Jangan gunakan endpoint pembuatan kampanye hanya untuk mengaitkan nomor ke kampanye yang sudah ada.

Menghapus kaitan saat ini

Gunakan action=delete dengan nomor yang dimiliki. Ini menghapus kaitan kampanye pengirim nomor tersebut dan mengosongkan kolom merek/kampanye yang tersimpan untuk nomor itu. Ini tidak menghapus kampanye atau merek, tidak melepaskan nomor telepon, tidak membatalkan layanan nomor, dan tidak menghentikan penagihan berulang kampanye.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Respons dan verifikasi

Contoh fiktif ini mengilustrasikan amplop respons API biasa dan kolom hasil terpilih. Nomor yang dikembalikan mempertahankan format yang tersimpan di akun Anda. brandId dan campaignId berupa string kosong setelah penghapusan berhasil.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus adalah status HTTP mitra pesan. Handler menerima respons transport 2xx lalu memperbarui catatan nomor lokal; handler tidak menafsirkan isi respons mitra untuk hasil penerimaan tingkat bisnis yang terpisah. Oleh karena itu, respons sukses bukan bukti bahwa pendaftaran pesan telah selesai atau bahwa pengiriman akan berhasil. Tinjau status kampanye nomor di portal sebelum mengirim trafik produksi.

Jangan memperlakukan kaitan lokal semata sebagai persetujuan pengiriman. Persetujuan kampanye dan merek, penyediaan nomor, izin akun, aturan konten, dan batas pesan biasa tetap berlaku.

Kesalahan dan hasil parsial

401: tidak ada akun terautentikasi yang tersedia bagi handler.
400: action atau number hilang/tidak valid, atau permintaan add tidak memiliki pengenal kampanye.
404: nomor tersebut bukan nomor SMS yang dimiliki, aktif, dan tidak dibatalkan.
409: kampanye tidak tersedia bagi akun, tidak ACTIVE, secara eksplisit sandbox, atau mereknya tidak tersedia bagi akun.
503: integrasi pesan tidak tersedia. Hubungi dukungan alih-alih mengubah kredensial akun atau mengarang nilai konfigurasi.
502: permintaan pesan gagal, kehabisan waktu, atau mengembalikan status HTTP non-2xx. providerStatus mungkin dikembalikan. Timeout tidak membuktikan bahwa mitra tidak melakukan perubahan.
500 dengan partial=true: mitra pesan mengembalikan status HTTP sukses, tetapi kaitan lokal tidak dapat dikonfirmasi. Rekonsiliasi nomor di portal atau hubungi dukungan sebelum mencoba lagi.

Periksa kode status API dan isi respons selain hasil HTTP. Jangan mencoba ulang timeout atau hasil parsial secara membabi buta. Handler ini tidak memiliki kunci idempotensi tingkat permintaan, rollback transaksional, atau pemeriksaan penyelesaian pendaftaran kampanye. Penetapan lokal yang sama dan diulang dapat mengembalikan sukses meskipun basis data melaporkan tidak ada baris yang berubah.

Cakupan dan efek

Operasi ini mengubah perutean nomor pengirim dan kaitan kampanye/merek yang tersimpan. Dalam handler yang ditinjau, operasi ini tidak berisi debit akun langsung, pembuatan kampanye, pembelian, atau pengiriman pesan. Ini bukan penawaran harga atau janji layanan gratis: biaya nomor, kampanye, dan pesan yang ada tetap berlaku sesuai ketentuan akun Anda.

Di portal, beralih ke kampanye yang berbeda terlebih dahulu menghapus kaitan sebelumnya lalu menambahkan yang baru. Keduanya adalah permintaan terpisah. Jika permintaan kedua gagal, kaitan sebelumnya mungkin sudah dihapus. Jangan berasumsi kedua permintaan tersebut di-rollback bersama.