Hook action và filter

Danh sách đầy đủ hook của plugin, đọc trực tiếp từ mã nguồn phiên bản 1.2.7. Dùng chúng để thêm biến tin nhắn, đổi máy chủ API, chỉnh giới hạn hay can thiệp hàng đợi — mà không phải sửa file plugin, vì mọi thay đổi trong plugin sẽ mất khi cập nhật.

Đặt code ở đâu

Đặt trong functions.php của child theme, hoặc tốt hơn là một plugin nhỏ riêng để đổi giao diện không mất code. Đừng sửa file trong thư mục plugin.

Bản rút gọn có sẵn trong plugin

Tab Rest API của plugin có mục Filter & Action Hooks liệt kê năm hook hay dùng nhất kèm nút chép nhanh. Trang này là danh sách đầy đủ hơn.

Mục Filter và Action Hooks trong tab Rest API với khối mã ví dụ và nút Copy — Mục hook có sẵn trong tab Rest API. Bấm vào ảnh để phóng to.

Action — điểm móc theo luồng xử lý

Hook	Tham số	Chạy khi nào
`devvn_zalo_after_find_user`	`$phone`, `$order_id`	Sau khi tra được UID Zalo từ số điện thoại của một đơn hàng.
`devvn_zalo_after_find_user_before_send`	`$phone`, `$message`	Tra xong UID, ngay trước khi đẩy tin vào hàng đợi gửi.
`devvn_zalo_canhan_after_new_order`	`$uid`, `$own_id`, `$order_id`, `$queue`	Sau khi đã gửi xong tin báo đơn hàng mới. `$queue` là đối tượng hàng đợi, dùng để gửi thêm tin.
`devvn_zalo_log_message`	`$message`, `$context`	Mỗi lần plugin ghi một dòng log. Móc vào đây để đẩy log sang hệ thống giám sát riêng.
`zalocanhan_before_template_part`	`$template_name`, `$template_path`, `$located`, `$args`	Ngay trước khi nạp một tệp giao diện của plugin.
`zalocanhan_after_template_part`	như trên	Ngay sau khi nạp xong tệp giao diện.
`zalocanhan_license_changed`	`$valid` (bool)	Trạng thái giấy phép chuyển từ hợp lệ sang không hợp lệ hoặc ngược lại.
`zalocanhan_license_rejected`	`$key`, `$message`	Máy chủ từ chối mã giấy phép. Móc vào đây để tự gửi cảnh báo cho quản trị.
`zalocanhan_license_log`	`$message`	Mỗi dòng nhật ký của phần giấy phép.

Action mà plugin lắng nghe từ plugin vận chuyển

Plugin tự động gửi tin báo mã vận đơn khi các plugin vận chuyển của DevVN bắn ra những action này. Bạn cũng có thể tự gọi chúng nếu dùng hãng vận chuyển khác.

Hook	Hãng
`after_up_order_to_ghtk`	Giao Hàng Tiết Kiệm
`devvn_after_ghn_create_order`	Giao Hàng Nhanh
`devvn_after_vtp_create_order`	ViettelPost
`devvn_after_vnpost_create_order`	VNPost
`devvn_after_nhanhvn_create_order`	Nhanh.vn

Filter — nội dung tin nhắn

Hook	Tham số	Dùng để
`devvn_zalo_message_replacements`	`$replacements`, `$order`	Thêm hoặc sửa biến thay thế trong tin báo đơn hàng.
`devvn_zalo_message_meta_value`	`$meta_value`, `$meta_key`, `$order`	Đổi giá trị của biến dạng `{meta.key_name}`.
`zalocanhan_prepare_message_filter`	`$template`, `$order`, `$old_status`, `$new_status`, `$src`	Can thiệp vào mẫu tin trước khi thay biến — ví dụ đổi hẳn mẫu theo giá trị đơn.
`devvn_zalo_formatted_address_replacements`	`$address`	Đổi cách ghép chuỗi địa chỉ đầy đủ của khách.
`devvn_message_filter_patterns`	`$patterns`, `$message`	Thêm quy tắc lọc/định dạng áp lên nội dung tin trước khi gửi.
`zalocanhan_campaign_default_name`	mặc định `'Quý khách'`	Đổi cách xưng hô khi chiến dịch không biết tên người nhận.
`zalo_canhan_send_images_thumb_size`	`'woocommerce_thumbnail'`, `$product`	Đổi kích thước ảnh sản phẩm gửi kèm tin.

