API Kirim SMS
Pada bagian ini akan dijelaskan mengenai cara mengirim SMS dengan menggunakan AYOSMS! SMS API, kemana URL untuk mengirimkan parameter dan nilainya.
Endpoint URL
Seluruh permintaan untuk mengirimkan SMS ke AYOSMS! SMS API harus ditujukan ke alamat URL sebagai berikut:Input Parameters
Tabel berikut ini adalah daftar parameter bisa dikirimkan ke alamat URL diatas. Perhatikan bahwa 4 parameter pertama adalah WAJIB dikirimkan sedangkan lainnya adalah optional. Semua parameter bersifat case sensitive.Parameter | Deskripsi | Contoh Nilai |
---|---|---|
api_key | Wajib API Key di akun AYOSMS!. | 11877c8e0ac231ca93ec2cfcbe1820eb |
from | Wajib Pengirim pesan SMS. Maksimum 11 karakter. 7-bit karakter. | AYOSMS%21 |
to | Wajib Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+'). Nomor tujuan dapat lebih dari 1, dipisahkan dengan tanda koma ','. | 62811990000,628999900000 |
msg | Wajib Isi dari pesan SMS yang dikirim, harus di URL encode dalam karakter Unicode UTF-8. Terbatas 400 karakter. Hanya menerima 7-bit karakter. | Hello+World%21 |
trx_id | Kode Unik yang dikirim dari pengguna AYOSMS! untuk membantu referensi pada pelaporan SMS. Terbatas 36 karakter. Hanya menerima 7-bit karakter. | ae75fa6b-aa5d-4ea9-9ce7-d7db9da760af |
dlr | Jika Anda ingin menerima status laporan pengiriman SMS "Delivery Report" dari operator maka isi parameter ini dengan '1'. Status laporan ini belum tentu tersedia di semua operator. Alamat URL "delivery report" dapat diisi di halaman pengaturan akun setelah login ke AYOSMS! Webtool. | 1 |
delivery_time | Kirim pesan SMS di waktu tertentu di masa yang akan datang. Dengan mengisi parameter ini maka pesan SMS akan dieksekusi oleh mesin AYOSMS! sesuai dengan tanggal dan jam yang ditentukan. Format: yyyymmddHHii (tahun=yyyy, bulan=mm, tanggal=dd, jam=HH, menit=ii). | 201704070815 |
priority | Untuk pengiriman SMS dengan kecepatan tinggi (seperti contohnya SMS OTP) wajib menambahkan parameter ini (priority=high) Tanpa parameter ini maka operator akan menunda pengiriman SMS smapai beberapa menit kedepan (berbeda-beda waktunya di setiap operator) |
high |
Balasan Pengiriman
SMS API AYOSMS! akan memberikan balasan dalam 2 bentuk:- HTTP Header Status (biasanya dalam bentuk kode 200 OK yang menunjukkan bahwa permintaan API sudah sukses diterima)
- HTTP Content (dalam format JSON)
Balasan Permintaan Pengiriman SMS Sukses
Standar balasan API SMS adalah kode status=1 dan msg_id unik untuk referensi setiap permintaan pengiriman SMS, ditambah trx_id jika parameter trx_id diisi pada saat pemanggilan API:HTTP Header | 200 OK |
Content | { |
Balasan Error: Pulsa Tidak Cukup
HTTP Header | 200 OK |
Content | { |
Response Attributes
Parameter | Deskripsi |
---|---|
status | Kode status '1' menunjukkan permintaan sukses diterima, sedangkan '0' menunjukkan permintaan gagal diterima (untuk kode Error, silakan lihat penjelasannya dibawah) |
msg_id | ID unik untuk identifikasi setiap permintaan pengiriman SMS. Digunakan juga untuk mencocokkan setiap laporan pengiriman (Delivery Report). |
trx_id | Kode unik referensi yang diisi oleh user saat melakukan permintaan pengiriman SMS melalui API |
segment | Jumlah SMS segmen yang dikirimkan. AYOSMS! hanya mendukung GSM 7bit karakter. 1-160 karakter akan dihitung sebagai 1 segmen SMS. Lebih dari 160 karakter maka SMS akan dihitung per 153 karakter sebagai 1 segment. 1 segment SMS dihitung seharga 1 SMS. |
error-text | Kode error diikuti dengan penjelasannya |
Balasan Kode Error
Kode Balasan | Deskripsi |
---|---|
ERR001 | akun user dibatalkan |
ERR002 | pulsa tidak mencukupi |
ERR005 | parameter "from" salah atau kosong |
ERR006 | parameter "to" salah atau kosong |
ERR007 | parameter "msg" salah atau kosong |
ERR008 | parameter "api_key" tidak ditemukan |
ERR009 | pengirim/masking tidak terdaftar |
ERR010 | waktu pengiriman telah lampau |
ERR012 | ditemukan karakter non GSM 7bit (saat ini AYOSMS! hanya mendukung karakter GSM 7bit) |
ERR013 | lebih dari 400 karakter |
ERR014 | tujuan nomor tidak diketahui |
ERR999 | parameter "api_key" kosong |
Contoh
Untuk mengirim SMS sederhana berisi Hello world! ke nomor ponsel 62811000000 dengan pengirim berasal dari "AYOSMS!"
Parameter | Value in Request | Description |
---|---|---|
api_key | your_unique_api_key | API Key di akun AYOSMS!. |
from | AYOSMS%21 (URL encoded dari "AYOSMS!") | Pengirim pesan SMS. Maksimum 11 karakter. 7-bit karakter. |
to | 62811000000 | Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+'). |
msg | Hello+world%21 (URL encoded for "Hello world!") | Isi dari pesan SMS yang dikirim, harus di URL encode dalam karakter Unicode UTF-8. Terbatas 400 karakter. Hanya menerima 7-bit karakter. |
trx_id | mytrxid12345 | Kode Unik yang dikirim dari pengguna AYOSMS! untuk membantu referensi pada pelaporan SMS. Terbatas 36 karakter. Hanya menerima 7-bit karakter. |
Laporan Pengiriman
Laporan Pengiriman (Delivery Receipt (DLR)), adalah pesan yang dikirimkan operator untuk menunjukkan posisi terakhir dari pesan SMS kita.
Meminta Laporan Pengiriman
Jika pada saat permintaan pengiriman mengisi parameter "dlr=1" maka sistem akan memberikan umpan balik sesaat setelah sistem AYOSMS! menerima unpan balik permintaan pengiriman SMS dari operator.
Permintaan Umpan Balik DLR
Sesaat setelah AYOSMS! menerima laporan pengiriman dari operator (DLR), pengiriman umpan balik HTTP DLR akan dikirimkan ke URL Umpan Balik DLR Anda dengan parameter-parameter sebagai berikut:
Parameter | Deskripsi |
---|---|
msg_id | ID unik untuk identifikasi setiap permintaan pengiriman SMS. Digunakan juga untuk mencocokkan setiap laporan pengiriman (Delivery Report). |
trx_id | Kode unik referensi yang diisi oleh user saat melakukan permintaan pengiriman SMS melalui API |
from | Pengirim pesan SMS. |
to | Nomor tujuan menggunakan format internasional (prefix dengan kode negara tanpa tanda '+'). |
delivered | Waktu saat AYOSMS! menerima status DR dari operator (dalam format UNIX TIMESTAMP, GMT+7). |
status | Selalu berisi '1' jika SMS terkirim sampai ke nomor tujuan, dan '0' untuk gagal (seperti SMS kadaluarsa/nomor tujuan tidak aktif/handset error dll) |
error-text | Berisi keterangan lebih detail mengenai kegagalan. (Lihat keterangan error-text dibawah) Error-text: DELIVERED PENDING FAILED EXPIRED GENERATING MPOSTER URL NO ROUTE TO DESTINATION NUMBER SENT NOT DELIVERED |
Balasan dari Sistem Anda
Sistem Anda HARUS membalas dengan text "OK" saat sistem AYOSMS! mengirimkan DR. Sistem AYOSMS! akan mencoba sampai 10x jika sistem Anda tidak memunculkan text "OK".HTTP Header | 200 OK |
Content | OK |