Tài liệu

HTTP

Các bước thiết lập

1. Chuẩn bị sẵn URL endpoint (url) và phương thức yêu cầu (GET, POST, …).
2. Nếu API cần xác thực, chọn basic hoặc bearer trong auth_type rồi nhập tên đăng nhập và mật khẩu hoặc token. Đừng ghi thông tin xác thực trực tiếp vào headers — chúng sẽ bị lưu ở dạng văn bản thuần.

Tài liệu chính thức ↗

Bắt buộc

url

Tùy chọn

method (mặc định GET), headers, body, query_params, auth_type (none / basic / bearer), timeout, retries

Khi body trống, hệ thống sẽ gửi đầu ra của nút phía trước. Chỉ kết nối được địa chỉ công khai.

Lỗi thường gặp

• "not a public address": đích đến là địa chỉ nội bộ hoặc cục bộ (kể cả khi chuyển hướng dẫn đến đó), và bị chặn vì lý do bảo mật.
• Chỉ hỗ trợ URL http và https.
• Khi body để trống, đầu ra của nút trước đó sẽ được gửi đi.
• Thời gian chờ mặc định là 30 giây và tối đa là 60 giây.

DingTalk

Các bước thiết lập

1. Mở nhóm DingTalk → Cài đặt nhóm → Trợ lý nhóm → Thêm bot → Tùy chỉnh (qua Webhook).
2. Ở phần cài đặt bảo mật, chọn Chữ ký hoặc Từ khóa tùy chỉnh (có thể bật cả hai). Với Chữ ký, sao chép khóa bắt đầu bằng SEC vào secret. Với từ khóa, nhập một từ luôn xuất hiện trong tin nhắn của bạn và thêm cả Opengency làm từ khóa, vì "Kiểm tra kết nối" gửi đoạn văn bản "Opengency 连接测试".
3. Sao chép URL webhook được tạo ra vào webhook_url.

Tài liệu chính thức ↗

Bắt buộc

webhook_url

Tùy chọn

secret (khóa chữ ký), msg_type (text / markdown / link / card), message, at_mobiles, at_all

Lấy webhook_url tại nhóm DingTalk → Trợ lý nhóm thông minh → Thêm robot. "Kiểm tra kết nối" sẽ gửi thật một tin nhắn thử vào nhóm. Nội dung tin nhắn thử được cố định là "Opengency 连接测试". Nếu robot dùng từ khóa tùy chỉnh, một trong các từ khóa phải là "Opengency", nếu không bài kiểm tra sẽ bị từ chối vì từ khóa không khớp (không ảnh hưởng nếu chỉ bật Chữ ký).

Lỗi thường gặp

• Chữ ký không khớp (sign not match): robot dùng Chữ ký nhưng secret bị trống hoặc sai. Hãy nhập khóa chữ ký bắt đầu bằng SEC, không phải access_token trong URL webhook.
• Không khớp từ khóa: tin nhắn không chứa từ khóa nào của bot. Hãy đưa một từ khóa vào tin nhắn, hoặc thêm vào bot một từ khóa mà tin nhắn của bạn sẽ chứa.
• Dấu thời gian không hợp lệ: đồng hồ của máy chủ chạy Opengency lệch hơn một giờ so với DingTalk. Hãy chỉnh lại giờ máy chủ.
• "Kiểm tra kết nối" không phải chạy thử — nó thực sự đăng "Opengency 连接测试" vào nhóm.

WeCom

Các bước thiết lập

1. Mở nhóm WeCom → "…" ở góc trên bên phải → Bot nhóm → Thêm bot.
2. URL webhook sẽ hiển thị ngay khi bot được tạo.
3. Sao chép URL đó vào webhook_url.

Tài liệu chính thức ↗

Bắt buộc

webhook_url

Tùy chọn

msg_type (text / markdown / card), message, at_mobiles, at_all, url và title (dùng cho card)

Lấy webhook_url tại nhóm WeCom → Robot nhóm; key trong URL chính là thông tin xác thực. @ chỉ có tác dụng với text. "Kiểm tra kết nối" sẽ gửi thật một tin nhắn thử vào nhóm.

Lỗi thường gặp

• key trong URL webhook chính là thông tin xác thực: bất kỳ ai có URL đều có thể đăng vào nhóm. Nếu bị lộ, hãy xóa bot khỏi nhóm và thêm một bot mới.
• Nhắc @ chỉ hoạt động với loại text. Loại card còn cần url (đích liên kết của thẻ); thiếu url sẽ không lưu được.
• WeCom giới hạn tốc độ đối với bot đăng quá thường xuyên, khiến tin nhắn không gửi được. Đừng đặt lịch chạy quá dày.
• "Kiểm tra kết nối" thực sự đăng một tin nhắn thử nghiệm vào nhóm.

