API Chiến dịch #

Một chiến dịch tập hợp mọi thứ mà bot AI cần để trò chuyện với các liên hệ của bạn: hướng dẫn, các kênh hoạt động, giờ hoạt động và hành vi theo dõi. API Chiến dịch cho phép bạn liệt kê, tạo, cập nhật, sao chép, bật, lưu trữ và tinh chỉnh các chiến dịch từ mã của riêng bạn thay vì từ bảng điều khiển.

Tất cả các điểm cuối bên dưới đều liên quan đến URL cơ sở https://api.youraiconnector.com/v1. Mọi yêu cầu phải được xác thực — xem Truy cập API và Xác thực để biết cách lấy và truyền khóa API của bạn. Truy cập API là một tính năng trả phí; nếu không có nó, các yêu cầu sẽ bị từ chối với 403.

Lưu ý: Một số ví dụ hiển thị biểu mẫu truy vấn ?apiKey=YOUR_API_KEY đơn giản, những ví dụ khác sử dụng tiêu đề X-API-Key. Cả hai đều hoạt động ở mọi nơi — hãy sử dụng bất kỳ cách nào phù hợp với thiết lập của bạn.

Các loại chiến dịch #

Khi tạo một chiến dịch, bạn phải chọn một trong các loại sau:

Chữ hoa và chữ thường không quan trọng. type, status, booking_provider, first_response_mode, bot.anthropic_model và bot.ai_speed đều chấp nhận bất kỳ kiểu viết hoa nào — "live", "Live" và "LIVE" đều là một — và giá trị được lưu trữ ở dạng chuẩn, đây cũng là dạng bạn nhận được khi đọc chiến dịch. Ngoại lệ duy nhất là cặp tạm dừng: "Paused" và "paused" là hai trạng thái thực sự khác biệt, vì vậy một cách viết mơ hồ như "PAUSED" sẽ bị từ chối kèm theo 400 yêu cầu bạn chọn một trong hai.

Hai trạng thái tạm dừng #

Cả hai đều dừng chiến dịch: định tuyến đến chỉ chạy khi trạng thái chính xác là Live. Từ API, hãy sử dụng Paused để tạm dừng và Live để tiếp tục — cặp chữ thường tồn tại cho nút trên bảng điều khiển và vẫn được duy trì hoạt động cho nút đó.

Không có trạng thái nào trong số này là những gì xảy ra khi AI ngừng trả lời trong một cuộc trò chuyện. Đó là một công tắc theo từng liên hệ, is_bot_active trên liên hệ — được thiết lập khi con người tiếp quản, khi liên hệ chọn không tham gia hoặc khi AI kết thúc cuộc trò chuyện. Trạng thái của chính chiến dịch không bị ảnh hưởng và mọi cuộc trò chuyện khác trong đó vẫn tiếp tục chạy. Xem tạm dừng hoặc tiếp tục AI cho một liên hệ.

Việc tạo chiến dịch không quyết định ai sẽ trả lời một kênh. Định tuyến được xử lý bởi Điểm truy cập trên một AI Agent, không phải bởi các chiến dịch. Mỗi kênh có một Điểm truy cập mặc định cho kênh, chỉ định Agent trả lời các liên hệ mới, chưa biết trên kênh đó: thiết lập nó với PUT /entry-points/channel-defaults, kiểm tra xem thang đo có đang hoạt động cho tài khoản hay không với GET /entry-points/routing-status, xóa nó với DELETE /entry-points/channel-defaults. POST /channels/campaign vẫn ghi bản đồ định tuyến chiến dịch theo kênh cũ, nhưng bản đồ đó không còn được tham chiếu cho định tuyến đến trên bất kỳ tài khoản nào; nó chỉ được giữ lại để khôi phục. Đừng xây dựng dựa trên nó. Xem Định tuyến một kênh đến một chiến dịch để biết cả hai giao diện cạnh nhau.

Liệt kê chiến dịch #

GET /campaigns

