PHP 串接 TextMagic API 發送簡訊：完整整合指南與程式碼範例

前言

簡訊通知是系統常見需求（驗證碼、警報、行銷推播）。TextMagic 是知名簡訊閘道服務商，提供 REST API 與官方 PHP SDK。本文示範如何使用 Composer 安裝 SDK 並發送簡訊。

環境準備

1. 註冊 TextMagic 帳號，取得 username 與 API key (password)。
2. 專案根目錄執行 composer require textmagic/sdk。

發送簡訊完整程式碼

<?php
require_once __DIR__ . '/vendor/autoload.php';

use TextMagic\Services\TextMagicAPI;

$username = 'your_username';
$password = 'your_api_key';

$client = new TextMagicAPI($username, $password);

try {
    // 發送單則簡訊
    $result = $client->send('您的驗證碼是 123456', ['+886912345678'], true);
    
    // 回傳結構範例：
    // [
    //   'messages' => ['msg_id' => 'phone_number'],
    //   'sent_text' => '您的驗證碼是 123456',
    //   'parts_count' => 1
    // ]
    print_r($result);
} catch (Exception $e) {
    error_log("TextMagic 發送失敗: " . $e->getMessage());
    // 可在此整合錯誤通知機制
}

進階功能

• 批次發送：$client->send('內容', ['+886911111111', '+886922222222'])。
• 排程發送：$client->schedule('內容', ['+8869xxxxxxx'], '2024-12-31 23:59')。
• 查詢餘額：$client->getUser()->getBalance()。
• 接收回覆：設定 Webhook URL 接收 MO (Mobile Originated) 訊息。

錯誤處理與最佳實務

1. 例外捕獲：SDK 會拋出 TextMagic\Exceptions\TextMagicException，務必 try-catch。
2. 重試機制：網路抖動時可用指數退避重試 3 次。
3. 號碼格式驗證：發送前以正則確認 E.164 格式（含國碼）。
4. 敏感資訊保護：API Key 請存放於環境變數或密碼管理系統，勿硬編碼。
5. 日誌記錄：記錄請求/回應內容（隱藏部分手機號）供稽核。

替代方案比較

總結

TextMagic PHP SDK 整合簡單，幾行程式碼即可實現全球簡訊發送。生產環境務必加上錯誤處理、重試、日誌與安全儲存憑證，確保通知服務穩定可靠。