API Phân tích & Báo cáo #

Các endpoint chỉ đọc này cho phép bạn lấy dữ liệu hoạt động của tài khoản vào bảng điều khiển và báo cáo của riêng bạn: số lượng sự kiện tin nhắn, mức tiêu thụ tín dụng, chi phí AI, cùng các biểu đồ và thông tin chi tiết giống như trên bảng điều khiển trong ứng dụng. Hướng dẫn này bao gồm:

• Tóm tắt — các bộ đếm lưu lượng tin nhắn (đã gửi, đã giao, đã đọc, đã trả lời, đã đặt lịch, liên hệ được tạo, tín dụng).
• Tín dụng — sổ cái chi tiết, được phân trang về việc sử dụng tín dụng với tổng số và phân tích chi tiết.
• Chi phí AI — tổng hợp chi tiêu cho AI theo ngày.
• Chuỗi chỉ số — chuỗi thời gian sẵn sàng cho biểu đồ của một hoặc nhiều chỉ số, được nhóm theo chiến dịch, kênh, AI Agent hoặc số điện thoại.
• Kết quả hội thoại — các hội thoại theo thời gian, được nhóm theo thẻ liên hệ mà chúng mang (các thẻ đóng mà tác nhân của bạn áp dụng).
• Chi phí hội thoại: chi phí tín dụng trung bình của một hội thoại mà AI tự xử lý so với hội thoại mà nhóm của bạn đã tham gia.
• Thông tin chi tiết trên bảng điều khiển và Thông tin chi tiết AI trên bảng điều khiển — dữ liệu đầy đủ đằng sau bảng điều khiển trong ứng dụng, bao gồm các bản tóm tắt do AI viết.
• Hoạt động thực thể — dòng thời gian của một liên hệ, giao dịch hoặc tác vụ cụ thể.
• Số lượng sự kiện tổng hợp — định dạng camelCase kế thừa của Tóm tắt được giữ lại cho các tích hợp hiện có.

Mỗi endpoint trên trang này cần một phạm vi chính xác, không được dùng cả hai: chỉ truyền tối đa một trong campaign_id (kế thừa) hoặc agent_id tại nơi endpoint chấp nhận. Gửi cả hai sẽ trả về 400, và một id không có trong tài khoản của bạn sẽ trả về 404 thay vì 403, để id của các tài khoản khác không thể đoán được.

Chỉ có hai endpoint lọc theo thẻ liên hệ. tag_ids (với tag_match) được hỗ trợ bởi Thông tin chi tiết trên Dashboard và Tổng số sự kiện — đây là hai endpoint mà bộ lọc Tất cả thẻ trên dashboard trong ứng dụng sử dụng. Tóm tắt, Chuỗi chỉ số và Kết quả hội thoại xác thực tham số (danh sách id sai định dạng vẫn trả về 400) nhưng không áp dụng nó: bạn sẽ nhận lại các con số trên toàn bộ tài khoản mà không có thông báo lỗi nào cho biết điều đó. Đừng đọc tổng số chưa lọc như là tổng số đã lọc theo thẻ.

Tất cả các đường dẫn bên dưới đều tương đối so với URL cơ sở của API:

https://api.youraiconnector.com/v1

Mọi yêu cầu đều phải được xác thực. Xem Xác thực để biết bốn phương thức được chấp nhận. Các ví dụ ở đây sử dụng tiêu đề X-API-Key (và một dạng tham số truy vấn cho cURL).

Phạm vi ngày #

Cả ba điểm cuối đều chấp nhận các bộ lọc ngày tùy chọn giống nhau:

Ngày được hiểu theo giờ UTC. Phạm vi mặc định là 30 ngày qua và được giới hạn ở mức 366 ngày — phạm vi rộng hơn sẽ trả về 400. from không được sau to.

Cờ truncated #

Các điểm cuối Tóm tắt và Tín dụng giới hạn số lượng bản ghi mà một yêu cầu duy nhất quét. Nếu phạm vi của bạn đủ bận để đạt đến giới hạn đó, phản hồi sẽ bao gồm "truncated": true. Khi bạn thấy nó, các con số dựa trên quá trình quét một phần — hãy thu hẹp phạm vi ngày của bạn (hoặc phân trang với cửa sổ nhỏ hơn) để có được số liệu đầy đủ.

Tóm tắt lưu lượng tin nhắn #