Trả về các chiến dịch của bạn, mới nhất trước. Các chiến dịch đã lưu trữ sẽ bị loại trừ trừ khi bạn truyền archived=true.

Các tham số truy vấn

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Phản hồi

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Khi next_cursor là null, bạn đã đến trang cuối cùng.

Lấy một chiến dịch #

GET /campaigns/{campaignId}

Trả về tài liệu chiến dịch đầy đủ, bao gồm cấu hình bot trực tiếp (bot), cài đặt theo dõi, các kênh đã bật và bất kỳ từ khóa nào. Dấu thời gian được trả về dưới dạng mili giây epoch.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Phản hồi

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Tạo một chiến dịch #

POST /campaigns

Tạo một chiến dịch mới. name và type là bắt buộc; mọi thứ khác là tùy chọn. Bạn có thể bao gồm bất kỳ trường chiến dịch nào khác trong cùng một yêu cầu — ví dụ: language, ai_mode hoặc một đối tượng cấu hình bot đầy đủ — và nó sẽ được lưu trữ cùng với chiến dịch mới. Chủ sở hữu và thời gian tạo được thiết lập tự động.

Các trường yêu cầu

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Cập nhật chiến dịch #

PUT /campaigns/{campaignId}

Cập nhật một phần chiến dịch — chỉ gửi các trường bạn muốn thay đổi. Đây là động từ cập nhật chung duy nhất; không có PATCH /campaigns/{campaignId} (hai lộ trình PATCH là các nút chuyển đổi bật và lưu trữ hẹp).

Các trường bạn có thể thay đổi. Mọi thứ mà trình chỉnh sửa chiến dịch ghi lại, bao gồm name, status, type, language, ai_mode, enabled_channels, các cài đặt kích hoạt và nhỏ giọt, các cờ đặt chỗ và theo dõi, các trường giám sát Instagram/Facebook và toàn bộ cấu hình bot. Danh tính và quyền sở hữu bị khóa trong suốt vòng đời của chiến dịch: user, id và created_at sẽ bị từ chối, cũng như bất kỳ tên trường nào mà điểm cuối không nhận dạng được. Việc từ chối được áp dụng cho mỗi yêu cầu, không phải cho mỗi trường — một khóa không xác định sẽ trả về 400 và không có gì trong yêu cầu đó được ghi lại.

ai_mode trên một chiến dịch có hỗ trợ Agent sẽ phản ánh trạng thái của Agent đó. Khi một chiến dịch được trả lời bởi AI Agent, việc đọc chiến dịch sẽ trả về ai_mode dựa trên nút gạt Active của Agent đó — công tắc duy nhất thực sự quyết định việc AI có phản hồi hay không. Việc ghi ai_mode trên chiến dịch như vậy vẫn được chấp nhận nhưng sẽ không thay đổi giá trị bạn đọc được; thay vào đó, hãy bật hoặc tắt nút gạt Active của Agent (trong bảng điều khiển hoặc thông qua Agents API). Đối với các chiến dịch cổ điển không có Agent, ai_mode vẫn đọc và ghi giá trị đã lưu như trước đây.

Các trường bot được hợp nhất, chúng không ghi đè. Gửi cài đặt bot dưới dạng các khóa có dấu chấm ("bot.instructions": "...") hoặc dưới dạng một đối tượng lồng nhau ("bot": { "instructions": "..." }) — cả hai đều ghi theo từng lá, vì vậy các trường bạn bỏ qua sẽ giữ nguyên giá trị hiện tại của chúng. bot.instructions, bot.goal, bot.rules và bot.personality đều có thể chỉnh sửa theo cách này, cũng như mọi cài đặt bot khác được liệt kê trong Các trường cấu hình bot. Điều tương tự cũng áp dụng cho test_bot, frequency và follow_up_config.

Để thay thế toàn bộ cấu hình bot — xóa bất kỳ trường nào bạn không gửi — hãy sử dụng bot_replace (hoặc test_bot_replace) với đối tượng hoàn chỉnh. Bạn không thể kết hợp thay thế và hợp nhất cho cùng một đối tượng trong một yêu cầu; điều đó sẽ trả về 400.

