API Docs
  • Giới thiệu
    • Tổng quan
  • HƯỚNG DẪN KHỞI TẠO
    • Hướng dẫn tạo ứng dụng
    • Hướng dẫn tạo access token
  • Danh sách API
    • Voice OTP
      • Hướng dẫn thiết lập
      • API Voice OTP
    • Call Campaign
      • Hướng dẫn thiết lập
      • API Gọi ra theo chiến dịch
      • API Danh sách chiến dịch
      • API Chi tiết chiến dịch
    • Call Scenario APIs
      • Tổng quan Call Scenario APIs
      • Hướng dẫn xây dựng kịch bản
      • API Tạo kịch bản
      • API Lấy danh sách kịch bản
      • API Lấy thông tin kịch bản
      • API Cập nhật kịch bản
      • API Xóa kịch bản
      • API Tạo hành động
      • API Lấy danh sách hành động
      • API Cập nhật hành động
      • API Xóa hành động
      • API Gửi yêu cầu duyệt kịch bản
      • API Gọi ra theo kịch bản
      • API tạm dừng gọi ra theo kịch bản
      • API tiếp tục gọi ra theo kịch bản
      • Danh sách lỗi
  • Webhook API
    • Webhook
Powered by GitBook
On this page
  • 1. Khởi tạo
  • 2. Tạo kịch bản
  • 3. Thêm hành động
  • 4. Chèn một hành động vào giữa 2 hành động
  1. Danh sách API
  2. Call Scenario APIs

Hướng dẫn xây dựng kịch bản

Hướng dẫn xây dựng kịch bản bằng Call Scenario APIs

PreviousTổng quan Call Scenario APIsNextAPI Tạo kịch bản

Last updated 9 months ago

1. Khởi tạo

Đội ngũ của chúng tôi đã chuẩn bị sẵn các ví dụ mã nguồn tại kho lưu trữ GitHub dưới đây. Bạn có thể sao chép nó về máy của mình để dùng thử.

Repository GitHub: 

git clone https://github.com/vbee-holding/aicall-api-samples.git
cd Vbee-AICall-API-demo

Sau khi pull về, hãy đảm bảo rằng bạn đã cài đặt Node.js để có thể chạy mã nguồn.

Chạy lệnh sau để tải thư viện cần thiết

npm i

2. Tạo kịch bản

Mở file `create_scenario.js` và thực hiện điền đầy đủ 3 thông tin API_KEY, API_SECRET và poolHotlineKey của bạn.

Sau đó chạy lệnh sau.

node create_scenario.js

Đầu tiên sẽ thực hiện API Tạo kịch bản sau đó sử dụng API Lấy danh sách hành động để xem nội dung kịch bản đã tạo. Ở đây là danh sách các hành động đã được tạo như ví dụ ở dưới:

{
    "result": [
        {
            "action_inputs": [
                {
                    "action_id": "6543757451deb414fee10560",
                    "id": "6543757451deb46775e10564",
                    "output_id": "cee1da6d-38b2-4025-a01d-eda0cfb08652"
                }
            ],
            "content_type": "TEXT",
            "id": "6543757451deb4009fe10562",
            "label": "start",
            "response_setting": {
                "response_type": "KEYPAD"
            },
            "responses": [],
            "scenario_id": "6543757451deb41129e1055d",
            "type": "INTERACTIVE_MENU"
        },
        {
            "id": "6543757451deb414fee10560",
            "scenario_id": "6543757451deb41129e1055d",
            "system_outputs": [
                {
                    "label": "start",
                    "next_action_id": "6543757451deb4009fe10562",
                    "type": "SUCCESS"
                }
            ],
            "type": "OUTBOUND_CALL"
        }
    ],
    "status": 1
}

Có thể thấy 2 hành động theo mặc định sẽ được tạo ra như sau:

  • OUTBOUND_CALL đây là hành động của hệ thống dùng để mô tả quá trình gọi ra đến số của khách hàng. Phản hồi của hành động này tương ứng với sự kiện nghe máy sẽ được nối với hành động INTERATIVE_MENU.

  • INTERACTIVE_MENU là hành động phát lời thoại và ghi nhận các phản hồi phím bấm từ khách hàng nghe máy. Bạn có thể chỉnh sửa hành động này qua API Cập nhật hành động.

Lúc này kịch bản có dạng

3. Thêm hành động

Như đã nói ở trên kịch bản sau khi được tạo ra sẽ có nội dung trống mặc định. Tiếp theo là thêm một hành động vào kịch bản.

Cụ thể chúng ta sẽ thêm hành động để :

  • Khi người dùng nghe máy tổng đài sẽ phát lời thoại "Xin chào quý khách, đây là tổng đài CSKH nhân tạo, Mời bạn bấm phím 1 để nghe thông tin khuyến mãi"

  • Sau đó chờ khách hàng phản hồi trong tối đa 5s

  • Nếu khách hàng nhấn phím 1 tổng đài sẽ nói rằng "Chương trình đi 4 tính tiền 3 trong vòng 1 tháng kể từ khi đăng ký hội viên".

