Xử lý sự cố thường gặp

(a) Email gửi tới nhưng không thành ticket

Triệu chứng: khách báo đã gửi mail, connection hiện “Connected”, nhưng không thấy hội thoại mới.

Connection có đang được poll không? Bộ poll IMAP chỉ quét các connection có inbound_provider = imap và trạng thái không phải error/disconnected/disabled, và needs_reauth không phải true. Vào Settings → Connections kiểm tra badge trạng thái; nếu “Error” hoặc “Disconnected”, sửa lại rồi bấm Test IMAP để đưa về “Connected”.
Mật khẩu đã thực sự được lưu chưa? Nếu gần đây có sửa mật khẩu IMAP ở màn hình Edit connection mà chỉ bấm Test rồi đóng lại (không bấm Save), mật khẩu mới chưa vào DB — xem chi tiết ở Kết nối email.
Đây có phải mail đến TRƯỚC khi bật connection không? Lần poll đầu tiên (hoặc sau khi UIDVALIDITY của hộp thư đổi) chỉ đặt mốc “bắt đầu từ bây giờ” — không quét lại mail cũ. Nếu mail đã nằm sẵn trong hộp thư trước khi bạn bật/poll lần đầu, nó sẽ không bao giờ thành ticket. Đây là hành vi cố ý, không phải lỗi — xem thêm mục (e).
Địa chỉ nhận có khớp Receiving address không? Nếu 1 connection backing nhiều inbox, email phải khớp đúng plus-address (support+xxx@...) cấu hình ở tab Routing của một trong các inbox — không khớp inbox nào thì mail bị drop hoàn toàn. Xem Tạo inbox & định tuyến.
Sender filter có đang chặn không? Kiểm tra tab Routing → Sender filter của inbox — nếu đang ở chế độ Allow/Deny, email từ địa chỉ không khớp rule sẽ bị drop im lặng.
Có phải bị loop-guard chặn không? Mail tự động (bounce, auto-reply, mailing list, hoặc chính mail Helpdesk gửi đi vòng lại) bị nhận diện và bỏ qua để tránh vòng lặp — kiểm tra xem mail có phải auto-reply/bounce/newsletter không.

(b) Không gửi được reply cho khách

Triệu chứng: agent bấm Send, không báo lỗi, nhưng khách không nhận được mail.

Outbound mode của inbox đang ở Off? Vào chi tiết inbox → tab Outbound → Send mode. Nếu là “Off — don’t send email”, reply chỉ lưu trong app, không gửi mail thật — đây là cấu hình chủ đích, không phải lỗi.
Mode Shared nhưng connection chưa có SMTP? Nếu Send mode là Shared, hệ thống cần smtp_host + smtp_username trên Connection. Thiếu thì hệ thống rơi về gửi qua kênh dự phòng của ODP (không giữ được From/threading đúng) — kiểm tra badge cảnh báo “No SMTP on connection → system fallback” ngay trên tab Outbound.
Mode Custom nhưng thiếu Host/Username? Cần điền đủ Host + Username (+ Password đã lưu) rồi bấm Test SMTP để xác nhận trước khi trông chờ gửi thật.
Contact có email không? Nếu requester của hội thoại không có primary_email hợp lệ, hệ thống không có địa chỉ để gửi và âm thầm bỏ qua.
Inbox có phải kênh email không? Reply chỉ được gửi email khi channel_type = email; inbox WhatsApp đi theo đường khác.

(c) SLA không cập nhật / badge đứng yên

Triệu chứng: hội thoại sắp/đã trễ hạn nhưng badge SLA vẫn hiện “On track” hoặc không đổi.

Hội thoại đã được gán SLA policy chưa? Recompute mỗi phút chỉ chạy cho hội thoại có sla_policy_id và chưa Resolved — hội thoại chưa gán policy nào sẽ không bao giờ có badge SLA.
Policy có thật sự áp dụng (applies_to) cho hội thoại này không? Nếu policy giới hạn theo inbox/label/priority cụ thể mà hội thoại không khớp, nó bị bỏ qua trong lượt tính.
Có bật “Business hours only” và mong đợi tính theo giờ làm việc? Xem caution ở Chính sách SLA — lựa chọn lịch làm việc hiện không được lưu, nên SLA luôn tính theo giờ đồng hồ 24/7 dù đã bật tuỳ chọn này. Không phải lỗi “không cập nhật” — số liệu vẫn chạy, chỉ là chạy theo cách khác kỳ vọng.
Có mới thay đổi gì trong vòng 1 phút không? Recompute chạy theo cron mỗi phút — đợi tối đa ~60 giây trước khi kết luận là kẹt.

Triệu chứng: số hiển thị cạnh “Open”/“Mine”/label trên sidebar không khớp số hội thoại thực tế lọc ra được.

Counts không tính từ danh sách đang lọc. Badge sidebar lấy từ một API đếm riêng trên server (theo agent, không theo bộ lọc status/inbox/label/từ khoá hiện tại) — nó luôn phản ánh toàn bảng, không phải “số kết quả đang xem”. Đừng kỳ vọng 2 con số này khớp nhau khi đang áp dụng nhiều bộ lọc.
Đang lọc theo nhiều nhãn cùng lúc? Khi chọn nhiều label, phần lọc phía server hiện chỉ áp dụng nhãn đầu tiên trong danh sách, còn client lọc AND đầy đủ nhưng chỉ trong phạm vi trang dữ liệu đã tải — kết quả hiển thị có thể ít hơn thực tế nếu dữ liệu trải nhiều trang.
API đếm bị lỗi (ví dụ vừa deploy backend mới)? Khi endpoint đếm lỗi, giao diện cố ý giữ badge ở 0 thay vì hiện lỗi to — nếu thấy toàn bộ badge về 0 cùng lúc, nghi ngờ backend/API đang có vấn đề hơn là dữ liệu thật bằng 0.

(e) Không thấy hội thoại cũ dù mail đã có từ trước

Triệu chứng: kết nối một hộp thư đã có sẵn nhiều mail cũ, nhưng Helpdesk chỉ hiện mail mới phát sinh sau khi kết nối.

Đây là hành vi thiết kế có chủ đích, không phải lỗi: lần poll đầu tiên của một connection (hoặc bất cứ khi nào UIDVALIDITY của hộp thư thay đổi) chỉ đặt mốc bắt đầu bằng “email mới nhất tại thời điểm đó”, rồi chỉ xử lý mail đến sau mốc này. Toàn bộ mail đã nằm sẵn trong hộp thư trước khi kết nối/poll lần đầu sẽ không bao giờ tự động thành ticket.