Một vài trường được thiết lập thông qua một khóa chuyên dụng thay vì ghi trực tiếp: sử dụng list_id cho danh sách liên hệ, event_id cho loại sự kiện (hoặc event_ids, một mảng có thứ tự các ID loại sự kiện, để cho phép AI đặt nhiều loại — loại đầu tiên là mặc định; một mảng trống sẽ hủy liên kết tất cả), và contact_ids (một mảng các ID liên hệ) cho các liên hệ của chiến dịch. Các mục trong cơ sở kiến thức được quản lý thông qua FAQs API, không phải endpoint này.

Các thẻ thay thế, chúng không hợp nhất. Hãy gửi tags dưới dạng mảng hoàn chỉnh và nó sẽ trở thành bộ thẻ của chiến dịch — xem Thẻ chiến dịch để biết các trường và các điểm cuối (endpoint) dùng để thêm hoặc chỉnh sửa một thẻ đơn lẻ.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Xóa chiến dịch #

DELETE /campaigns/{campaignId}

Xóa vĩnh viễn một chiến dịch. Hành động này không thể hoàn tác — nếu bạn có thể cần lại chiến dịch này, hãy lưu trữ nó thay thế.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true
}

Sao chép chiến dịch #

POST /campaigns/{campaignId}/duplicate

Tạo một bản sao của chiến dịch với tất cả các cài đặt được giữ nguyên. Bản sao sẽ bắt đầu ở trạng thái đã tắt và tên của nó sẽ có thêm hậu tố (copy), vì vậy nó sẽ không bao giờ gửi tin nhắn cho đến khi bạn bật nó lên một cách rõ ràng.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Phản hồi

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Các bản sao trùng lặp trong cùng một tài khoản.

Bật hoặc tắt chiến dịch #

PATCH /campaigns/{campaignId}/enabled

Bật hoặc tắt một chiến dịch. Một chiến dịch bị tắt sẽ ngừng tương tác với các liên hệ nhưng vẫn giữ nguyên tất cả cấu hình của nó.

Các trường yêu cầu

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Lưu trữ hoặc khôi phục chiến dịch #

PATCH /campaigns/{campaignId}/archived

Lưu trữ hoặc khôi phục một chiến dịch. Các chiến dịch đã lưu trữ sẽ bị ẩn khỏi danh sách chiến dịch mặc định nhưng vẫn giữ lại tất cả dữ liệu của chúng và có thể được khôi phục bất cứ lúc nào.

Các trường yêu cầu

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Cập nhật cấu hình bot #

PUT /campaigns/{campaignId}/bot-config

Đây là cách an toàn để thay đổi các cài đặt riêng lẻ của bot. Mỗi trường bạn gửi sẽ được hợp nhất vào cấu hình bot hiện có, vì vậy bất kỳ trường nào bạn bỏ qua đều được giữ nguyên. Hãy sử dụng cách này thay vì endpoint cập nhật chiến dịch bất cứ khi nào bạn chỉ muốn tinh chỉnh một phần của bot.

Các khóa trường chỉ được sử dụng chữ cái, số, dấu gạch dưới và dấu gạch nối.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Các trường cấu hình bot #

Tất cả các trường của bot đều là tùy chọn. Chỉ gửi những trường bạn muốn thiết lập. Bất kỳ trường bot bổ sung nào ngoài những trường được liệt kê ở đây đều được chấp nhận và lưu trữ nguyên trạng.

Thiết lập giờ hoạt động của bot #

PUT /campaigns/{campaignId}/active-hours

Thiết lập lịch trình khả dụng của bot. Ngoài các khoảng thời gian được cấu hình, bot sẽ không tự động trả lời. Thao tác này sẽ ghi vào trường availability của cấu hình bot.

Các trường yêu cầu