Trả về các bộ đếm sự kiện tin nhắn tổng hợp cho tài khoản của bạn, dưới dạng tổng phạm vi và chuỗi theo ngày. Mỗi ngày trong phạm vi xuất hiện trong by_date — những ngày không có hoạt động sẽ được điền bằng 0. Tùy chọn lọc theo một chiến dịch duy nhất với campaign_id.

GET /analytics/summary

cURL

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}

Mỗi mục trong by_date có các trường bộ đếm giống như totals, cộng thêm một date.

Nếu bạn truyền một campaign_id không thuộc tài khoản của mình, phản hồi sẽ là 404 với { "success": false, "error": "Campaign not found" }.

Sử dụng tín dụng #

Trả về mức sử dụng tín dụng trong phạm vi: một danh sách phân trang các bản ghi riêng lẻ, cộng với tổng phạm vi và phân tích theo lý do và theo chiến dịch.

GET /analytics/credits

Điều chỉnh so với tiêu thụ: Các thay đổi số dư như tiền thưởng, gia hạn gói và hiệu chỉnh được loại trừ khỏi totals và các phân tích — chúng không phải là mức tiêu thụ thực tế. Chúng vẫn xuất hiện trong danh sách records, được gắn cờ với "is_adjustment": true.

Tổng và phân tích chỉ xuất hiện trên trang đầu tiên (khi không có cursor nào được cung cấp). Trên các trang sau, totals, by_reason, by_reason_cost và by_campaign được trả về dưới dạng null — chỉ có mảng records là tiếp tục. Điều này tránh việc phải quét lại toàn bộ phạm vi cho mỗi trang.

cURL

curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.

Phản hồi (trang đầu tiên)

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}

Ghi chú trường:

• amount — tín dụng bị tính phí cho bản ghi. Bằng không đối với các bản ghi được tính phí vào khóa API nhà cung cấp của riêng bạn.
• is_adjustment — true cho các thay đổi số dư (được loại trừ khỏi tổng/phân tích).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — chỉ được điền trên các bản ghi được tính phí vào khóa API nhà cung cấp của riêng bạn; bằng không hoặc null nếu không.
• is_test — true cho các lần chạy thử nghiệm/playground, vốn không bao giờ bị tính phí.
• next_cursor — con trỏ cho trang tiếp theo, hoặc null khi không còn bản ghi nào nữa.

Số dư tín dụng #

GET /users/me/credits — vị thế tín dụng hiện tại của tài khoản của bạn chỉ trong một lần gọi: số dư còn lại để chi tiêu, hạn mức hàng tháng, cùng các cài đặt tự động nạp tiền và tín dụng thấp. Mức sử dụng tín dụng ở trên là lịch sử; đây là số dư ngay lúc này. Các thành viên trong nhóm muốn gọi hàm này cần có quyền truy cập thanh toán; khóa của chủ sở hữu tài khoản luôn có quyền này.

curl "https://api.youraiconnector.com/v1/users/me/credits?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/users/me/credits", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { balance } = await res.json();

Phản hồi (200)

{
  "success": true,
  "balance": 1837.5,
  "monthly_credits": 2000,
  "used_this_month": null,
  "auto_recharge_enabled": true,
  "low_credit_threshold": null
}

Các đại lý có thể truyền sub_account_id để đọc số dư của tài khoản khách hàng. Bên trong một quy trình tự động hóa, bước Kiểm tra tín dụng sẽ trả về các trường tương tự.

Tổng hợp chi phí AI #

Trả về tổng hợp chi phí AI theo ngày cho tài khoản của bạn. Dữ liệu này đọc các tổng số hàng ngày đã được tổng hợp trước, vì vậy nó rất nhanh ngay cả trong phạm vi dài. Mỗi ngày trong phạm vi đều xuất hiện trong days — những ngày không có hoạt động sẽ được điền bằng không.

GET /analytics/ai-cost

cURL

curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}

Ghi chú trường:

• byok_usd — chi phí được tính vào các khóa API nhà cung cấp của riêng bạn.
• platform_usd — phần chi phí chạy trên nền tảng thay vì khóa của riêng bạn.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — các thành phần chi phí tạo nên total_usd.
• by_provider — chi phí bằng USD được phân loại theo tên nhà cung cấp AI.
• Các số liệu USD chỉ được trả về cho các tài khoản sử dụng khóa nhà cung cấp của riêng họ. Đối với các tài khoản thanh toán bằng tín dụng, mọi trường USD đều bằng 0 và costs_redacted là true (số lượng cuộc gọi vẫn hiển thị).

Chuỗi chỉ số #