Feishu

Các bước thiết lập

1. Mở nhóm Feishu → Cài đặt → Bot nhóm → Thêm bot → Bot tùy chỉnh.
2. Vì lý do bảo mật, bạn có thể bật Xác minh chữ ký và điền khóa hiển thị trên trang đó vào secret. Từ khóa tùy chỉnh cũng dùng được; hãy thêm cả "Opengency" làm từ khóa ở đó.
3. Sao chép URL webhook được tạo ra vào webhook_url.

Tài liệu chính thức ↗

Bắt buộc

webhook_url

Tùy chọn

secret (điền khi robot bật xác minh chữ ký), msg_type (text / post / markdown / card), message, title, at_open_ids, at_all

Lấy webhook_url tại nhóm Feishu → Cài đặt nhóm → Robot nhóm → Robot tự tạo. "Kiểm tra kết nối" sẽ gửi thật một tin nhắn thử vào nhóm.

Lỗi thường gặp

• Xác minh chữ ký đang bật nhưng secret để trống hoặc sai: Feishu sẽ từ chối tin nhắn (xác minh chữ ký thất bại). Bạn có thể xem lại khóa trong cài đặt bot.
• Đã đặt từ khóa tùy chỉnh nhưng tin nhắn không chứa từ khóa nào: tin nhắn sẽ bị từ chối.
• at_open_ids cần open_id bắt đầu bằng ou_, không phải số điện thoại hay tên.
• "Kiểm tra kết nối" thực sự đăng một tin nhắn thử nghiệm vào nhóm.

Slack

Các bước thiết lập