Mỗi ngày trong tuần chứa một khoảng thời gian duy nhất hoặc một mảng các khoảng thời gian. Một khoảng thời gian có start_time và end_time theo định dạng HH:MM 24 giờ.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Liệt kê các hàm tùy chỉnh của chiến dịch #

GET /campaigns/{campaignId}/custom-functions

Trả về các hàm tùy chỉnh được liên kết với chiến dịch này, được phân giải thành các định nghĩa đầy đủ. Các hàm tùy chỉnh là các hành động HTTP bên ngoài mà bot có thể gọi trong khi hội thoại — ví dụ: kiểm tra hàng tồn kho trong cửa hàng của bạn hoặc tạo bản ghi trong CRM của bạn.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Phản hồi

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Liên kết một hàm tùy chỉnh với một chiến dịch #

POST /campaigns/{campaignId}/custom-functions

Liên kết một hàm tùy chỉnh hiện có với chiến dịch này để bot có thể gọi hàm đó trong khi trò chuyện. Việc liên kết một hàm đã được liên kết sẽ không có tác dụng gì.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Hủy liên kết một hàm tùy chỉnh khỏi một chiến dịch #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Việc hủy liên kết một hàm chưa được liên kết sẽ không có tác dụng gì.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Liên kết một nguồn cơ sở tri thức với một chiến dịch #

POST /campaigns/{campaignId}/kb-sources

Liên kết một nguồn cơ sở tri thức (được tạo thông qua API FAQ) với chiến dịch này để bot có thể sử dụng nguồn đó khi trả lời. Việc liên kết một nguồn đã được liên kết sẽ không có tác dụng gì.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Hủy liên kết một nguồn cơ sở tri thức khỏi một chiến dịch #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Việc hủy liên kết một nguồn chưa được liên kết sẽ không có tác dụng gì.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Liên kết một máy chủ MCP với một chiến dịch #

POST /campaigns/{campaignId}/mcp-servers

Liên kết một máy chủ MCP với chiến dịch này, cho phép bot truy cập vào các công cụ của máy chủ đó trong cuộc trò chuyện. Việc liên kết một máy chủ đã được liên kết sẽ không có tác dụng gì.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Hủy liên kết máy chủ MCP khỏi chiến dịch #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Việc hủy liên kết một máy chủ chưa được liên kết sẽ không có tác dụng gì.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Thư viện phương tiện của chiến dịch #

Thư viện phương tiện lưu trữ hình ảnh, video, tài liệu và ghi chú thoại mà bot có thể gửi trong cuộc trò chuyện.

Liệt kê thư viện phương tiện của chiến dịch #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url là một URL đã ký được ghi lại tại thời điểm tải lên — nó có thể đã hết hạn vào thời điểm bạn đọc lại; bảng điều khiển sẽ ký lại URL đó theo yêu cầu.

Tải lên một mục phương tiện #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Phản hồi

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Cập nhật mục phương tiện #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Chỉ chỉnh sửa siêu dữ liệu của mục — để thay thế tệp, hãy xóa mục đó và tải lên tệp mới.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Xóa mục phương tiện #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Việc xóa một mục đã không còn tồn tại sẽ không thực hiện hành động nào.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Phản hồi

{ "success": true, "deleted": true }

Thẻ chiến dịch #

Thẻ chiến dịch là một nhãn mà bạn dạy bot áp dụng cho liên hệ trong cuộc trò chuyện — hot-lead, not-interested, booked-a-call. Mỗi thẻ có ba phần:

Tên thẻ phải là duy nhất trong một chiến dịch. Bot áp dụng thẻ theo tên, vì vậy hai mục nhập có cùng một tên sẽ không có kết quả xác định.

Thiết lập tất cả các thẻ của chiến dịch #

PUT /campaigns/{campaignId} với một mảng tags.

Thao tác này thay thế các thẻ của chiến dịch bằng chính xác những gì bạn gửi, giống như những gì tab Thẻ trên bảng điều khiển thực hiện khi bạn lưu. Hãy gửi mảng hoàn chỉnh mỗi lần — một thẻ bạn bỏ qua là một thẻ bạn đã xóa. Gửi [] sẽ xóa tất cả các thẻ.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Đọc lại các thẻ bằng GET /campaigns/{campaignId}.

