API Reference

SMSKUB REST API

ส่ง SMS, บริหารแคมเปญ และยืนยันตัวตนด้วย OTP ผ่าน HTTP API เดียว เลือกภาษาโค้ดที่มุมขวาบน ตัวอย่างทุก endpoint จะสลับตามภาษาที่เลือกทันที

Bearer Token REST / JSON NBTC Licensed

Authentication

ทุก request ต้องแนบ API Key ผ่าน header Authorization แบบ Bearer token สร้างและจัดการ key ได้จากหน้า Settings ในพอร์ทัล SMSKUB

เก็บ API Key ไว้ฝั่ง server เท่านั้น อย่าฝังในโค้ดฝั่ง client/mobile หากคาดว่า key รั่วไหลให้ revoke แล้วออกใหม่

HEADER

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

POST/api/messages

ส่งข้อความ (Quick Send)

ส่ง SMS ทันทีไปยังปลายทางหนึ่งหรือหลายเบอร์ เหมาะกับข้อความครั้งเดียวที่ไม่ต้องตั้งเวลา

Request Body

Field	Type	Required	คำอธิบาย
to	string[]	REQUIRED	อาร์เรย์เบอร์ปลายทาง (`0811111111` หรือ `66811111111`)
from	string	REQUIRED	ชื่อผู้ส่งที่อนุมัติแล้ว
message	string	REQUIRED	เนื้อหาข้อความ (ไทย/อังกฤษ)

GET/api/messages

ประวัติข้อความ

ดึงรายการข้อความที่เคยส่ง พร้อม pagination และการเรียงลำดับ

Query Parameters

Param	Type	Default	คำอธิบาย
page	integer	1	เลขหน้า
limit	integer	10	จำนวนต่อหน้า
sort	string	create_at	ฟิลด์ที่ใช้เรียง
order	integer	-1	`1` น้อย→มาก, `-1` มาก→น้อย

GET/api/messages/:id

ข้อความรายรายการ

ดึงรายละเอียดข้อความรายการเดียวจาก id รวมสถานะการนำส่งล่าสุด

Path Parameter

Param	Type	Required	คำอธิบาย
id	string	REQUIRED	รหัสข้อความจากตอนส่งหรือจากประวัติ

POST/api/campaigns

สร้างแคมเปญ

ส่งข้อความแบบตั้งเวลา ติดตามลิงก์ และแนบแท็กผู้รับ เหมาะกับงาน marketing ที่ต้องวัดผล

Request Body

Field	Type	Required	คำอธิบาย
name	string	REQUIRED	ชื่อแคมเปญ
message	string	REQUIRED	เนื้อหาข้อความ
to	string[]	REQUIRED	อาร์เรย์เบอร์ปลายทาง
from	string	REQUIRED	ชื่อผู้ส่ง
is_schedule	boolean	optional	ตั้งเวลาส่งหรือไม่
frequency	string	optional	`onetime`/`daily`/`weekly`/`monthly`/`custom`
start_time	datetime	optional	เวลาเริ่ม (ISO 8601)
is_tracking	boolean	optional	เปิดติดตามลิงก์ (ใช้คู่ `url`)
contact_id	string	optional	รหัสกลุ่มผู้ติดต่อ (ใช้คู่ `is_tag`)

POST/api/v2/otp/request

ขอรหัส OTP

ส่งรหัส OTP ตามค่าที่ตั้งไว้ใน OTP Project คืน ref_no สำหรับผูกรอบการยืนยัน

OTP ใช้ Content-Type: application/x-www-form-urlencoded (ไม่ใช่ JSON)

Form Fields

Field	Type	Required	คำอธิบาย
phone	string	REQUIRED	เบอร์ปลายทาง (0 หรือ 66)
project	string	แนะนำ	รหัส OTP Project
text1	string	optional	ตัวแปรแทรกที่ 1 (≤20 ตัว)
otp	string	optional	กำหนดรหัสเอง (ตรงรูปแบบ project)
ref_code	string	optional	กำหนด reference code เอง

POST/api/v2/otp/verify

ตรวจสอบ OTP

ตรวจรหัส OTP ที่ผู้ใช้กรอกกับเบอร์และ project เดียวกัน คืน validate: true เมื่อถูกต้อง

Form Fields

Field	Type	Required	คำอธิบาย
phone	string	REQUIRED	เบอร์ที่ขอ OTP
project	string	REQUIRED	รหัส OTP Project เดียวกับตอนขอ
otp	string	REQUIRED	รหัส OTP ที่ผู้ใช้กรอก

GET/api/project

OTP Projects

OTP Project เก็บการตั้งค่าของแต่ละงานยืนยันตัวตน — ความยาวรหัส, อายุ, เทมเพลตข้อความ ใช้ project id อ้างอิงตอนขอ/ตรวจ OTP

Method	Endpoint	คำอธิบาย
GET	/api/project	รายการ OTP Project ทั้งหมด
GET	/api/project/:id	ดูการตั้งค่าของ project เดียว

GET/api/transactions/balance

เครดิตคงเหลือ

ตรวจสอบยอดเครดิตคงเหลือและวันหมดอายุของบัญชี

GET/api/senders/usable

ชื่อผู้ส่งที่ใช้ได้

ดึงรายชื่อ Sender Name ที่อนุมัติแล้วและพร้อมใช้ในฟิลด์ from

สถานะข้อความ

ฟิลด์ status ในผลลัพธ์ของข้อความจะมีค่าใดค่าหนึ่งดังนี้

processing

กำลังอยู่ในคิวส่ง

success

ส่งถึงปลายทางสำเร็จ

complete

ประมวลผลเสร็จทุกเบอร์

fail

ส่งไม่สำเร็จ

expired

หมดอายุก่อนนำส่ง

blocklist

เบอร์อยู่ในรายการบล็อก

error

เกิดข้อผิดพลาดระหว่างส่ง

Status Codes

ฟิลด์ code ตรงกับ HTTP status เสมอ เมื่อผิดพลาด response จะมีฟิลด์ error เพิ่ม

Code	ความหมาย	คำอธิบาย
200	Success	ทำรายการสำเร็จ
400	Bad Request	ข้อมูลไม่ถูกต้อง — `error` เป็น array ของฟิลด์ที่ผิด
401	Unauthorized	API Key ไม่ถูกต้อง/ไม่ได้แนบ
402	Expired	เครดิตหมดอายุ / OTP หมดอายุ
403	Forbidden	ไม่มีสิทธิ์ / OTP ยืนยันไปแล้ว
500	Server Error	ข้อผิดพลาดฝั่งเซิร์ฟเวอร์