Để thực hành, tương tự như ví dụ trước bạn cần mở file `create_action.js` và thực hiện điền đầy đủ 3 thông tin API_KEY, API_SECRET và poolHotlineKey của bạn.

Sau đó dùng lệnh

node create_action.js

Đoạn mã sẽ thực hiện

Nội dung kịch bản trước khi chạy mã:

Tiếp theo 

  const actions = await getScenarioActions(scenario.id);

  // Lấy hành động gốc - system action outbound call
  const root = actions.find((action) => action.type === "OUTBOUND_CALL");

  // Lấy hành động đầu tiên khi khách hàng nghe máy
  const firstAction = actions.find(
    (action) => action.id === root.systemOutputs[0].nextActionId
  );

  // Thêm phím 1 vào danh sách phản hồi của của hành động đầu tiên
  await updateScenarioAction({
    id: firstAction.id,
    contentType: "TEXT",
    contentText: "Xin chào quý khách, đây là tổng đài CSKH nhân tạo, Mời bạn bấm phím 1 để nghe thông tin khuyến mãi",
    responseSetting: { responseType: "KEYPAD", timeout: 5 },
    responses: [{ keyPadMatch: "1" }],
  });

Trên đây là đoạn mã tìm ra hành động tương tác với menu đầu tiên và thêm một phản hồi khi khách hàng nhấn phím 1. Sau đoạn mã trên nội dung kịch bản như sau.

Chú ý

Hành động đầu tiên trong kịch bản không có cài đặt phản hồi, bao gồm thời gian chờ và số lần phát lại tối đa. Điều này có nghĩa là sau khi phát lời thoại, hành động này sẽ tự động dừng kịch bản và kết thúc. Để tránh điều này, khi cập nhật kịch bản, bạn cần thêm giá trị cho hai trường này.

responseSetting: { responseType: "KEYPAD", timeout: 5 },

Giờ chúng ta sẽ bắt đầu tạo hành động với label là "Phím 1" mới với hàm `createInteractiveMenuAction` qua api API Tạo hành động. Hành động này sẽ thuộc loại INTERACTIVE_MENU và khi được kích hoạt, tổng đài sẽ nói "Chương trình đi 4 tính tiền 3 trong vòng 1 tháng kể từ khi đăng ký hội viên".

const pressKey1Action = await createInteractiveMenuAction({
  scenarioId: scenario.id,
  label: 'Phím 1',
  type: 'INTERACTIVE_MENU',
  contentType: 'TEXT',
  contentText: `Chương trình đi 4 tính tiền 3 trong vòng 1 tháng kể từ khi đăng ký hội viên`,
  responseSetting: { responseType: 'KEYPAD' },
});

Sau khi tạo ra hành động trên sẽ chưa được gọi đến vì không được kết nối với phản hồi của bất cứ hành động nào.

Để kết nối hành động mới với phản hồi của hành động đầu tiên, chúng ta sử dụng hàm updateScenarioAction và thêm định danh của hành động mới vào thuộc tính nextActionId.

await updateScenarioAction({
  id: firstAction.id,
  responses: [{ keyPadMatch: "1", nextActionId: pressKey1Action.id }],
});

Cuối cùng nội dung kịch bản sẽ trở thành

Chú ý

Để lời thoại của bạn trở nên sinh động và gần gũi hơn, bạn có thể thêm thẻ cá nhân hóa vào nội dung. Thẻ cá nhân hóa sẽ được thay thế bằng giá trị của trường cá nhân hóa tương ứng.

Cách thêm thẻ cá nhân hóa

Đầu tiên, bạn cần tạo kịch bản và lưu lại các trường cá nhân hóa. Các trường cá nhân hóa sẽ có dạng sau:

"personalized_fields": [
    {
        "name": "Số điện thoại",
        "name_slug": "so_dien_thoai",
        "reading_type": "TEXT"
    },
    {
        "name": "Số tiền",
        "name_slug": "so_tien",
        "reading_type": "CURRENCY"
    },
    {
        "name": "Ngày vay",
        "name_slug": "ngay_vay",
        "reading_type": "DATE"
    },
],

Trong đó:

  • name là tên của trường cá nhân hóa.

  • name_slug là đại diện cho thẻ cá nhân hóa trong nội dung của lời thoại.

  • reading_type là kiểu dữ liệu của trường cá nhân hóa.

Ví dụ khi bạn muốn tổng đài nói rằng:

  • "Xin chào bạn có số điện thoại 0999999999 đã vay số tiền 9 triệu đồng từ ngày 24/7/2023 chưa trả nhé."

Với các giá trị in đậm là giá trị của trường cá nhân hóa. Thì contentText của bạn cần truyền lên sẽ là:

  • "Xin chào bạn có số điện thoại @{{phone_number}} đã vay số tiền @{{so_tien}} từ ngày @{{ngay_vay}} chưa trả nhé."