Thêm một thẻ #

POST /campaigns/{campaignId}/tags

Thêm một thẻ đơn lẻ mà không cần gửi lại phần còn lại. Sử dụng cách này khi bạn đang thêm vào một tập hợp mà bạn không xây dựng trong yêu cầu này.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Việc đăng cùng một thẻ hai lần sẽ không có tác dụng gì ở lần thứ hai. Đăng cùng một tag_id với tên hoặc mô tả khác sẽ thêm một mục nhập thứ hai thay vì chỉnh sửa mục nhập đầu tiên — hãy sử dụng điểm cuối bên dưới để chỉnh sửa tại chỗ.

Cập nhật hoặc xóa một thẻ #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Các địa chỉ này nhắm đến một mục nhập bằng tag_id của nó, vì vậy chúng chỉ hoạt động trên các thẻ được tạo bằng một mục nhập. Nếu một thẻ không có tag_id, hãy thay đổi nó bằng PUT /campaigns/{campaignId} cho toàn bộ mảng ở trên.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Một tagId không nằm trong chiến dịch sẽ trả về 404 với "Tag not found in campaign tags".

Chuyển đổi các kênh của chiến dịch #

POST /campaigns/{campaignId}/channels

Thêm hoặc xóa các kênh khỏi mảng enabled_channels của chiến dịch mà không cần gửi lại toàn bộ mảng — an toàn hơn so với PUT /campaigns/{campaignId} khi có thứ khác có thể đang chỉnh sửa chiến dịch cùng lúc.

Gửi một lần chuyển đổi đơn lẻ hoặc một loạt — không gửi cả hai trong cùng một yêu cầu:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Các kênh hợp lệ: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Điều này chỉ thay đổi các kênh mà chiến dịch quảng bá — nó không quyết định ai sẽ trả lời một kênh. Xem Các loại chiến dịch ở trên và Định tuyến chiến dịch đến các kênh đến ở bên dưới để biết thêm chi tiết.

Comment-to-DM (Instagram và Facebook) #

Comment-to-DM biến bình luận trên bài đăng của bạn thành một cuộc trò chuyện riêng tư: ai đó bình luận, bot sẽ gửi cho họ một tin nhắn trực tiếp (DM), và chiến dịch sẽ tiếp tục cuộc trò chuyện từ đó. Tính năng này được cấu hình hoàn toàn thông qua đối tượng chiến dịch, vì vậy không có phần nào chỉ dành riêng cho giao diện người dùng.

Trước tiên hãy kết nối Trang Facebook — xem Kết nối Kênh. Sau đó, thiết lập các trường bên dưới bằng PUT /campaigns/{campaignId}.

Chiến dịch phải ở trạng thái Live. Việc theo dõi bình luận chỉ chọn các chiến dịch có status là Live (không phân biệt chữ hoa chữ thường — xem Các loại chiến dịch). Bất kỳ trạng thái nào khác sẽ âm thầm vô hiệu hóa nó, và một trạng thái tự tạo như "Active" hiện sẽ bị từ chối kèm theo 400 thay vì được lưu trữ. Các trạng thái hợp lệ bao gồm Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent và Failed.

Các trường

Xóa một trường

Các trường này bị xóa thay vì được đặt thành null khi bạn gửi null, vì vậy bot sẽ quay lại các giá trị mặc định của nó: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Một khóa không xác định sẽ từ chối toàn bộ yêu cầu. PUT /campaigns/{campaignId} xác thực toàn bộ nội dung dựa trên danh sách cho phép. Một khóa không được nhận dạng sẽ trả về 400 cho toàn bộ yêu cầu — nó không bị âm thầm bỏ qua, và không có trường nào khác trong nội dung đó được ghi lại.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Phản hồi hiển thị trên bình luận yêu cầu tính năng trả lời bình luận trong gói của bạn. Nếu không có tính năng này, DM vẫn được gửi và phản hồi công khai sẽ bị bỏ qua.

