เอกสาร API ส่ง SMS และ OTP สำหรับนักพัฒนา | SEPSMS

POST /message/send sms:send

發送 SMS

在單一請求中發送訊息給一個或多個目標號碼，可加入個別收件人的變數（personalize），或預先設定發送時間。

originstring已核准的寄件人名稱（Sender Name）

messagestring要發送的訊息內容

recipientsstring[]目標號碼，格式為 0xxxxxxxxx 或 66xxxxxxxxx

scheduledTimestring?ISO 8601 格式的發送時間（留空 = 立即發送）

variablesobject?用於個人化的個別收件人變數值

請求

curl -X POST https://sepsms.com/api/v2/message/send \
  -H "X-API-Key: sk_sep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "SEPSMS",
    "recipients": ["66812345678", "66898765432"],
    "message": "สวัสดีคุณลูกค้า รับส่วนลด 10% วันนี้",
    "scheduledTime": null
  }'

回應

{
  "result": {
    "uuid": "9f8b2c1e-...",
    "refNo": "SP240115...",
    "totalMsisdn": 2,
    "totalCredit": 2,
    "blockedCount": 0,
    "status": "pending"
  }
}

POST /otp/send otp:send

發送 OTP

發送一次性驗證碼並附上參考碼（reference），系統會產生驗證碼並透過 SMS 發送，驗證碼本身不會在回應中傳回。

destinationstring目標號碼

originstring寄件人名稱

templatestring?訊息內容，必須包含 {code}（也可加入 {ref}）

ttlSecondsnumber?驗證碼有效時間 60-600 秒（預設 300）

codeLengthnumber?驗證碼長度 4-8 位數

請求

curl -X POST https://sepsms.com/api/v2/otp/send \
  -H "X-API-Key: sk_sep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "66812345678",
    "origin": "SEPSMS",
    "template": "รหัสยืนยันของคุณคือ {code} (Ref: {ref})"
  }'

回應

{
  "result": {
    "uuid": "1a2b...",
    "reference": "A3K9X2",
    "destination": "66812345678",
    "expiresAt": "2026-01-15T10:35:00.000Z",
    "ttlSeconds": 300
  }
}

POST /otp/verify otp:verify

驗證 OTP

依據發送時取得的 reference，驗證使用者輸入的驗證碼。

referencestring發送 OTP 時取得的參考碼

pinstring使用者輸入的驗證碼

請求

curl -X POST https://sepsms.com/api/v2/otp/verify \
  -H "X-API-Key: sk_sep_..." \
  -H "Content-Type: application/json" \
  -d '{ "reference": "A3K9X2", "pin": "123456" }'

回應

{ "result": { "reference": "A3K9X2", "verified": true } }

GET /message/{uuid} sms:read

送達狀態

查看已發送訊息的送達狀態彙整（依號碼的明細請見 /v2/message/{uuid}/recipients）。

uuidpath發送 SMS 時取得的 uuid

請求

curl https://sepsms.com/api/v2/message/9f8b2c1e-... \
  -H "X-API-Key: sk_sep_..."

回應

{
  "result": {
    "uuid": "9f8b2c1e-...",
    "origin": "SEPSMS",
    "status": "completed",
    "totalMsisdn": 2,
    "drSummary": [
      { "drStatus": "success", "count": 2 }
    ],
    "refundedCount": 0
  }
}

GET /message/{uuid}/recipients sms:read

單一訊息的逐一收訊者明細

查看每個目標號碼的送達狀態，每次最多回傳 50 筆。若一次發送有數十萬個目標號碼，請將 after 設為上一批最後一筆的 uuid 並重複呼叫，每頁的成本不會隨深度增加。使用此模式時，回應會帶有 pagination.nextCursor 作為下一次的 after，以及 pagination.hasMore；最後一頁的 hasMore 為 false，請持續呼叫直到它變成 false。summary 為整批發送依狀態的統計，而非僅本頁，因此只在第一頁回傳，後續頁面不會重複。offset 不是此端點的參數，送出也不會有作用。

uuidpath發送 SMS 時取得的 uuid

