LINE Webhook Hooks 整合指南

OrderChatz 提供了多個 action hook，讓其他外掛能夠監聽和響應 LINE webhook 事件。這些 hook 遵循 WordPress 慣例，提供完整的事件資料供第三方外掛使用。

全局 Webhook Hook

1. otz_webhook_request_received

觸發時機：當接收到 LINE webhook 請求時立即觸發
參數：

• $request (WP_REST_Request) – WordPress REST API 請求物件

使用範例：

add_action( 'otz_webhook_request_received', 'my_webhook_logger' );

function my_webhook_logger( $request ) {
    $body = $request->get_body();
    $signature = $request->get_header( 'x-line-signature' );

    error_log( "收到 LINE webhook 請求，內容長度：" . strlen( $body ) );
}

2. otz_webhook_request_processed

觸發時機：當 webhook 請求處理完成時觸發
參數：

• $request (WP_REST_Request) – WordPress REST API 請求物件
• $response (WP_REST_Response) – WordPress REST API 回應物件，包含以下資料：
  • success (bool) – 是否處理成功
  • processed (int) – 成功處理的事件數量
  • failed (int) – 處理失敗的事件數量
  • processing_time_ms (float) – 處理時間（毫秒）

使用範例：

add_action( 'otz_webhook_request_processed', 'my_webhook_analytics' );

function my_webhook_analytics( $request, $response ) {
    $data = $response->get_data();

    // 取得回應資料
    $success = $data['success'] ?? false;
    $processed_count = $data['processed'] ?? 0;
    $failed_count = $data['failed'] ?? 0;
    $processing_time = $data['processing_time_ms'] ?? 0;

    // 取得 HTTP 狀態碼
    $status_code = $response->get_status();

    // 記錄詳細統計
    $current_stats = get_option( 'my_webhook_stats', [
        'total_processed' => 0,
        'total_failed' => 0,
        'total_requests' => 0,
        'avg_processing_time' => 0
    ]);

    $new_total_requests = $current_stats['total_requests'] + 1;
    $new_avg_time = (($current_stats['avg_processing_time'] * $current_stats['total_requests']) + $processing_time) / $new_total_requests;

    update_option( 'my_webhook_stats', [
        'total_processed' => $current_stats['total_processed'] + $processed_count,
        'total_failed' => $current_stats['total_failed'] + $failed_count,
        'total_requests' => $new_total_requests,
        'avg_processing_time' => $new_avg_time,
        'last_processed' => current_time( 'mysql' ),
        'last_status_code' => $status_code,
        'last_success' => $success
    ]);
}

事件層級 Hook

3. otz_webhook_event_received

觸發時機：當開始處理單一 LINE 事件時觸發
參數：

• $event (array) – LINE 事件資料陣列

使用範例：

add_action( 'otz_webhook_event_received', 'my_event_filter' );

function my_event_filter( $event ) {
    // 記錄所有事件類型
    $event_type = $event['type'] ?? 'unknown';
    $user_id = $event['source']['userId'] ?? 'unknown';

    error_log( "處理事件類型：{$event_type}，來源用戶：{$user_id}" );
}

4. otz_webhook_event_processed

觸發時機：當單一 LINE 事件處理完成時觸發
參數：

• $event (array) – LINE 事件資料陣列
• $result (array) – 處理結果陣列，包含 success/error 資訊

使用範例：

add_action( 'otz_webhook_event_processed', 'my_event_handler' );

function my_event_handler( $event, $result ) {
    if ( ! $result['success'] ) {
        $error_code = $result['error']['code'] ?? 'unknown';
        $error_message = $result['error']['message'] ?? 'Unknown error';

        // 發送錯誤通知給管理員
        wp_mail(
            get_option( 'admin_email' ),
            'LINE Webhook 處理錯誤',
            "事件處理失敗：{$error_code} - {$error_message}"
        );
    }
}

專用事件 Hook

5. otz_line_message_received

觸發時機：當接收到 LINE 訊息事件時觸發
參數：

• $event (array) – LINE 訊息事件資料
• $user_id (string) – LINE 用戶 ID

使用範例：

add_action( 'otz_line_message_received', 'my_message_processor' );

function my_message_processor( $event, $user_id ) {
    $message = $event['message'] ?? [];
    $message_type = $message['type'] ?? 'unknown';

    // 處理特定類型的訊息
    if ( $message_type === 'text' ) {
        $text = $message['text'] ?? '';

        // 檢查是否包含關鍵字
        if ( strpos( $text, '客服' ) !== false ) {
            // 自動標記為客服案件
            my_create_support_ticket( $user_id, $text );
        }
    }
}

6. otz_line_user_followed

觸發時機：當用戶追蹤 LINE 官方帳號時觸發
參數：

• $event (array) – LINE 追蹤事件資料
• $user_id (string) – LINE 用戶 ID

使用範例：

add_action( 'otz_line_user_followed', 'my_welcome_new_user' );

function my_welcome_new_user( $event, $user_id ) {
    // 發送歡迎訊息
    $welcome_message = '歡迎追蹤我們的官方帳號！';

    // 這裡可以使用 OrderChatz 的 API 發送訊息
    // 或整合其他行銷工具
    do_action( 'my_send_line_message', $user_id, $welcome_message );

    // 記錄新用戶
    my_track_new_follower( $user_id );
}

7. otz_line_user_unfollowed

觸發時機：當用戶取消追蹤 LINE 官方帳號時觸發
參數：

• $event (array) – LINE 取消追蹤事件資料
• $user_id (string) – LINE 用戶 ID

使用範例：

add_action( 'otz_line_user_unfollowed', 'my_handle_unfollow' );

function my_handle_unfollow( $event, $user_id ) {
    // 記錄取消追蹤
    my_track_unfollower( $user_id );

    // 清理相關資料
    my_cleanup_user_data( $user_id );

    // 可選：觸發重新行銷活動
    do_action( 'my_trigger_retargeting', $user_id );
}

function my_track_unfollower( $user_id ) {
    $follower_count = get_option( 'line_follower_count', 0 );
    update_option( 'line_follower_count', max( 0, $follower_count - 1 ) );

    // 記錄取消追蹤時間
    update_option( "line_user_unfollowed_{$user_id}", current_time( 'mysql' ) );
}

結論

OrderChatz 的 LINE webhook hook 系統提供了強大的擴展能力，讓開發者能夠輕鬆整合自定義功能。透過適當的使用這些 hook，您可以建立複雜的自動化系統、分析工具、或整合第三方服務。