Tối ưu hóa chiến dịch bằng AI #

POST /campaigns/{campaignId}/optimize

Chạy cùng một quy trình viết lại AI như các luồng Tối ưu hóa (Optimize) và phản hồi không thích (thumbs-down) trên bảng điều khiển: nhận phản hồi của bạn, viết lại các hướng dẫn của bot và chuẩn bị kết quả dưới dạng một bản nháp mới để bạn xem xét.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Phản hồi (202 — quá trình viết lại chạy trong nền)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Hãy thăm dò GET /campaigns/{campaignId} và theo dõi test_bot.status: nó sẽ chuyển sang "Optimizing" ngay lập tức, sau đó quay lại "Draft" khi quá trình viết lại hoàn tất trong test_bot. Từ đó, nó hoạt động giống như bất kỳ bản nháp nào trên bảng điều khiển — hãy xem xét nó, sau đó xuất bản trên bảng điều khiển để đưa vào hoạt động. Một 409 có nghĩa là một quá trình tối ưu hóa đang chạy cho chiến dịch này.

Việc tối ưu hóa sẽ tốn tín dụng, giống như bất kỳ hoạt động AI nào khác trên tài khoản của bạn.

Gán một liên hệ vào chiến dịch #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Đưa một liên hệ hiện có vào chiến dịch và, nếu bạn yêu cầu, sẽ gửi ngay tin nhắn mở đầu của chiến dịch đó. Đây là cách để gửi mẫu WhatsApp đã được phê duyệt của chiến dịch cho một liên hệ: mẫu mà chiến dịch được phê duyệt cùng thuộc về chiến dịch đó, vì vậy nó không xuất hiện trong thư viện Templates API và không thể được gửi thông qua /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Phản hồi

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Tín dụng: Việc gửi tin nhắn mở đầu trong chiến dịch WhatsApp được tính phí như bất kỳ lượt gửi mẫu nào, dựa trên quốc gia của người nhận và danh mục của mẫu. Trên các kênh khác, tin nhắn mở đầu là một tin nhắn gửi đi thông thường.

Định tuyến chiến dịch đến các kênh tiếp nhận #

Các điểm cuối này quản lý chiến dịch nào sẽ trả lời các liên hệ mới, chưa xác định trên một kênh. Ưu tiên sử dụng Entry Points cho các tích hợp mới (xem ghi chú trong phần Các loại chiến dịch) — các điểm cuối này vẫn hữu ích khi làm việc với các chiến dịch định tuyến theo cách cũ và để giải quyết xung đột quyền sở hữu kênh giữa hai chiến dịch tiếp nhận.

Gán chiến dịch cho các kênh tiếp nhận #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Phản hồi

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels chỉ liệt kê các kênh đã được định tuyến thực tế đến chiến dịch này; failed liệt kê bất kỳ kênh nào không được định tuyến. Nếu mọi kênh được yêu cầu đều thất bại, bản thân yêu cầu đó cũng sẽ thất bại.

Xóa định tuyến tiếp nhận của chiến dịch #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Phản hồi

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Kích hoạt lại một chiến dịch không hoạt động #

POST /campaigns/{campaignId}/reactivate

Khôi phục chiến dịch từ Ended, Completed, Paused hoặc Draft và yêu cầu lại các kênh của chiến dịch đó. Chỉ hoạt động trên các chiến dịch Incoming from Unknown Contacts hoặc Combined — một chiến dịch đã Live sẽ được coi là thành công và không cần thực hiện thêm thao tác nào.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Một kênh đã được yêu cầu bởi tác nhân của một chiến dịch khác sẽ hiển thị trong channelsBlockedByConflict thay vì làm thất bại toàn bộ cuộc gọi — hãy sử dụng dừng chiến dịch đến đang xung đột bên dưới để giải phóng kênh trước nếu bạn muốn chiến dịch này tiếp quản kênh đó. Một 400 sẽ được trả về cho loại chiến dịch không hỗ trợ kích hoạt lại, hoặc trạng thái không nằm trong các trạng thái không hoạt động ở trên.