afternumber?上一批最後一筆的 uuid，將回傳其後的資料；走訪的第一頁請傳 0。

pagenumber?頁碼，從 1 開始，未使用 after 時適用；頁數越深越慢

limitnumber?每頁筆數，1 至 50，預設 50

statusstring?依送達狀態篩選：pending、success、failed、expired、blocked、invalid、timeout、cancelled

searchstring?比對目標號碼的部分字串

請求

curl "https://sepsms.com/api/v2/message/9f8b2c1e-.../recipients?limit=50&after=3c7f1a90-4b21-4e77-9a03-0d5e1c884f60" \
  -H "X-API-Key: sk_sep_..."

回應

{
  "result": [
    {
      "id": 8814022,
      "uuid": "3c7f1a90-4b21-4e77-9a03-0d5e1c884f60",
      "destination": "66812345678",
      "message": "ข้อความที่ส่ง",
      "drStatus": "success",
      "drStatusAt": "2026-08-31T09:14:02.000Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 1250,
    "nextCursor": "3c7f1a90-4b21-4e77-9a03-0d5e1c884f60",
    "hasMore": true
  },
  "summary": [
    { "drStatus": "success", "count": 1180 },
    { "drStatus": "failed", "count": 70 }
  ]
}

GET /message/credit/balance credit:read

剩餘點數餘額

查詢帳號中的剩餘點數餘額

請求

curl https://sepsms.com/api/v2/message/credit/balance \
  -H "X-API-Key: sk_sep_..."

回應

{ "result": { "balance": 18420 } }

GET /senders senders:read

發送者名稱清單

取得你帳號可用的發送者名稱（Sender Name）、各自的審核狀態、可見範圍，以及是否僅限 OTP。發送 SMS/OTP 時，使用回傳的 origin 作為發送者。請用 privilege 區分你自己擁有的名稱（private）與所有帳號共用的公共名稱（public），沒有其他欄位能區分這兩者。

請求

curl https://sepsms.com/api/v2/senders \
  -H "X-API-Key: sk_sep_..."

回應

{
  "result": [
    {
      "uuid": "95d7bb42-...",
      "origin": "SEPSMS",
      "status": "approved",
      "privilege": "private",
      "isOtpOnly": false,
      "trialAllowed": true,
      "sample": "พิเศษ! ลูกค้ารับส่วนลด 20% วันนี้",
      "purpose": "แจ้งโปรโมชันและข่าวสารถึงลูกค้า",
      "availableSince": "2026-06-01T07:08:44.000Z",
      "lastUsedAt": null,
      "createdAt": "2026-06-01T07:08:44.000Z"
    }
  ]
}

POST /webhooks dashboard

Webhook 通知

從開發者儀表板註冊與管理你的端點 URL（需登入，無法透過 API Key 建立）。註冊後，每個事件（例如發送成功/失敗、送達結果、點數即將用盡）都會 POST 到你的 URL。每個 payload 皆以 HMAC-SHA256 簽署（X-Webhook-Signature header）。

urlstring用於接收 event 的 HTTPS 端點

eventsstring[]你想接收的 event 清單

請求

# Webhook endpoints are registered + managed in the
# developer dashboard (logged-in). Registration is not
# available to API keys. Registration payload:
{
  "url": "https://your-app.com/hooks/sepsms",
  "events": ["dr.success", "dr.failed"]
}

回應

// POST sent to your URL. The event name, timestamp and
// signature travel in headers, not the body:
//   X-Webhook-Event: dr.success
//   X-Webhook-Timestamp: 1737020405
//   X-Webhook-Signature: t=1737020405,v1=<hmac-sha256>
{
  "smsUuid": "9f8b2c1e-...",
  "msisdn": "66812345678",
  "txId": "8f3a1c9d...",
  "status": "success"
}

Webhook events： sms.sentsms.failedsms.completeddr.successdr.failedotp.verifiedcredit.loworder.completed

透過 REST API 串接發送 SMS 與 OTP

3 個步驟開始串接

取得 API Key

附上 Header

呼叫 Endpoint

使用 API Key 驗證

主要 Endpoints