SMPP 介面

介面資訊

本協定定義了 EngageLab OTP 服務的 SMPP 通訊協定，旨在透過 TCP 連線實現高效、可靠的訊息下發和狀態回報。介面資訊包括 IP 地址、埠號，以及連線所需的認證資訊。請確保按照授權管道提供的帳號密碼進行正確配置。

SMPP 地址

smpp 地址：otpsmpp.api.engagelab.cc 請從授權管道（如商務或技術支援）獲取以下資訊：

• 埠號: { port }
• 帳號: { system_id }
• 密碼: { password }

建立連線

客戶端資料封包

建立起 TCP 連線後，第一個資料封包需要發送 BindTransceiver 命令（即 0x00000009）進行鑑權校驗。此資料封包需要包含以下欄位：

• system_id: 分配給客戶的系統帳號，用於標識身分。
• password: 系統帳號對應的存取密碼，用於身分認證。

伺服器端回應

成功回應

• 伺服器端將發送 BindTransceiverResp 命令（即 0x80000009）回應。
• 填充 system_id 欄位，值與接收到的 system_id 欄位一致。

失敗回應

• 若鑑權失敗，伺服器端將斷開該 TCP 連線，並記錄失敗原因。

訊息發送

伺服器端邏輯

訊息發送採用 SUBMIT_SM 命令（即 0x00000004）提交訊息下發請求，伺服器端邏輯如下：

1. 伺服器端解析請求內容，並固定使用 SMS 管道進行下發。
2. 訊息下發為同步模式，結果將以 SUBMIT_SM_RESP 命令（即 0x80000004）回應。
3. 送達情況將透過訊息上報，詳情參考 送達報告。
4. 推薦使用 UCS2 編碼以支援特殊字元和國際化。

客戶端資料封包

客戶端發送 SUBMIT_SM 命令（即 0x00000004）提交訊息，需包含以下欄位：

1. service_type
   • 取值：MSG / CODE / MRKT
   • 預設值：MSG
2. source_addr
   • 可置空，目前 OTP 中暫不使用。
3. destination_addr
   • 訊息目標，需為國際手機號碼形式（如 +6598765432）。
4. short_message
   • 訊息內容，採用 JSON 格式，格式如下：
     { "id": "xxx", // 範本ID "language": "default", // 使用的語言，預設為default "code": "xx", // 驗證碼，僅當 service_type 為 code 時使用 "params": { // 自訂 key-value 對 "key1": "val1" // val 格式為字串 } }

                   
                   {
       "id": "xxx",          // 範本ID
       "language": "default", // 使用的語言，預設為default
       "code": "xx",          // 驗證碼，僅當 service_type 為 code 時使用
       "params": {            // 自訂 key-value 對
         "key1": "val1"       // val 格式為字串
       }
     }
     
                 

     此代碼塊在浮窗中顯示
5. data_coding
   • 推薦使用 UCS2 編碼以確保特殊字元 {} 正常解析。
   • 若支援直接發送 {}，則可使用預設編碼（即 0x00）。
6. header 中的 status
   • 設置為 0x00000000。

伺服器端回應

伺服器端發送 SUBMIT_SM_RESP 命令（即 0x80000004）回應訊息下發結果。

成功回應

• header 的 status 欄位值: 0x00000000
• MESSAGE_ID 欄位: 回應訊息 ID，用於關聯送達報告。

失敗回應

• 伺服器端填充 header 的 status 欄位 提供失敗原因：

送達報告

伺服器端透過 DELIVER_SM 命令（即 0x00000005）上報送達報告。具體欄位如下：

1. service_type
   • 固定值：MSG
2. source_addr
   • 置空。
3. destination_addr
   • 與 SUBMIT_SM 命令中的 destination_addr 一致。
4. data_coding
   • 編碼方式：預設值 0x00。
5. esm_class
   • 設置為 0x00。
6. short_message
   • 採用 delivery receipt 格式封裝送達報告。
7. tlv 中的 ReceiptedMessageID
   • 訊息 ID，用於關聯識別。
8. tlv 中的 MessageState
   • 訊息狀態，欄位值 0x0427。

狀態解析

short_message 欄位 中，stat 的值含義如下：

其他說明

無效命令

針對客戶端提交的無效命令，伺服器端將返回 GENERIC_NACK 命令（即 0x80000000）並記錄相關日誌。伺服器端僅支援以下命令：

1. EnquireLink 命令（即 0x00000015）
2. Unbind 命令（即 0x00000006）
3. SubmitSM 命令（即 0x00000004）
4. DeliverSMResp 命令（即 0x80000005）
5. BindTransceiver 命令（即 0x00000009）

活躍保持

客戶端需每 30 秒（容差 ±5 秒）發送一次 EnquireLink 命令（即 0x00000015），以確保連線活躍。

發送狀態含義

術語說明

• SMPP: 簡訊訊息對等協定（Short Message Peer-to-Peer Protocol），用於簡訊閘道的訊息交換。
• SUBMIT_SM: 提交簡訊訊息的 SMPP 命令。
• DELIVER_SM: 伺服器端用於上報訊息送達情況的 SMPP 命令。

如有任何問題，請聯繫 OTP 技術支援。