Dừng chiến dịch đến đang xung đột #

POST /campaigns/{campaignId}/stop-incoming

Giải phóng các kênh của chiến dịch này khỏi bất kỳ chiến dịch KHÁC nào hiện đang nắm giữ chúng, để chiến dịch này có thể yêu cầu chúng tiếp theo. Đây là phiên bản REST của những gì bảng điều khiển thực hiện tự động khi bạn khởi chạy một chiến dịch đến vào một kênh mà người khác đã trả lời.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels trả về trống khi chiến dịch này đã sở hữu mọi kênh mà nó quảng cáo — không có gì để tiếp quản.

Ước tính chi phí #

Ước tính chi phí khởi chạy một chiến dịch trước khi bạn gửi nó.

Ước tính chi phí mẫu WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode là "credits" trên làn đường WhatsApp được quản lý. Trên làn đường mà Meta tính phí trực tiếp cho Tài khoản WhatsApp Business của riêng bạn, costPerContact, subtotal và totalTemplateCost sẽ trả về null — không bao giờ là 0, điều này sẽ được hiểu là miễn phí — vì không có số liệu tín dụng nào để báo cáo.

Ước tính chi phí SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

SMS luôn được gửi qua tài khoản Twilio của riêng bạn (xem nhà cung cấp SMS), vì vậy khoản này luôn được Twilio tính phí trực tiếp — estimatedCostUsd là ước tính về hóa đơn Twilio đó, không phải là khoản phí tín dụng.

Kiểm tra giới hạn #

Kiểm tra giới hạn trước khi bạn khởi chạy, thay vì phát hiện ra sau khi gửi thất bại.

Kiểm tra theo phạm vi chiến dịch #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — liệu việc khởi chạy hoặc lên lịch cho chiến dịch này có vượt quá giới hạn nhắn tin bằng AI-credit của tài khoản của bạn hay không.

GET /campaigns/{campaignId}/limits/messaging — liệu việc đó có vượt quá giới hạn nhắn tin hàng ngày của tài khoản của bạn hay không.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Phản hồi (không vượt quá giới hạn)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Một 400 sẽ được trả về thay thế khi vượt quá giới hạn, với lý do nằm trong error.

Các kiểm tra theo phạm vi tài khoản #

GET /campaigns/limits/campaigns — liệu bạn đã đạt đến giới hạn tạo chiến dịch hàng tháng của gói đăng ký hay chưa.

GET /campaigns/limits/contacts — liệu bạn đã đạt đến giới hạn liên hệ của gói đăng ký hay chưa.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Tổng số liệu thống kê chiến dịch #

GET /campaigns/stats/totals

Tổng số tin nhắn đã gửi và phản hồi cho mọi chiến dịch VÀ mọi tác nhân AI trên tài khoản của bạn, trong một khoảng thời gian trượt — cùng những con số mà trang danh sách chiến dịch hiển thị bên cạnh mỗi hàng, trong một lệnh gọi thay vì một yêu cầu cho mỗi chiến dịch.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent là một bản tổng hợp riêng, không phải là tổng của byCampaign — lưu lượng truy cập của một tài khoản sử dụng AI-Agent có thể không bao gồm bất kỳ chiến dịch nào, vì vậy nếu không có nó, dữ liệu này sẽ không hiển thị ở đây.

Kiểm tra chiến dịch trong môi trường thử nghiệm (playground) #

Môi trường thử nghiệm cho phép bạn thực hiện cuộc trò chuyện với bot của chiến dịch mà không cần chạm vào kênh thực hoặc liên hệ thực. Đây là cùng một môi trường sandbox như bảng điều khiển thử nghiệm trên dashboard, và nó hoàn toàn khả dụng thông qua API.

