📘 Tài liệu Agentic Work

Agentic Work là nền tảng Chatbot AI hỗ trợ khách hàng 24/7 cho doanh nghiệp Việt Nam. Tích hợp đa kênh (Facebook, Zalo, Telegram, WhatsApp), AI + RAG thông minh, response dưới 2 giây.

✨ Tính năng chính

• AI Chat Engine — RAG knowledge search, multi-turn conversation, streaming response
• Widget Web — Embed widget JS vào bất kỳ website nào
• Multi-channel — Facebook Messenger, Zalo OA, Telegram, WhatsApp
• Flow Builder — Visual flow editor + AI auto-generate
• Knowledge Base — Upload docs, crawl website, search AI
• Lead Scoring — AI tự động phân loại khách hàng (hot/warm/cold)
• CRM Integration — Sync leads sang HubSpot, Salesforce, Zoho, Webhook
• Broadcast — Gửi tin nhắn hàng loạt đến khách hàng
• Analytics — Thống kê tin nhắn, satisfaction, intents, top questions

🚀 Bắt đầu nhanh

Bước 1: Đăng ký tài khoản

curl -X POST https://api.agenticwork.vn/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Công ty ABC",
    "owner_name": "Nguyễn Văn A",
    "owner_email": "email@congty.vn",
    "phone": "+84901234567"
  }'

Hệ thống gửi OTP về email. Xác thực bằng:

curl -X POST https://api.agenticwork.vn/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email": "email@congty.vn", "code": "123456"}'

Bước 2: Đăng nhập & lấy API Key

curl -X POST https://api.agenticwork.vn/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "email@congty.vn",
    "password": "your-password"
  }'

Response sẽ chứa JWT token. Sử dụng token này cho mọi request tiếp theo:

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Bước 3: Thêm Knowledge Base

# Thêm kiến thức thủ công
curl -X POST https://api.agenticwork.vn/api/v1/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Giá sản phẩm",
    "content": "Sản phẩm A giá 500k, sản phẩm B giá 1 triệu",
    "category": "pricing"
  }'

# Hoặc crawl từ website
curl -X POST https://api.agenticwork.vn/api/v1/knowledge/crawl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://congty.vn/faq"}'

Bước 4: Cài Widget vào website

<!-- Đặt trước </body> -->
<script
  src="https://api.agenticwork.vn/widget/widget.js"
  data-api-key="sk_test_xxxxxxxx"
  data-theme="blue"
  data-position="right"
  data-greeting="Xin chào! Mình có thể giúp gì cho bạn?"
  async
></script>

Bước 5: Test chat

curl -X POST https://api.agenticwork.vn/api/v1/chat/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Giá sản phẩm A bao nhiêu?",
    "session_id": "test-session-001"
  }'

🔐 Xác thực

Agentic Work sử dụng JWT (HS256) cho xác thực. Token có thời hạn 7 ngày.

JWT Claims

Gửi request

# Header Authorization
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Hoặc dùng API Key (cho widget/widget endpoint)
Authorization: Bearer sk_test_xxxxxxxx

🔑 API Key

Mỗi tenant có 2 API keys:

Regenerate API Key

curl -X POST https://api.agenticwork.vn/api/v1/tenant/api-key/regenerate \
  -H "Authorization: Bearer $TOKEN"

💬 Cài đặt Widget

Embed Script

Thêm đoạn code sau vào trang web của bạn, đặt trước </body>:

<script
  src="https://api.agenticwork.vn/widget/widget.js"
  data-api-key="sk_test_xxxxxxxx"
  data-theme="blue"
  data-position="right"
  data-title="Hỗ trợ khách hàng"
  data-greeting="Xin chào! Mình có thể giúp gì cho bạn?"
  data-placeholder="Nhập tin nhắn..."
  data-color="#2563eb"
  data-avatar="🤖"
  data-powered-by="true"
  async
></script>

Data Attributes

⚙️ Cấu hình Widget

curl https://api.agenticwork.vn/api/v1/widget/config \
  -H "Authorization: Bearer sk_test_xxxxxxxx"

{
  "widget_title": "Hỗ trợ khách hàng",
  "widget_greeting": "Xin chào! Mình có thể giúp gì?",
  "widget_color": "#2563eb",
  "widget_position": "right",
  "welcome_message": "Chào bạn! Tôi là AI assistant...",
  "offline_message": "Chúng tôi đang offline...",
  "allowed_domains": "congty.vn,www.congty.vn",
  "ai_model": "openai/gpt-4o-mini"
}

curl -X PATCH https://api.agenticwork.vn/api/v1/widget/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_title": "Chat với chúng tôi",
    "widget_color": "#10b981",
    "allowed_domains": "congty.vn"
  }'