Trả về một hoặc nhiều chuỗi thời gian chỉ số trong một lần gọi, tùy chọn nhóm theo tối đa hai chiều — endpoint để liên kết với biểu đồ. Một yêu cầu duy nhất có thể trả lời “số lượng đã gửi và đã trả lời mỗi ngày, theo mỗi kênh, cho chiến dịch này” mà không cần thực hiện mỗi cuộc gọi cho mỗi chiến dịch.

GET /analytics/series

Mỗi phản hồi mang theo một mảng labels (trục thời gian, được điền số 0 trên toàn bộ phạm vi) và một mục trong series cho mỗi nhóm, mỗi mục chứa một mảng cho mỗi chỉ số được yêu cầu căn chỉnh theo labels. Các chuỗi sau limit không bị loại bỏ — chúng được thu gọn thành other_bucket, được tính bằng tổng phạm vi trừ đi chuỗi được trả về, vì vậy một biểu đồ được hiển thị luôn cộng dồn thành các con số thực của bạn; truncated là true bất cứ khi nào điều đó xảy ra.

Nguồn gốc của các con số: sent, delivered, read, và replied đến từ các bản ghi tin nhắn, chứa thông tin kênh và số gửi. booked, contact_created, và credits_spent đến từ luồng sự kiện, không chứa số gửi, vì vậy các chỉ số đó nằm trong nhóm null khi bạn nhóm theo number.

conversations đếm các cuộc hội thoại (phiên chat) đã bắt đầu trong mỗi nhóm, và conversation_credits chi phí của các cuộc hội thoại đó, được tính chính xác như Chi phí cuộc hội thoại. Chia giá trị này cho giá trị kia theo từng nhóm để có chi phí trung bình cho mỗi cuộc hội thoại theo thời gian. Khi bạn nhóm hoặc lọc theo chiến dịch, tác nhân, kênh hoặc số điện thoại, một cuộc hội thoại sẽ được tính vào nhóm mà tin nhắn đầu tiên của nó thuộc về.

Phạm vi ngày của endpoint này bị giới hạn ở 92 ngày (chặt chẽ hơn giới hạn 366 ngày được sử dụng ở nơi khác trên trang này).

cURL

curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}

Ghi chú trường:

• key — danh tính của một chuỗi. Chỉ các khóa cho các chiều group_by được yêu cầu mới hiện diện; một chiều có giá trị không xác định cho một hàng (một tin nhắn không có chiến dịch, một sự kiện không có kênh) sẽ trả về là null thay vì bị loại bỏ, để các chuỗi vẫn cộng dồn thành tổng số.
• other_bucket — null khi không có gì bị thu gọn.
• Endpoint này trả về 503 với "error_code": "analytics_unavailable" khi cơ sở dữ liệu báo cáo không thể phản hồi cho tài khoản của bạn, thay vì một 200 đầy số không — một biểu đồ toàn số không sẽ bị hiểu nhầm là dữ liệu thực.

Kết quả hội thoại #

Trả về kết quả hội thoại trong một phạm vi ngày: số lượng hội thoại theo ngày dưới mỗi thẻ liên hệ, cộng với tổng số cho các phản hồi, lượt đặt lịch, lượt chuyển giao cho con người và các hội thoại mà liên hệ không có thẻ.

Thẻ này là thẻ liên hệ: các thẻ mà AI Agent của bạn áp dụng bằng công cụ gắn thẻ, quy tắc tự động gắn thẻ, API hoặc nhóm của bạn. Đây không phải là nhãn cho mỗi hội thoại. Một hội thoại được tính theo các thẻ mà liên hệ mang tại thời điểm yêu cầu, vì vậy một liên hệ có nhiều thẻ sẽ được tính một lần cho mỗi thẻ, và một thẻ bị xóa sau đó cũng sẽ bị loại bỏ khỏi các ngày trước đó. Hãy cung cấp cho tác nhân của bạn một thẻ kết thúc cho mỗi kết quả (ví dụ: resolved_ai, handoff_asked_for_human) và điểm cuối này sẽ trả về các lý do chứa và chuyển giao theo thời gian.

GET /analytics/outcomes

Truyền group_by=tag để thu gọn trục thời gian và chỉ nhận tổng phạm vi theo thẻ — ở chế độ đó labels trống và mảng counts của mỗi thẻ trống, trong khi total vẫn được điền dữ liệu.

Phạm vi ngày của endpoint này được giới hạn ở 92 ngày.

cURL

curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag_id": "tag_8f2k1", "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag_id": "tag_c91xq", "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag_id": null, "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

Ghi chú trường:

• by_tag[].tag / by_tag[].tag_id — tên và id của thẻ liên hệ; cả hai đều là null trên hàng các hội thoại mà liên hệ không có thẻ. Tối đa 20 thẻ được trả về, ưu tiên thẻ có lưu lượng cao nhất trước.
• totals.sessions — các hội thoại riêng biệt bắt đầu trong phạm vi đó. Đây không phải là tổng của by_tag[].total: một liên hệ có ba thẻ sẽ đóng góp một hội thoại vào ba hàng.
• totals.unresolved — các hội thoại mà liên hệ không có thẻ.
• totals.human_alerted — các hội thoại được chuyển giao cho con người; điều này được ghi lại trong mỗi lần chuyển giao và trước đây chưa từng được hiển thị bởi bất kỳ điểm cuối nào.
• Cùng trạng thái 503/analytics_unavailable như Chuỗi chỉ số khi cơ sở dữ liệu báo cáo không thể phản hồi.

Chi phí hội thoại #

Trả về chi phí trung bình của một hội thoại trong một phạm vi ngày, được phân tách theo cách thức diễn ra. Đây là con số để hiển thị cho khách hàng như là lợi tức đầu tư: chi phí của một hội thoại mà AI tự xử lý, bên cạnh chi phí của một hội thoại mà nhóm của bạn phải tham gia.

GET /analytics/conversation-costs

curl "https://api.youraiconnector.com/v1/analytics/conversation-costs?from=2026-08-26&to=2026-09-24&apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "from": "2026-08-26",
  "to": "2026-09-24",
  "sessions": 564,
  "total_credits": 5957,
  "summary": {
    "contained": { "sessions": 503, "credits": 5168, "avg_credits": 10.2744 },
    "handed_off": { "sessions": 50, "credits": 781, "avg_credits": 15.62 },
    "no_ai": { "sessions": 11, "credits": 8, "avg_credits": 0.7273 }
  },
  "sessions_truncated": false
}

Ghi chú trường:

• Đếm các cuộc hội thoại (phiên chat) đã bắt đầu trong phạm vi, với các khoản tín dụng được tính phí bên trong cửa sổ của mỗi cuộc hội thoại, đã trừ đi các khoản hoàn tiền. Các khoản tín dụng chi tiêu bên ngoài bất kỳ cuộc hội thoại nào (tóm tắt hàng ngày, phí hàng tháng, tự động hóa không được bắt đầu bởi liên hệ, chẳng hạn như webhook hoặc trình kích hoạt RSS) không phải là một phần của nó. Các lần chạy tự động hóa và các bước AI được bắt đầu bởi một liên hệ sẽ được tính vào cuộc hội thoại của liên hệ đó kể từ ngày 26 tháng 9 năm 2026.
• contained: AI đã trả lời và không ai từ nhóm của bạn phải can thiệp. handed_off: ai đó đã gửi tin nhắn sau khi AI đã trả lời, hoặc AI đã cảnh báo cho con người. no_ai: AI không bao giờ trả lời (ví dụ: các cuộc trò chuyện mà nhóm của bạn xử lý khi AI đang tạm dừng).
• Tối đa 20.000 cuộc hội thoại được tính; sessions_truncated là true khi phạm vi chứa nhiều hơn, vì vậy hãy thu hẹp nó lại.
• Cần quyền thanh toán cho các thành viên trong nhóm. Cùng tư thế 503/analytics_unavailable như chuỗi Chỉ số.
• Đối với mỗi liên hệ, sự phân chia tương tự có trong Lấy chi phí liên hệ.

Thông tin chi tiết từ bảng điều khiển #

Trả về toàn bộ dữ liệu bảng điều khiển cho một phạm vi ngày trong một lần gọi: bản đồ nhiệt tỷ lệ phản hồi theo ngày trong tuần và giờ, bảng xếp hạng chiến dịch, khối lượng theo kênh, tổng số chính xác theo kết nối, phân tích số liệu theo ngày (toàn tài khoản, theo kênh và theo số), nguồn gốc liên hệ, thời gian phản hồi hộp thư đến và nguồn cấp hoạt động gần đây. Đây là dữ liệu báo cáo phong phú nhất trên API — nó cung cấp trực tiếp cho bảng điều khiển trong ứng dụng.

GET /analytics/dashboard-insights