Filter — Contact Form 7

Hook	Tham số	Dùng để
`devvn_zalo_cf7_message_replacements`	`$replacements`, `$posted_data`, `$contact_form`	Thêm biến thay thế lấy từ dữ liệu biểu mẫu.
`devvn_zalo_cf7_prepare_message`	`$message`, `$template`, `$posted_data`, `$contact_form`	Sửa hẳn nội dung tin sau khi đã thay biến.

Filter — kết nối tới dịch vụ Zalo

Hook	Mặc định	Dùng để
`zalo_canhan_api_domain`	máy chủ của DevVN	Trỏ sang máy chủ Zalo riêng của bạn. Có thể thay bằng hằng số `ZALOCANHAN_APIHOST` trong `wp-config.php`.
`zalo_canhan_api_endpoints`	mảng đường dẫn	Đổi đường dẫn từng lệnh API khi máy chủ riêng đặt khác.
`zalo_canhan_api_timeout`	`60` giây	Nâng thời gian chờ khi mạng chậm.
`zalo_canhan_api_retries`	`2`	Số lần thử lại khi gọi API lỗi.
`zalo_canhan_api_retry_delay`	`2` giây	Khoảng chờ giữa hai lần thử lại.
`zalo_canhan_api_retry_codes`	`[429, 503]`	Những mã lỗi nào thì đáng thử lại.
`zalo_canhan_args_filter`	`$args`, `$action`	Sửa tham số gửi lên API. `$action` cho biết đang gọi lệnh nào: `sendMessage`, `findUser`, `sendFriendRequest`, `getAllFriends`, `getAllGroups`, `sendImages`…
`zalocanhan_campaign_api_timeout`	hằng của lớp chiến dịch	Thời gian chờ riêng cho chiến dịch gửi hàng loạt.
`zalocanhan_campaign_api_retries`	hằng của lớp chiến dịch	Số lần thử lại riêng cho chiến dịch.

Filter — hàng đợi, giới hạn và lịch chạy

Hook	Mặc định	Dùng để
`zalo_queue_retry_time`	`300` giây	Chờ bao lâu trước khi thử gửi lại một tin lỗi.
`zalo_canhan_max_account`	lấy từ giấy phép	Số tài khoản Zalo tối đa được khai.
`zalocanhan_birthday_delay`	`60` giây	Giãn cách giữa hai tin chúc mừng sinh nhật.
`zalocanhan_auto_undo_delay`	`2` giây	Giãn cách khi thu hồi hàng loạt lời mời kết bạn.
`delete_old_scheduler_actions_day`	`60` ngày	Giữ lịch sử sự kiện Action Scheduler bao lâu trước khi xoá.
`zalo_canhan_cache_support`	`false`	Bật hỗ trợ bộ nhớ đệm cho các truy vấn của plugin.

Filter — đăng nhập bằng OTP

Hook	Mặc định	Dùng để
`zalo_otp_expiration`	`180` giây	Mã OTP sống bao lâu.
`limit_request_otp`	`3` lần/ngày	Một số điện thoại được xin OTP bao nhiêu lần mỗi ngày.
`valid_otp_out`	`$out`	Sửa dữ liệu trả về sau khi xác thực OTP thành công.
`zalo_login_domain_email`	`'zalo.me'`	Đuôi email của tài khoản tạo tự động, mặc định là `{sđt}@zalo.me`.
`prefix_account_user`	chuỗi rỗng	Tiền tố thêm vào tên đăng nhập được tạo tự động.
`devvn_login_otp_account_link`	`$link`	Đổi đường dẫn tài khoản mà nút đăng nhập trỏ tới khi khách đã đăng nhập.
`skip_email_by_domain`	`$recipient`	Bỏ qua việc gửi email cho một số đuôi email nhất định.

