Giao tiếp Webhook API

🔑 Webhook Token là gì?

💡

Định nghĩa

Webhook Token là mã định danh duy nhất (24 ký tự) dùng để xác thực các HTTP request gửi đến VietBot. Mỗi Agent có một token riêng. Khi bật Webhook, VietBot lắng nghe tại endpoint /webhook/{agentId}?token={token}.

M2M

Giao tiếp máy với máy

VietBot nhận lệnh HTTP POST từ bất kỳ hệ thống nào: Home Assistant, Node-RED, IFTTT, Homey, OpenHAB...

JSON

Dữ liệu JSON

Tất cả dữ liệu trao đổi qua Webhook đều ở định dạng JSON chuẩn, dễ dàng tích hợp với mọi nền tảng.

Real-time

Phản hồi tức thì

VietBot xử lý lệnh và phản hồi ngay lập tức qua Webhook response hoặc thông qua MQTT.

Hai chiều

Gửi & Nhận

Không chỉ nhận lệnh — Webhook còn cho phép VietBot chủ động gửi thông báo ra bên ngoài khi có sự kiện.

⚙️ Cách thiết lập

1

Đăng nhập Web Manager

Mở web.vietbot.vn → Đăng nhập → Chọn Agent cần cấu hình.

2

Mở Function Dialog

Trong trang cấu hình Agent, bấm nút "Sửa chức năng" (Edit Functions).

3

Bật Plugin Webhook và nhấn Generate Token

Trong danh sách plugin bên trái, tìm và chọn plugin "webhook". Sang bảng cấu hình bên phải, nhấn nút Generate để tạo token mới (24 ký tự).

4

Lưu cấu hình

Bấm "Lưu cấu hình" (Save Config) ở cuối popup để xác nhận.

📡 Endpoint URL

🔗

Webhook Endpoint

Sử dụng endpoint sau để gửi lệnh đến VietBot:

POST https://vietbot.vn/api/webhook/{agentId}?token={webhook_token}

💡

Cách lấy Agent ID & Token

Agent ID: Copy từ URL trình duyệt khi mở Agent (?agentId=...).
Token: Copy từ Function Dialog sau khi bật plugin Webhook và nhấn Generate.

📨 Gửi lệnh qua Webhook (HTTP POST)

# VietBot đọc toàn bộ câu
curl -X POST "https://vietbot.vn/api/webhook/{agentId}?token={token}" \
  -H "Content-Type: application/json" \
  -d '{"action":"tts","text":"Xin chào Việt Nam"}'

# VietBot đọc từng từ (streaming)
curl -X POST "https://vietbot.vn/api/webhook/{agentId}?token={token}" \
  -H "Content-Type: application/json" \
  -d '{"action":"tts","text":"Hello world","streaming":true}'

🎯 Các Action được hỗ trợ

TTS

Text-to-Speech

Yêu cầu VietBot đọc text. Action: tts — Trường text: nội dung cần đọc.

{"action":"tts","text":"Nội dung"}

LLM

Gọi LLM trực tiếp

Gửi prompt đến LLM của Agent. Action: llm — Trường prompt: câu hỏi cho AI.

{"action":"llm","prompt":"Hôm nay trời mưa không?"}

AUDIO

Gửi Audio trực tiếp

Gửi audio PCM 16kHz mono. Action: audio — Trường audio: base64 encoded.

{"action":"audio","audio":"...base64..."}

CHAT

Chat với Agent

Gửi câu hỏi text, VietBot trả lời text. Action: chat.

{"action":"chat","message":"Bật đèn phòng khách"}

🏠 Tích hợp với Home Assistant

🏠

Ví dụ: Gửi thông báo từ Home Assistant đến VietBot

Thêm vào configuration.yaml hoặc automation của Home Assistant:

# Home Assistant - Automation
automation:
  - alias: "Door open notification"
    trigger:
      platform: state
      entity_id: binary_sensor.door
      to: 'on'
    action:
      - service: rest_command.vietbot_tts
        data:
          agent_id: "YOUR_AGENT_ID"
          token: "YOUR_WEBHOOK_TOKEN"
          message: "Cửa đã mở"

rest_command:
  vietbot_tts:
    url: "https://vietbot.vn/api/webhook/{{ agent_id }}?token={{ token }}"
    method: post
    content_type: 'application/json'
    payload: '{"action":"tts","text":"{{ message }}"}'

⚠️ Lưu ý bảo mật

Bảo mật

Token là bí mật

Không chia sẻ Webhook Token công khai. Nếu bị lộ, nhấn Generate để tạo token mới.

HTTPS

Luôn dùng HTTPS

Đảm bảo endpoint được truy cập qua https:// để token không bị chặn trên đường truyền.

Rate Limit

Giới hạn tần suất

Không gửi quá nhiều request liên tục. VietBot xử lý tuần tự.

← Quay lại trang chủ Mở Web Manager →