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:
https://api.ayosms.com/mconnect/gw/sendsms.php

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
{
msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
trx_id : "123456",
status : 1,
segment : 1
}

Balasan Error: Pulsa Tidak Cukup

HTTP Header 200 OK
Content
{
msg_id : "0ca9265c543baf107d3d1feda03aa4d5-1",
trx_id : "123456",
status : 0,
error-text : "ERR002:insufficient balance"
}

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
ERR999 parameter "api_key" kosong

Contoh

Untuk mengirim SMS sederhana berisi Hello world! ke nomor ponsel 62811000000 dengan pengirim berasal dari "AYOSMS!"

https://api.ayosms.com/mconnect/gw/sendsms.php?api_key=your_unique_api_key&from=AYOSMS%21&to=62811000000&msg=Hello+world%21&trx_id=mytrxid12345
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

<Your_DLR_Callback_URL>?msg_id=0ca9265c543baf107d3d1feda03aa4d5-1&trx_id=mytrxid12345&from=AYOSMS%21&to=62811000000&delivered=1460019615&status=1&error-text=DELIVERED

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
SMSMOO
AYOMOBILE!