SMPP 整合

介面資訊

OTP 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 技術支援。