Gateway › Connector

Connector

Cách hoạt động

agent-hub (webhook gateway)  --POST poll.path-->  bot API (getUpdates)  --items-->  inbound.map (user · chat · text)  -->  bus
bus  -->  outbound.send ({chat} {text})  --POST-->  bot API (sendMessage)

Enable gateway webhook: web app Integrations → Gateways → Enable trên dòng webhook.
Lấy token bot từ bot API của nền tảng (vd. Zalo Bot Manager → Tạo bot).
Trang Integrations → mode connector → chọn preset có sẵn (vd. zalo) → dán token.

Config

{
  "base_url": "https://bot-api.zaloplatforms.com/bot{token}",
  "poll": { "path": "/getUpdates", "body": { "timeout": "30" }, "items": "result" },
  "inbound": {
    "accept": { "event_name": ["message.text.received"] },
    "map": {
      "user_id": "message.from.id",
      "chat_id": "message.chat.id",
      "message_id": "message.message_id",
      "text": "message.text"
    },
    "group_when": { "message.chat.chat_type": "GROUP" }
  },
  "outbound": {
    "send": {
      "path": "/sendMessage",
      "body": { "chat_id": "{chat}", "text": "{text}" },
      "message_id": "result.message_id",
      "max_text_len": 2000
    }
  }
}


`base_url`	http(s), có thể chứa `{token}`.
`poll.*`	Mỗi poll là POST JSON; `timeout_s` 1–120; backoff tăng dần tới `backoff_max_s`.
`inbound.accept`	Chỉ giữ update khớp mọi đường dẫn.
`inbound.map.*`	Đường dẫn chấm vào JSON nền tảng; thiếu = vắng.
`group_when`	Khớp → tin group trong `chat_id`; không → DM từ `user_id`.
template	Chỉ có `{token}`, `{chat}`, `{text}`; thay một lượt.

Đây là bản rút gọn của preset zalo thật (base_url, poll.path, inbound.accept, inbound.map, group_when, outbound.send đều khớp preset gốc). Preset gốc còn có poll.timeout_s, poll.backoff_max_s, thêm các trường map (user_name, display_name, is_bot) và outbound.typing.

Preset API (web app)

GET /api/webhook/connector-presets

Trả về {"presets": {"<name>": {...}, ...}} — một dict theo tên preset. Tên này chính là giá trị truyền vào trường preset khi POST /api/webhook/integrations.

Giới hạn

Chỉ text — ảnh, sticker, voice, file không được chuyển.
At-most-once: getUpdates không có offset/ack.
Không hỗ trợ edit, ack, nút bấm; thread / topic bị bỏ qua.
Một poller mỗi token.
Poller tự khởi động ít lâu sau khi tạo, không cần restart.