observe-whatsapp

Tổng quan về skill observe-whatsapp

Skill observe-whatsapp giúp bạn chẩn đoán các hoạt động WhatsApp trong Kapso: gửi tin nhắn, thử lại webhook, lỗi API và tình trạng số điện thoại. Skill này được thiết kế cho các kỹ sư hỗ trợ, người vận hành và người tích hợp cần đi từ “có gì đó đã lỗi” đến nguyên nhân cụ thể thật nhanh, mà không phải đọc từng file trong repo trước.

Hãy dùng skill observe-whatsapp khi bạn cần xác minh một tin nhắn đã được gửi, đã được giao hay đã được đọc; tìm ra vì sao webhook không đến; hoặc kiểm tra một cấu hình WhatsApp đang suy giảm, bị chặn hay vẫn khỏe mạnh. Giá trị chính không chỉ là chẩn đoán, mà là một lộ trình triage rõ ràng hơn: skill cho bạn biết nên kiểm tra gì trước và bằng chứng nào là quan trọng nhất.

Skill này phù hợp nhất cho việc gì

observe-whatsapp mạnh nhất trong xử lý sự cố production, đặc biệt khi người dùng có message ID, số điện thoại, lỗi webhook, hoặc một health check thất bại. Skill này không tập trung vào hướng dẫn WhatsApp chung chung, mà vào trạng thái vận hành trong Kapso.

Điều gì làm observe-whatsapp khác biệt

Skill này đi theo workflow và dựa trên bằng chứng. Nó bao gồm cả đường dẫn Kapso CLI trực tiếp lẫn script dự phòng, nên bạn có thể dùng dù đang ở phiên CLI đã đăng nhập hay đang làm việc với API credentials. Điều đó khiến observe-whatsapp for Observability thực dụng hơn nhiều so với một prompt chỉ mô tả triệu chứng.

Khi nào đây là lựa chọn phù hợp

Chọn observe-whatsapp nếu bạn cần kiểm tra timeline giao nhận, lần thử webhook, tín hiệu health, hoặc log API. Nếu bạn chỉ cần một câu trả lời có sẵn hoặc một giải thích dùng một lần, prompt thông thường có thể đã đủ; còn nếu bạn cần chẩn đoán lặp lại được, skill này hợp hơn.

Cách dùng skill observe-whatsapp

Cài đặt bối cảnh và điều kiện tiên quyết

Đường dẫn cài đặt dự kiến là:

npx skills add gokapso/agent-skills --skill observe-whatsapp

Để có kết quả tốt nhất, hãy dùng Kapso CLI trước: xác thực bằng kapso login, rồi chạy kapso status để xác nhận quyền truy cập project và các số WhatsApp đang khả dụng. Nếu không thể dùng CLI, skill này cũng hỗ trợ cơ chế dự phòng qua API với KAPSO_API_BASE_URL và KAPSO_API_KEY.

Biến một vấn đề mơ hồ thành prompt có thể dùng được

Skill hoạt động tốt nhất khi prompt của bạn chứa những факт nhỏ nhưng hành động được: số điện thoại, message ID, sự kiện webhook, khung thời gian, hoặc đúng chuỗi lỗi. Ví dụ, thay vì nói “WhatsApp bị lỗi,” hãy dùng: “Use observe-whatsapp to check why wamid.HBgMMTIzNDU2Nzg5 stopped at delivered and whether webhook retries failed after 10:00 UTC.”

Quy trình thường cho câu trả lời nhanh nhất

Bắt đầu từ triệu chứng mà người dùng nhìn thấy, rồi thu hẹp vào một trong bốn nhánh: giao nhận tin nhắn, giao webhook, triage lỗi, hoặc kiểm tra health. Trên thực tế, skill này kỳ vọng bạn xác nhận cấu hình trước, rồi mới kiểm tra đúng artifact cụ thể sau. Trình tự đó giảm các ngả suy đoán sai và tránh nhầm sang số điện thoại hoặc cuộc hội thoại khác.