📡 Events & Callbacks

Widget phát event để bạn tích hợp với hệ thống:

// Lắng nghe sự kiện
window.addEventListener('agentic-chat-open', (e) => {
  console.log('Chat opened');
});

window.addEventListener('agentic-chat-close', (e) => {
  console.log('Chat closed');
});

window.addEventListener('agentic-message-sent', (e) => {
  console.log('User sent:', e.detail.message);
});

window.addEventListener('agentic-message-received', (e) => {
  console.log('Bot replied:', e.detail.message);
});

💬 Chat API

curl -X POST https://api.agenticwork.vn/api/v1/chat/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Xin chào, tôi muốn tư vấn",
    "session_id": "user-123",
    "visitor_id": "visitor-456"
  }'

{
  "reply": "Xin chào! Chào mừng bạn đến với...",
  "session_id": "user-123",
  "intent": "greeting",
  "confidence": 0.95
}

curl https://api.agenticwork.vn/api/v1/chat/history/user-123 \
  -H "Authorization: Bearer $TOKEN"

const eventSource = new EventSource(
  'https://api.agenticwork.vn/api/v1/chat/stream/user-123'
);
eventSource.onmessage = (e) => {
  const data = JSON.parse(e.data);
  document.getElementById('reply').textContent += data.token;
};

📚 Knowledge Base

Quản lý kiến thức cho chatbot. Hỗ trợ RAG (Retrieval-Augmented Generation) — AI tự động tìm kiếm kiến thức liên quan để trả lời.

curl -X POST https://api.agenticwork.vn/api/v1/knowledge/crawl \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://congty.vn/faq"}'

curl -X POST https://api.agenticwork.vn/api/v1/knowledge/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "giá sản phẩm", "limit": 5}'

curl -X POST https://api.agenticwork.vn/api/v1/knowledge/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@san-pham.pdf"

🎯 Leads & Scoring

AI tự động phân loại khách hàng dựa trên hành vi chat, nội dung tin nhắn, và tín hiệu mua hàng.

{
  "id": "uuid",
  "score": 85,
  "classification": "hot",
  "signals": ["urgent_buy_intent", "price_inquiry", "contact_provided"],
  "visitor_id": "visitor-456"
}

curl "https://api.agenticwork.vn/api/v1/leads?page=1&per_page=20&classification=hot" \
  -H "Authorization: Bearer $TOKEN"

🔗 CRM Integration

Đồng bộ lead data sang hệ thống CRM bên ngoài. Hỗ trợ HubSpot, Salesforce, Zoho CRM, và Custom Webhook.

Supported CRM Types

curl -X POST https://api.agenticwork.vn/api/v1/crm/integrations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "crm_type": "custom_webhook",
    "config": {
      "webhook_url": "https://your-api.com/webhook/leads",
      "secret": "your-hmac-secret",
      "method": "POST"
    },
    "sync_direction": "outbound"
  }'

curl -X PUT "https://api.agenticwork.vn/api/v1/crm/integrations/$ID/mappings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [
      {"aw_field": "visitor_name", "crm_field": "contact_name", "transform": ""},
      {"aw_field": "visitor_email", "crm_field": "email", "transform": "lowercase"},
      {"aw_field": "visitor_phone", "crm_field": "phone", "transform": "phone_e164"},
      {"aw_field": "score", "crm_field": "lead_score", "transform": ""},
      {"aw_field": "classification", "crm_field": "status", "transform": "uppercase"}
    ]
  }'

Webhook Payload

Khi lead được sync, webhook sẽ nhận POST request:

{
  "event": "lead.synced",
  "timestamp": "2026-04-23T09:00:00Z",
  "tenant_id": "uuid",
  "lead": {
    "id": "uuid",
    "visitor_name": "Nguyễn Văn A",
    "visitor_email": "nguyenvana@example.com",
    "visitor_phone": "+84901234567",
    "score": 85,
    "classification": "hot",
    "signals": ["urgent_buy_intent"],
    "tags": ["vip", "enterprise"]
  },
  "signature": "sha256=..."  // HMAC-SHA256 nếu cấu hình secret
}

Xác thực Webhook (HMAC-SHA256)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

📱 Kênh kết nối

Quản lý các kênh messaging kết nối với chatbot.

curl -X POST https://api.agenticwork.vn/api/v1/channels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "telegram",
    "name": "Telegram Bot",
    "config": {
      "bot_token": "123456:ABC-DEF..."
    }
  }'

🔀 Flow Builder

Tạo conversation flows với visual editor hoặc AI auto-generate.

curl -X POST https://api.agenticwork.vn/api/v1/flows/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Flow đặt lịch hẹn: hỏi tên → hỏi SĐT → hỏi ngày giờ → xác nhận → gửi SMS"
  }'