Chú ý

  • Đối với trường cá nhân hóa so_dien_thoai là một trường cá nhân hóa mặc định của hệ thống bạn sẽ cần sử dụng @{{phone_number}} thay vì @{{so_dien_thoai}}.

Cuối cùng là gửi yêu cầu duyệt bằng API Gửi yêu cầu duyệt kịch bản và tạo cuộc gọi với API Gọi ra theo kịch bản sau khi kịch bản được duyệt.

4. Chèn một hành động vào giữa 2 hành động

Nâng cao hơn một chút trong trường hợp bạn muốn chèn hành động vào giữa 2 hành động đã có.

Và sau bước này chúng ta sẽ tạo được kịch bản mới có nội dung như sau

Để bắt đầu, tương tự như ví dụ trước bạn cần mở file `insert_action.js` và thực hiện điền đầy đủ 3 thông tin API_KEY, API_SECRET và poolHotlineKey của bạn.

Sau đó dùng lệnh

node insert_action.js

4.1 Tạo hành động mới cho phản hồi phím 2

// Tạo hành động khi nhấn phím 2
const pressKey1Action = await createInteractiveMenuAction({
  scenarioId: scenario.id,
  label: 'Phím 2',
  type: 'INTERACTIVE_MENU',
  contentType: 'TEXT',
  contentText: `Trong tháng này chúng tôi có thêm 2 món ăn mới kèm thông tin khuyến mãi. Vui lòng bấm phím 1 để nghe thông tin khuyến mãi`,
  responseSetting: { responseType: 'KEYPAD', timeout: 5 },
});

Lúc này kịch bản có dạng

4.2 Cập nhật lại hành động đầu tiên

Sau đó, bạn cần cập nhật lại hành động đầu tiên

// Liên kết hành động khi nhấn phím 2 với phàn hồi phím 2 của hành động đầu tiên
// Đồng thời hủy liên kết của hành động khi nhấn phím 1 với hành động đầu tiên
await updateScenarioAction({
  id: firstAction.id,
  contentType: "TEXT",
  contentText: "Xin chào quý khách, đây là tổng đài CSKH nhân tạo, Mời bạn bấm phím 2 để nhận tư vấn bán hàng",
  responses: [{ keyPadMatch: "2", nextActionId: pressKey1Action.id }],
});

Chú ý

  • khi sử dụng API Cập nhật hành động các thông tin gửi lên sẽ ghi đè lên thông tin sẵn có. Điều này có nghĩa là nếu bạn gửi lên danh sách phản hồi chỉ có 1 phần từ là hành động khi bấm phím 2 thì hành động khi bấm phím 1 sẽ bị mất liên kết với hành động đầu tiên nên khi bấm phím 1 sẽ coi là bấm phím không hợp lệ. Nếu bạn không cài đặt phản hồi khi không hợp lệ thì hệ thống sẽ tự ngắt cuộc gọi. Kịch bản lúc này sẽ có dạng

Cuối cùng để hoàn thiện kịch bản chúng ta cần liên kết hành động khi nhấn phím 1 vào phản hồi của hành động khi nhấn phím 2. 

// Liên kết hành động khi nhấn phím 1 vào phản hồi của hành động khi nhấn phím 2
await updateScenarioAction({
  id: pressKey2Action.id,
  responses: [{ keyPadMatch: "1", nextActionId: pressKey1Action.id }],
});

Chú ý

  • Khác với việc liên kết hành động vào phản hồi của hành động trước trong phần 3, chúng ta đã thực hiện hai bước để tạo phản hồi và liên kết hành động với phản hồi. Trong bước này, chúng ta có thể thực hiện cả hai việc trong một bước bằng cách truyền đồng thời cả hai tham số keyPadMatch và nextActionId.

  • Khi nhận được chúng tôi sẽ thực hiện việc tạo phản hồi và liên kết hành động thay bạn.

Cuối cùng nội dung kịch bản sẽ là

Cuối cùng là gửi yêu cầu duyệt bằng API Gửi yêu cầu duyệt kịch bản và tạo cuộc gọi với API Gọi ra theo kịch bản sau khi kịch bản được duyệt.

Giờ coi như bạn đã hoàn toàn thực hiện được và có được kịch bản có nội dung như sau.

Đoạn mã sẽ thực hiện tương tự sau đó thực hiện

Tương tự giờ chúng ta sẽ bắt đầu tạo hành động mới với hàm `createInteractiveMenuAction` qua api API Tạo hành động. Hành động này sẽ thuộc loại INTERACTIVE_MENU và khi được kích hoạt, tổng đài sẽ nói "Trong tháng này chúng tôi có thêm 2 món ăn mới kèm thông tin khuyến mãi. Vui lòng bấm phím 1 để nghe thông tin khuyến mãi".

https://github.com/vbee-holding/aicall-api-samples
Bước 3
Bước 3
Bước 3