Những file nên đọc trước

Để hiểu ngay từ lúc cài đặt, hãy đọc SKILL.md trước, rồi đến references/health-reference.md, references/message-debugging-reference.md, và references/triage-reference.md. Nếu cần ví dụ, hãy xem assets/health-example.json, assets/message-debugging-example.json, và assets/triage-example.json. Nếu muốn hiểu các công cụ dự phòng, hãy xem scripts/messages.js, scripts/message-details.js, scripts/webhook-deliveries.js, và scripts/whatsapp-health.js.

Câu hỏi thường gặp về skill observe-whatsapp

Có cần Kapso CLI để dùng observe-whatsapp không?

Không, nhưng đó là đường dẫn được khuyến nghị. Skill này được thiết kế để hoạt động tốt nhất với kapso status và các lệnh con WhatsApp. Nếu bạn không thể dùng CLI, các script và biến môi trường API sẽ đóng vai trò phương án dự phòng.

observe-whatsapp cần đầu vào gì?

Hãy cung cấp mã định danh, không chỉ triệu chứng: message ID, display number hoặc số điện thoại E.164, phone-number ID, khoảng thời gian, tên sự kiện webhook, hoặc thông báo lỗi thô. Đầu vào càng cụ thể, skill càng ít phải suy luận.

observe-whatsapp có thân thiện với người mới không?

Có, nếu bạn đã biết hình dạng cơ bản của vấn đề. Nó dễ dùng hơn một prompt trống vì cho bạn biết nên kiểm tra gì trước, nhưng vẫn giả định rằng bạn có thể cung cấp ít nhất một artifact WhatsApp cụ thể.

Khi nào không nên dùng skill này?

Đừng dùng observe-whatsapp cho các tác vụ observability không liên quan đến WhatsApp hoặc cho các câu hỏi chiến lược cấp sản phẩm. Skill này cũng không phù hợp khi bạn không có ID, không có timestamp, và không có quyền truy cập log hoặc tín hiệu trạng thái.

Cách cải thiện skill observe-whatsapp

Nêu đúng điểm thất bại

Cách nhanh nhất để cải thiện chất lượng đầu ra là chỉ rõ workflow bị gãy ở đâu: “sent but not delivered,” “webhook received with Connection refused,” hoặc “health is degraded and webhook verification failed.” Điều đó giúp observe-whatsapp bỏ qua phần giải thích quá rộng và tập trung vào bước kiểm tra đang lỗi.

Đưa vào bằng chứng mà skill có thể xác minh

Đầu vào mạnh thường gồm message ID, số điện thoại đã dùng, khung thời gian, và bất kỳ response payload hay mã lỗi nào. Ví dụ, “Use observe-whatsapp to inspect webhook deliveries for whatsapp.message.received between 10:00 and 10:15 UTC; last attempt returned 502” tốt hơn nhiều so với “webhooks are down.”

Dùng các file reference để tinh chỉnh kết quả lần chạy đầu

Nếu câu trả lời đầu tiên quá chung chung, hãy đối chiếu với quy tắc diễn giải trong references/health-reference.md và logic xử lý sự cố trong references/triage-reference.md. Các reference này cho thấy điều gì պետք được xem là critical, degraded, hoặc retryable, nhờ đó cải thiện cả chẩn đoán lẫn cách diễn đạt mà bạn trả về cho người dùng.

Lặp lại từng thay đổi một

Nếu kết quả ban đầu chưa đầy đủ, hãy tinh chỉnh prompt bằng một факт mới: một ID khác, khung thời gian hẹp hơn, hoặc đúng bước kiểm tra đang lỗi. Với observe-whatsapp, cách đó thường hiệu quả hơn việc nhắc lại toàn bộ vấn đề, vì skill này được xây dựng để lần theo một đường vận hành duy nhất đến root cause.