Node Types

📊 Analytics

💳 Billing & Plans

💳 In-chat Payment

Thanh toán trực tiếp trong chat qua PayOS VietQR 24/7. Khách hàng quét QR code và thanh toán ngay trên điện thoại.

Payment Config API

curl https://api.agenticwork.vn/api/v1/chat/payment-config?tenant_id=your-tenant-id

curl -X POST "https://api.agenticwork.vn/api/v1/admin/tenants/$TENANT_ID/payment-config" \\
  -H "Authorization: Bearer $TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "payos_client_id": "your-client-id",
    "payos_api_key": "your-api-key",
    "payos_checksum_key": "your-checksum-key",
    "payment_description": "Thanh toán cho {{order_id}}",
    "enabled": true
  }'

Payment Node trong Flow

Thêm node payment vào flow để tạo link thanh toán:

{
  "id": "payment-1",
  "type": "payment",
  "data": {
    "amount": 150000,
    "description": "Thanh toán đơn hàng #12345",
    "product_name": "Sản phẩm A"
  }
}

📝 Form Submissions

Quản lý dữ liệu thu thập từ webform trong chat. Form node cho phép thu thập nhiều field (tên, email, SĐT...) trong một bước.

curl "https://api.agenticwork.vn/api/v1/form-submissions?page=1&per_page=20&flow_id=&from=&to=" \\
  -H "Authorization: Bearer $TOKEN"