Endpoint này sử dụng startDate/endDate (không phải from/to) vì nó chia sẻ cách triển khai với bảng điều khiển trong ứng dụng. Phạm vi được giới hạn ở 92 ngày và sẽ bị cắt bớt, không bị từ chối, khi phạm vi rộng hơn.

Null nghĩa là không khả dụng, không phải bằng không. Một số khối (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) được tính toán từ cơ sở dữ liệu báo cáo và trả về null khi nó không thể phản hồi cho tài khoản của bạn. Đừng hiển thị khối null dưới dạng biểu đồ trống.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Phản hồi (đã rút gọn — dữ liệu này rất lớn; xem Tài liệu tham khảo API để biết lược đồ đầy đủ)

{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}

Ghi chú trường:

• heatmap.buckets[].weekday — 0 là Chủ nhật đến 6 là Thứ Bảy.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — mỗi mục độc lập null khi cơ sở dữ liệu báo cáo không khả dụng cho tài khoản của bạn; mọi khối khác vẫn trả về kết quả.

Thông tin chi tiết từ AI của bảng điều khiển #

Trả về ba thông tin chi tiết ngắn gọn do AI viết về hoạt động nhắn tin của tài khoản trong một phạm vi ngày: một thành công, một điều cần theo dõi và một mẹo — những câu bạn có thể dán trực tiếp vào báo cáo thay vì các con số mà bạn vẫn phải tự diễn giải. Được tạo chỉ từ số liệu tin nhắn của chính tài khoản.

GET /analytics/dashboard-ai-insights

Điểm cuối này áp dụng cho toàn bộ tài khoản — nó không yêu cầu phạm vi chiến dịch hoặc tác nhân.

cURL

curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}

Thiếu startDate hoặc endDate sẽ trả về 400.

Dòng thời gian hoạt động của thực thể #

Trả về hoạt động của một liên hệ, giao dịch hoặc tác vụ duy nhất dưới dạng một dòng thời gian, sắp xếp theo thứ tự mới nhất trước: điều gì đã xảy ra và khi nào, bao gồm tin nhắn, cuộc hẹn, ghi chú và thay đổi trạng thái. Sử dụng nó để trả lời câu hỏi “điều gì đã xảy ra với người này” mà không cần phải kết hợp nhiều điểm cuối danh sách lại với nhau.

GET /analytics/entity-activity

cURL

curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}

Thiếu hoặc không hợp lệ entityType/entityId sẽ trả về 400. Một thực thể không tồn tại trong tài khoản của bạn sẽ trả về 404, vì vậy ID của các tài khoản khác không thể đoán được.

Tổng hợp số lượng sự kiện (cũ) #

Trả về cùng số lượng sự kiện tổng hợp như Tóm tắt lưu lượng tin nhắn, nhưng ở định dạng camelCase (contactCreated thay vì contact_created, byDate thay vì by_date) mà một số tích hợp cũ hơn đã sử dụng. Hãy ưu tiên /analytics/summary cho các tích hợp mới — điểm cuối này chỉ tồn tại để bảng điều khiển trong ứng dụng và API chia sẻ chung một triển khai.

GET /analytics/aggregate

cURL

curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"

Phản hồi

{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}

Tổng hợp tài khoản phụ của đại lý #

Các lỗi API Analytics #

Các endpoint của Analytics trả về cấu trúc lỗi tiêu chuẩn:

{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}

Trên một điểm cuối phân tích, định dạng ngày không hợp lệ hoặc khoảng thời gian nằm ngoài phạm vi sẽ trả về 400, và một campaign_id hoặc agent_id không xác định sẽ trả về 404. Việc gửi cả campaign_id và agent_id trên một điểm cuối chỉ chấp nhận một trong hai cũng là một 400 — hãy truyền tối đa một tham số. Các điểm cuối báo cáo chỉ dành cho PG (Chuỗi chỉ số, Kết quả hội thoại, Tổng hợp đại lý) trả về 503 với "error_code": "analytics_unavailable" thay vì một 200 đầy số 0 khi cơ sở dữ liệu báo cáo không thể phản hồi cho tài khoản của bạn — hãy thử lại sau một thời gian ngắn. 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, hoặc đối với tổng hợp đại lý, tài khoản của bạn không phải là Agency/Dev), 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.

Các bước tiếp theo #

• Xác thực — bốn cách để xác thực một yêu cầu.
• Lỗi & Giới hạn tốc độ — các mã trạng thái và giới hạn 300 yêu cầu/phút.
• API Tác nhân AI — các Tác nhân mà những số liệu này có thể được lọc theo.