Gateway › Integrations

Integrations

Chế độ

Chế độ	Nhận trả lời	Dùng khi
pull	`GET /webhook/<intg>/updates`	Không mở được endpoint public.
callback	agent-hub POST tới URL của bạn	Có server nhận webhook.
connector	agent-hub tự gọi bot API nền tảng	Nền tảng có bot API long-poll.

Tạo trên trang Integrations của web app: id [a-z0-9]{1,16} (default là id dành riêng), chọn chế độ, tuỳ chọn owner user id. Revoke là vĩnh viễn; không xoay key — revoke rồi tạo mới.

Endpoint & xác thực

POST /webhook/<intg>                                  gửi event (pull hoặc callback)
GET  /webhook/<intg>/updates?offset=0&timeout=30&limit=100
POST /webhook                                         kênh default (cấu hình gateway)

Authorization: Bearer <api_key>        # hoặc chữ ký HMAC bằng api_key

INTG="mybot"; KEY="<api_key>"; OFFSET=0
while true; do
  RESULT=$(curl -sS "http://127.0.0.1:8788/webhook/$INTG/updates?offset=$OFFSET&timeout=30" \
    -H "Authorization: Bearer $KEY")
  UPDATES=$(echo "$RESULT" | jq -r '.result[]')
  if [ -n "$UPDATES" ]; then
    echo "$UPDATES" | jq .
    OFFSET=$(($(echo "$UPDATES" | jq -r '.update_id' | tail -1) + 1))
  fi
done


offset	Ack theo offset: lần GET sau gửi last `update_id` + 1.
update_id	Của một reply xếp hàng chính là `message_id` của nó.
retention	Update giữ 7 ngày.
clamps	timeout 0–50 s (mặc định 30), limit 1–100.
id prefix	Bên trong agent-hub, group và user id thành `<intg>-<id>`; bạn luôn gửi / nhận id gốc.

Lỗi	Ý nghĩa
`401 integration revoked`	Key đã thu hồi.
`404 unknown integration`	Id không tồn tại.
`409 integration is callback mode`	Dùng pull trên kênh callback.
`502 webhook gateway not running`	Webhook gateway hiện không chạy.

Integrations API (web app)

Trang Integrations quản lý các kênh qua API sau:

GET  /api/webhook/integrations                      danh sách kênh đã tạo
POST /api/webhook/integrations                       tạo kênh mới
POST /api/webhook/integrations/<intg_id>/revoke       thu hồi (vĩnh viễn; 404 nếu id lạ)
GET  /api/webhook/connector-presets                  danh sách preset connector

POST /api/webhook/integrations nhận id, name, mode (pull | callback | connector) cùng trường theo chế độ: callback_url cho chế độ callback, preset hoặc config cho chế độ connector, owner_user_id và token tuỳ chọn.

Status	Khi
`201`	Tạo thành công, trả về thông tin kênh.
`400`	Thiếu trường bắt buộc theo chế độ (vd. chế độ connector thiếu cả `preset` và `config`).
`409`	Id đã tồn tại.