{
  "submissions": [
    {
      "id": "uuid",
      "tenant_id": "uuid",
      "session_id": "sess-123",
      "flow_id": "flow-456",
      "data": {
        "fullName": "Nguyễn Văn A",
        "email": "a@example.com",
        "phone": "+849****4567",
        "service": "Tư vấn"
      },
      "created_at": "2026-04-23T09:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

curl "https://api.agenticwork.vn/api/v1/form-submissions/export?from=2026-04-01&to=2026-04-30" \\
  -H "Authorization: Bearer $TOKEN" \\
  --output submissions.csv

Webform Node

Config trong flow editor:

{
  "id": "form-1",
  "type": "webform",
  "data": {
    "title": "Đăng ký tư vấn",
    "fields": [
      {"name": "fullName", "label": "Họ tên", "type": "text", "required": true},
      {"name": "email", "label": "Email", "type": "email", "required": true},
      {"name": "phone", "label": "Số điện thoại", "type": "tel", "required": true},
      {"name": "service", "label": "Dịch vụ quan tâm", "type": "select",
       "options": ["Tư vấn", "Báo giá", "Hỗ trợ"]}
    ]
  }
}

🛒 E-commerce Integration

Tích hợp Shopify & WooCommerce đồng bộ sản phẩm, đơn hàng, và trigger follow-up tự động.

Shopify Webhook

1. Vào Shopify Admin → Settings → Notifications → Webhooks
2. Thêm webhook URL: https://api.agenticwork.vn/api/v1/webhooks/shopify
3. Chọn events: orders/create, orders/paid, products/update
4. Trong Dashboard, cấu hình Shopify credentials và mapping

WooCommerce Webhook

1. Vào WooCommerce → Settings → Advanced → Webhooks
2. Thêm webhook: https://api.agenticwork.vn/api/v1/webhooks/woocommerce
3. Chọn topics: Order created, Order paid, Product updated
4. Delivery format: JSON

💳 Cấu hình In-chat Payment

Bước 1: Tạo tài khoản PayOS

1. Đăng ký tại payos.vn
2. Lấy Client ID, API Key, và Checksum Key
3. Config webhook URL: https://api.agenticwork.vn/api/v1/webhooks/payos

Bước 2: Config trong Dashboard

1. Vào Dashboard → Settings → Payment
2. Nhập PayOS Client ID, API Key, Checksum Key
3. Bật Enabled để kích hoạt cho tenant
4. Test bằng cách tạo flow với payment node

Bước 3: Thêm Payment Node vào Flow

Trong Flow Editor, thêm node payment với cấu hình:

{
  "amount": 150000,
  "description": "Thanh toán đơn hàng #{{order_id}}",
  "product_name": "{{product_name}}",
  "return_url": "https://your-site.com/thank-you"
}

📘 Facebook Messenger

Cài đặt

1. Vào Dashboard → Kênh kết nối → Thêm kênh → Facebook
2. Đăng nhập Facebook và chọn Fanpage muốn kết nối
3. Agentic Work tự động cấu hình webhook
4. Test bằng cách nhắn tin trên Fanpage

Config Facebook App

{
  "type": "facebook",
  "name": "Fanpage CSKH",
  "config": {
    "page_id": "123456789",
    "page_name": "Công ty ABC",
    "access_token": "EAA...",
    "verify_token": "your-custom-verify-token"
  }
}

💚 Zalo Official Account

Cài đặt

1. Tạo Zalo OA tại oa.zalo.me
2. Lấy OA Secret từ Developer Console
3. Vào Dashboard → Kênh kết nối → Thêm kênh → Zalo
4. Nhập OA Secret và cấu hình webhook

Config

{
  "type": "zalo",
  "name": "Zalo OA CSKH",
  "config": {
    "oa_id": "1234567890",
    "oa_secret": "your-oa-secret",
    "webhook_url": "https://api.agenticwork.vn/api/v1/zalo/webhook"
  }
}

✈️ Telegram Bot

Cài đặt

1. Tạo bot với @BotFather
2. Lấy Bot Token
3. Vào Dashboard → Kênh kết nối → Thêm kênh → Telegram
4. Nhập Bot Token

{
  "type": "telegram",
  "name": "Telegram Bot",
  "config": {
    "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  }
}

🪝 Custom Webhook

Kết nối với bất kỳ hệ thống nào qua webhook. Hỗ trợ HMAC-SHA256 signature để xác thực.

Cấu hình

{
  "name": "My CRM Webhook",
  "crm_type": "custom_webhook",
  "config": {
    "webhook_url": "https://your-api.com/leads",
    "secret": "your-hmac-secret-key",
    "method": "POST"
  },
  "sync_direction": "outbound"
}

Supported Methods

🧠 RAG Knowledge Search

Agentic Work sử dụng Retrieval-Augmented Generation (RAG) — kết hợp tìm kiếm vector similarity với LLM generation để trả lời câu hỏi chính xác từ kiến thức doanh nghiệp.

Cách hoạt động

1. User gửi câu hỏi
2. System embed câu hỏi thành vector (sử dụng Ollama local hoặc cloud API)
3. Tìm top 5 knowledge items tương đồng nhất (cosine similarity)
4. Inject context vào prompt và gọi LLM
5. LLM trả lời dựa trên context (không hallucinate)

Cấu hình Model

# Admin cấu hình model cho tenant
curl -X PUT "https://api.agenticwork.vn/api/v1/admin/models/tenants/$TENANT_ID" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_model": "openai/gpt-4o-mini",
    "embedding_model": "ollama/nomic-embed-text"
  }'

🤖 Tạo Flow với AI

Sử dụng AI để tự động tạo conversation flow từ mô tả bằng ngôn ngữ tự nhiên.

Ví dụ

curl -X POST https://api.agenticwork.vn/api/v1/flows/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Flow đặt lịch hẹn:
    1. Chào hỏi và hỏi tên khách hàng
    2. Hỏi số điện thoại
    3. Hỏi ngày giờ muốn đặt
    4. Xác nhận thông tin
    5. Nếu đồng ý → tạo ticket
    6. Nếu không → hỏi lại ngày giờ"
  }'

AI sẽ tạo flow với các node: message → input → input → question → condition → api_call

🎯 Lead Scoring Guide

AI phân loại khách hàng dựa trên:

• Buy intent signals: "Tôi muốn mua", "Giá bao nhiêu", "Còn hàng không"
• Contact info: Cung cấp email/SĐT → +20 điểm
• Urgency: "Ngay bây giờ", "Khẩn cấp" → +15 điểm
• Budget signals: Đề cập budget/price → +10 điểm
• Multi-turn engagement: Chat > 3 tin → +10 điểm

Thresholds

🔗 Kết nối CRM Guide

HubSpot Integration

1. Vào Dashboard → CRM → Thêm integration
2. Chọn HubSpot
3. Nhập HubSpot Private App Token (Settings → Integrations → Private Apps)
4. Thêm Field Mappings (AW field → HubSpot property)
5. Nhấn Test để kiểm tra kết nối
6. Bật integration

Salesforce Integration

1. Vào Dashboard → CRM → Thêm integration
2. Chọn Salesforce
3. Nhập Consumer Key, Consumer Secret, và Salesforce domain
4. Xác thực OAuth với Salesforce admin account
5. Thêm Field Mappings (AW field → Lead field)
6. Bật integration

Zoho CRM Integration

1. Vào Dashboard → CRM → Thêm integration
2. Chọn Zoho CRM
3. Nhập Zoho Client ID, Client Secret, và Region (.com / .vn)
4. Xác thực OAuth với Zoho account
5. Thêm Field Mappings (AW field → Zoho field)
6. Bật integration

Custom Webhook (5 phút)

1. Vào Dashboard → CRM → Thêm integration
2. Chọn Custom Webhook
3. Nhập Webhook URL và Secret
4. Thêm Field Mappings (AW field → CRM field)
5. Nhấn Test để kiểm tra
6. Bật integration