Twilio会话API中消息投递失败及用户退订处理指南

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\TwilioWebhookController;

Route::post('/twilio/webhook/delivery-status', [TwilioWebhookController::class, 'handleDeliveryUpdate']);

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Twilio\Security\RequestValidator; // 用于验证Webhook签名

class TwilioWebhookController extends Controller
{
    public function handleDeliveryUpdate(Request $request)
    {
        // 1. (重要) 验证Twilio请求签名，确保请求来自Twilio
        // 您的Twilio Auth Token，从配置文件获取
        $authToken = config('services.twilio.auth_token');
        $validator = new RequestValidator($authToken);

        $url = $request->fullUrl();
        $postVars = $request->request->all(); // 获取POST请求体参数
        $twilioSignature = $request->header('X-Twilio-Signature');

        if (!$validator->validate($twilioSignature, $url, $postVars)) {
            Log::warning('Twilio Webhook signature validation failed.', [
                'signature' => $twilioSignature,
                'url' => $url,
                'postVars' => $postVars
            ]);
            return response()->json(['message' => 'Unauthorized'], 403);
        }

        // 2. 解析Webhook数据
        $messageSid = $request->input('MessageSid'); // 消息的SID
        $conversationSid = $request->input('ConversationSid'); // 会话的SID
        $deliveryStatus = $request->input('DeliveryStatus'); // 投递状态 (e.g., delivered, failed, undelivered)
        $deliveryReason = $request->input('DeliveryReason'); // 投递失败原因 (如果失败)
        $participantSid = $request->input('ParticipantSid'); // 参与者的SID
        $errorCode = $request->input('ErrorCode'); // Twilio错误码 (如果失败)

        Log::info("Twilio Delivery Update received:", [
            'messageSid' => $messageSid,
            'conversationSid' => $conversationSid,
            'deliveryStatus' => $deliveryStatus,
            'deliveryReason' => $deliveryReason,
            'participantSid' => $participantSid,
            'errorCode' => $errorCode,
        ]);

        // 3. 根据投递状态和原因执行相应逻辑
        switch ($deliveryStatus) {
            case 'delivered':
                // 消息已成功投递
                Log::info("Message {$messageSid} delivered successfully to participant {$participantSid}.");
                // 可以在这里更新数据库中消息的状态为“已投递”
                // ConversationMessage::where('message_sid', $messageSid)->update(['status' => 'delivered']);
                break;
            case 'failed':
            case 'undelivered':
                // 消息投递失败或未投递
                Log::warning("Message {$messageSid} failed/undelivered to participant {$participantSid}. Reason: {$deliveryReason}, Error Code: {$errorCode}");

                // 特别处理用户退订情况
                if ($errorCode == '30007') { // Twilio错误码30007通常表示用户已退订
                    Log::info("Participant {$participantSid} (Conversation {$conversationSid}) has opted out.");
                    // 更新数据库中该参与者的退订状态
                    // Participant::where('sid', $participantSid)->update(['opted_out' => true]);
                    // 也可以通过participantSid查询到对应的Recipient_Number，然后更新该号码的退订状态
                    // DB::table('example')->where('Recipient_Number', '=', $recipientNumber)->update(['optedOut' => true]);
                }
                // 其他失败原因的处理...
                break;
            default:
                // 其他状态 (如 sent, sending, queued 等)
                Log::info("Message {$messageSid} is in status: {$deliveryStatus}.");
                break;
        }

        // Twilio期望接收一个200 OK响应
        return response()->json(['message' => 'Webhook received successfully'], 200);
    }
}