Quy trình là: tạo một liên hệ thử nghiệm ẩn, gửi tin nhắn, sau đó thăm dò chiến dịch để lấy phản hồi của bot. Các phản hồi được tạo không đồng bộ, vì vậy chúng sẽ xuất hiện trong test_messages trên chiến dịch thay vì trong nội dung phản hồi.

Playground chạy dựa trên các khoản tín dụng chi phí API. Một cuộc trò chuyện thử nghiệm bắt đầu bằng khóa API sẽ bị tính phí theo mức giá tin nhắn AI thông thường, giống như một phản hồi thực tế, và xuất hiện trong lịch sử sử dụng của bạn như một mục thông thường. Việc thử nghiệm từ bảng điều khiển vẫn được miễn phí. Sự khác biệt này là có chủ đích: một lần chạy thử nghiệm thực hiện công việc AI tương tự như một lần chạy trực tiếp, vì vậy một playground API không giới hạn sẽ là cách để chạy AI không giới hạn bằng chi phí của người khác.

Bước 1 - Tạo liên hệ thử nghiệm #

POST /campaigns/{campaignId}/try-out/contact

Tạo liên hệ kiểm thử ẩn và liên kết nó với chiến dịch. Tất cả các trường nội dung đều là tùy chọn; bất kỳ trường nào bạn bỏ trống sẽ sử dụng danh tính mẫu tích hợp sẵn (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Phản hồi

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Bước 2 - Ghi lại tin nhắn đến #

POST /campaigns/{campaignId}/try-out/messages

Thêm tin nhắn vào luồng kiểm thử. Hãy gửi tin nhắn của khách truy cập vào đây trước để nó xuất hiện trong lịch sử hội thoại mà bot sẽ đọc.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Bước 3 - Yêu cầu bot phản hồi #

POST /campaigns/{campaignId}/try-out/test-message

Gửi tin nhắn đến quy trình AI. Đây là lệnh gọi thực sự tạo ra phản hồi từ bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Phản hồi

{
  "success": true,
  "data": "Published"
}

"Published" nghĩa là tin nhắn đã được gửi đến quy trình AI. "Ignored" nghĩa là một tin nhắn kiểm thử mới hơn đã thay thế tin nhắn này — trình mô phỏng (playground) sẽ gộp một loạt tin nhắn nhanh thành một phản hồi duy nhất, khoảng bốn giây sau tin nhắn cuối cùng, tương tự như cách một cuộc hội thoại thực tế chờ đợi ai đó hoàn tất việc nhập liệu. Do cửa sổ gộp này, lệnh gọi này mất vài giây để trả về kết quả.

Bước 4 - Đọc phản hồi #

GET /campaigns/{campaignId}

Phản hồi của bot được thêm vào mảng test_messages của chiến dịch. Hãy thăm dò chiến dịch cho đến khi một mục outbound mới xuất hiện.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Đặt lại trình mô phỏng #

POST /campaigns/{campaignId}/try-out/reset

Xóa toàn bộ sandbox: xóa liên hệ kiểm thử, xóa sạch test_messages, và giải phóng các khóa phản hồi của bot. Hãy sử dụng lệnh này giữa các lần chạy kiểm thử.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Các endpoint playground khác #

Lỗi API chiến dịch #

Các endpoint chiến dịch trả về phong bì lỗi tiêu chuẩn:

{
  "success": false,
  "error": "Campaign not found"
}

Các mã chung mà mọi điểm cuối có thể trả về — 401, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

Liên quan #

• Định tuyến kênh đến một chiến dịch — trỏ Instagram, WhatsApp hoặc bất kỳ kênh nào khác đến AI Agent chịu trách nhiệm phản hồi, sử dụng Điểm truy cập (Entry Points).
• Tạo mẫu theo dõi bằng AI — bắt đầu một tác vụ nền để viết các mẫu theo dõi WhatsApp cho chiến dịch.
• API Câu hỏi thường gặp (FAQs) — quản lý các mục hỏi đáp mà chiến dịch của bạn sử dụng.
• Truy cập API — tạo khóa API của bạn.
• Xác thực — tất cả các cách để truyền khóa của bạn.