Filter — giao diện, phân trang và cấu hình

Hook	Mặc định	Dùng để
`zalocanhan_template_path`	`'devvn-zalocanhan/'`	Đổi tên thư mục ghi đè giao diện trong theme.
`zalocanhan_locate_template`	`$template`, `$template_name`, `$template_path`	Tự quyết định đường dẫn tệp giao diện được dùng.
`zalocanhan_get_template`	`$located`, `$template_name`, `$args`, `$template_path`, `$default_path`	Như trên, ở bước nạp tệp.
`zalocanhan_option`	mảng khai báo	Thêm hoặc đổi các mục cấu hình mà plugin đăng ký.
`phone_list_items_per_page`	`20`	Số dòng mỗi trang ở màn hình Danh sách SĐT Zalo.
`devvn_zalo_groups_per_page`	`2`	Số nhóm lấy về mỗi lần khi đồng bộ nhóm.
`devvn_zalo_allgroups_per_page`	`10`	Số nhóm mỗi trang khi lấy toàn bộ danh sách nhóm.
`zalo_canhan_count_per_page` · `zalo_canhan_count_page`	`20000` · số trang	Kích thước lô khi đồng bộ danh sách bạn bè.
`zalo_canhan_group_count_per_page` · `zalo_canhan_group_count_page`	số lượng · số trang	Kích thước lô khi đồng bộ thành viên nhóm.

Ví dụ hay dùng

Thêm biến riêng vào tin báo đơn hàng

PHP

add_filter( 'devvn_zalo_message_replacements', function ( $replacements, $order ) {
    $replacements['{ma_giam_gia}'] = 'GIAMGIA10';
    $replacements['{ngay_giao}']   = $order->get_meta( '_ngay_giao_du_kien' );
    return $replacements;
}, 10, 2 );

Sau đó dùng {ma_giam_gia} ngay trong ô mẫu tin ở tab Woocommerce.

Gửi thêm một tin cho quản lý khi có đơn mới

PHP

add_action( 'devvn_zalo_canhan_after_new_order', function ( $uid, $own_id, $order_id, $queue ) {
    $order = wc_get_order( $order_id );
    if ( ! $order || $order->get_total() < 5000000 ) {
        return;
    }
    $queue->process_send_message_to_phone(
        '0912345678',
        'Đơn lớn #' . $order_id . ' vừa vào: ' . $order->get_total()
    );
}, 10, 4 );

Nâng thời gian chờ khi mạng chậm

PHP

add_filter( 'zalo_canhan_api_timeout', function () {
    return 120;
} );

Đổi mẫu tin theo trạng thái đơn

PHP

add_filter( 'zalocanhan_prepare_message_filter', function ( $template, $order, $old_status, $new_status, $src ) {
    if ( 'completed' === $new_status && $order->get_total() > 2000000 ) {
        return "Cảm ơn {customer_name} đã mua hàng giá trị lớn!\nTặng bạn mã VIP10 cho lần sau.";
    }
    return $template;
}, 10, 5 );

Luôn kiểm tra sự tồn tại trước khi gọi hàm của plugin

Khi gọi trực tiếp các lớp như DevVN_Zalo_Queue, hãy bọc trong class_exists() và try/catch. Không có thì website sẽ chết trắng vào ngày ai đó tắt plugin. Xem thêm REST API và hàm PHP.

Cần gọi plugin từ hệ thống bên ngoài thì xem REST API và hàm PHP.