1. Mở https://api.slack.com/apps, tạo một App (hoặc chọn App đã có), bật Incoming Webhooks trong mục Features.
2. Nhấp vào Add New Webhook to Workspace, chọn kênh muốn đăng tin và cấp quyền.
3. Sao chép URL webhook được tạo (bắt đầu bằng https://hooks.slack.com/services/) vào webhook_url.

Tài liệu chính thức ↗

Bắt buộc

webhook_url

Tùy chọn

message, username, icon_emoji, channel

webhook_url tự nó chính là thông tin xác thực (ai có nó cũng có thể đăng tin lên kênh đó); Opengency lưu nó ở dạng mã hóa và ẩn nó trên giao diện và nhật ký. Webhook của một Slack App hiện tại luôn đăng vào kênh đã chọn khi tạo, vì vậy username, icon_emoji và channel sẽ bị bỏ qua; muốn đăng vào nơi khác, hãy tạo webhook khác. "Kiểm tra kết nối" sẽ thực sự đăng một tin nhắn thử vào kênh.

Lỗi thường gặp

• no_service: webhook đã bị xóa, vô hiệu hóa, hoặc địa chỉ sai. Kiểm tra trang Incoming Webhooks của App, tạo lại nếu cần và cập nhật kết nối.
• channel_not_found: kênh không tồn tại, hoặc webhook này không có quyền truy cập. Kiểm tra tên kênh, hoặc tạo lại webhook cho đúng kênh.
• channel_is_archived: kênh đã được lưu trữ. Hãy bỏ lưu trữ, hoặc dùng webhook của một kênh khác.
• action_prohibited: quản trị viên không gian làm việc đã giới hạn những gì webhook này được làm. Hãy liên hệ quản trị viên Slack của bạn.
• invalid_payload hoặc no_text: tin nhắn trống hoặc sai định dạng. Hãy đảm bảo message không trống.
• HTTP 429: bạn đang đăng quá thường xuyên và bị Slack giới hạn tốc độ. Hãy thử lại sau, và đừng lên lịch chạy quá sát nhau.
• "Kiểm tra kết nối" không phải chạy thử — nó thực sự đăng "Opengency connection test" vào kênh.

Teams

Các bước thiết lập

1. Trong Teams, mở kênh muốn đăng tin → "…" cạnh tên kênh → Workflows.
2. Chọn mẫu "Send webhook alerts to a channel", chọn nhóm và kênh theo hướng dẫn, rồi lưu.
3. Sau khi tạo xong, sao chép URL webhook từ trang chi tiết của luồng vào webhook_url.

Tài liệu chính thức ↗

Bắt buộc

webhook_url

Tùy chọn

message, title

webhook_url tự nó chính là thông tin xác thực (sig trong địa chỉ là chữ ký của luồng); Opengency lưu nó ở dạng mã hóa và ẩn nó trên giao diện và nhật ký. Chỉ hỗ trợ webhook của Workflows (Power Automate); các webhook Office 365 connector cũ (outlook.office.com/webhook/…) đang bị Microsoft ngừng sử dụng và không được hỗ trợ. Tin nhắn được gửi dưới dạng Adaptive Card: title là tiêu đề in đậm ở đầu thẻ, message là nội dung (Markdown cơ bản hoạt động được). Một tin nhắn không được vượt quá 28 KB; nội dung quá dài sẽ bị cắt bớt. "Kiểm tra kết nối" sẽ thực sự đăng một tin nhắn thử vào kênh.

Lỗi thường gặp

• HTTP 401 / 403 (địa chỉ không hợp lệ hoặc đã bị thu hồi): chữ ký trong URL webhook sai, hoặc đã được tạo lại. Hãy mở luồng trong Teams, sao chép địa chỉ mới nhất và cập nhật kết nối.
• HTTP 404 (không tìm thấy luồng): luồng có thể đã bị xóa. Hãy tạo lại từ mẫu và cập nhật địa chỉ trong kết nối.
• Thông báo luồng bị tắt/vô hiệu hóa: hãy bật lại trong ứng dụng Teams Workflows hoặc Power Automate. Một luồng thuộc về người tạo ra nó, và có thể bị tắt nếu người đó rời đi hoặc tài khoản bị vô hiệu hóa; hãy nhờ quản trị viên chuyển nó cho người khác.
• HTTP 400 (trình kích hoạt không chấp nhận tin nhắn): hãy đảm bảo luồng được tạo từ mẫu "Send webhook alerts to a channel", trình kích hoạt của nó là When a Teams webhook request is received, và bạn chưa thay đổi định dạng tin nhắn mà nó chấp nhận.
• HTTP 429: Teams giới hạn tốc độ webhook (khoảng bốn yêu cầu mỗi giây), đăng quá thường xuyên sẽ bị từ chối. Hãy thử lại sau, và đừng lên lịch chạy quá sát nhau.
• "Kiểm tra kết nối" không phải chạy thử — nó thực sự đăng "Opengency connection test" vào kênh.

Email

Các bước thiết lập

1. Bật SMTP trong cài đặt của nhà cung cấp email.
2. Tạo mật khẩu ứng dụng (một số nhà cung cấp gọi là mã ủy quyền). Hầu hết nhà cung cấp, gồm Gmail, Outlook và Yahoo, không cho phép ứng dụng bên thứ ba gửi thư bằng mật khẩu đăng nhập của bạn.
3. Ghi lại máy chủ SMTP và cổng, ví dụ smtp.gmail.com:587 hoặc smtp.qq.com:465.
4. Điền địa chỉ của bạn vào sender_email và mật khẩu ứng dụng ở bước 2 vào sender_password.

Tài liệu chính thức ↗

Bắt buộc

smtp_server, sender_email, sender_password, to

Tùy chọn

smtp_port (mặc định 587), smtp_ssl (auto / implicit / starttls / none), use_tls, cc, bcc, subject, body, format (text / html / markdown)

subject và body hỗ trợ {{variables}}, biến lấy từ đầu ra của nút phía trước. Hầu hết nhà cung cấp yêu cầu mật khẩu ứng dụng thay vì mật khẩu đăng nhập.

Lỗi thường gặp

• Xác thực thất bại: sender_password đang là mật khẩu đăng nhập của bạn. Hãy dùng mật khẩu ứng dụng hoặc mã ủy quyền thay thế.
• Hết thời gian chờ kết nối hoặc lỗi bắt tay: cổng và kiểu mã hóa không khớp. Cổng 465 dùng TLS ngầm định, cổng 587 dùng STARTTLS; khi smtp_ssl để auto, hệ thống sẽ tự chọn đúng kiểu theo cổng nên hiếm khi cần thay đổi.
• "not a public address": máy chủ SMTP phân giải ra địa chỉ nội bộ hoặc cục bộ (thường gặp với máy chủ mail nội bộ), và bị chặn vì lý do bảo mật. Hãy dùng máy chủ SMTP có thể truy cập từ internet công khai.
• to cần ít nhất một người nhận; nhiều người nhận cách nhau bằng dấu phẩy.

SQLite

Các bước thiết lập

1. Không cần tài khoản hay mật khẩu: tệp cơ sở dữ liệu nằm trong thư mục dữ liệu riêng của bạn.
2. Chỉ cần điền tên tệp vào database_path, ví dụ orders.db; tệp sẽ được tạo nếu chưa tồn tại.

Tài liệu chính thức ↗

Bắt buộc

database_path, sql

Tùy chọn

params, operation (select / insert / update / delete / execute), return_type (mặc định dict), timeout

database_path chỉ cần điền tên file (ví dụ orders.db), file sẽ tự động lưu trong thư mục dữ liệu riêng của bạn. SQL dùng dấu ? làm placeholder, giá trị đặt trong params.

Lỗi thường gặp

• "no such table": tên tệp gõ sai sẽ không báo lỗi không tìm thấy tệp. Thay vào đó, một cơ sở dữ liệu mới, trống sẽ được tạo ra, nên bảng không tồn tại. Hãy kiểm tra tên tệp trước.
• database_path chỉ là tên tệp. Cơ sở dữ liệu nằm trong thư mục dữ liệu riêng của bạn và không thể truy cập tệp ở nơi khác.
• Dùng ? làm placeholder, với các giá trị đặt trong params.

MySQL

Các bước thiết lập

1. Chuẩn bị sẵn host, cổng (mặc định 3306), tên người dùng, mật khẩu và tên cơ sở dữ liệu.
2. Tạo một tài khoản cơ sở dữ liệu riêng cho kết nối này; nếu chỉ chạy truy vấn, chỉ cấp quyền SELECT.
3. Đảm bảo cơ sở dữ liệu có thể truy cập từ internet công khai: tường lửa hoặc security group của nhà cung cấp cloud phải mở cổng.

Tài liệu chính thức ↗

Bắt buộc

host, user, password, database, sql

Tùy chọn

port (mặc định 3306), ssl (disabled / required / verify), params, read_only (mặc định bật), max_rows (mặc định 1000), timeout

SQL dùng %s làm placeholder, giá trị đặt trong params (khi có params, dấu % thường phải viết thành %%). Mặc định chỉ đọc, muốn ghi phải tắt read_only; với nút chỉ đọc nên dùng tài khoản chỉ có quyền SELECT. Mỗi lần chỉ chạy một câu lệnh, chỉ kết nối được địa chỉ công khai.

Lỗi thường gặp

• "not a public address": host là địa chỉ nội bộ (10.x, 172.16–31.x, 192.168.x, 127.0.0.1). Connector chỉ có thể truy cập địa chỉ công khai, nên cơ sở dữ liệu cần một điểm truy cập công khai.
• Ghi dữ liệu bị từ chối: read_only mặc định đang bật và SQL chạy trong giao dịch chỉ đọc. Hãy tắt read_only khi thực sự cần ghi, và kiểm tra tài khoản có quyền ghi.
• Kết quả không đầy đủ: mặc định trả về tối đa 1000 dòng (max_rows, tối đa 10000); phần vượt quá sẽ bị cắt bớt và đánh dấu truncated.
• Chỉ chạy một câu lệnh SQL tại một thời điểm. Dùng %s làm placeholder với giá trị đặt trong params; đừng ghép giá trị trực tiếp vào chuỗi SQL.
• Hết thời gian chờ kết nối: thường do tường lửa hoặc security group chưa mở cổng.

Webhook

Các bước thiết lập

1. Chuẩn bị một URL công khai có thể nhận yêu cầu POST và điền vào webhook_url.
2. Nếu muốn bên nhận xác nhận được yêu cầu đến từ quy trình của bạn, hãy thống nhất một khóa và điền vào secret_key.
3. Ở phía nhận: mọi yêu cầu đều mang X-Webhook-Timestamp; nếu đặt secret_key, yêu cầu còn mang thêm X-Webhook-Signature, là giá trị HMAC-SHA256 dạng hex của (timestamp + "." + raw_body) tính bằng khóa đó.

Bắt buộc

webhook_url

Tùy chọn

secret_key, verify_signature, event_types, retry_count, timeout

Khi đã điền secret_key, request sẽ mang header X-Webhook-Signature (HMAC-SHA256) để bên nhận xác minh chữ ký.

Lỗi thường gặp

• "Kiểm tra kết nối" thực sự gửi một sự kiện với event_type là ping đến bên nhận.
• Phản hồi 4xx hoặc 500, hoặc hết thời gian chờ, sẽ không được thử lại (vì bên nhận có thể đã xử lý rồi). Chỉ thử lại với mã 429, 502, 503, 504 và các kết nối chưa từng thiết lập được.
• "not a public address": URL nhận là địa chỉ nội bộ hoặc cục bộ.
• event_types để trống nghĩa là chuyển tiếp tất cả; khi đã có giá trị, dữ liệu có event_type không nằm trong danh sách sẽ bị bỏ qua.