API Mẫu tin nhắn WhatsApp #

Các mẫu tin nhắn WhatsApp là những tin nhắn được soạn sẵn đã được phê duyệt để gửi bên ngoài cửa sổ hội thoại 24 giờ thông thường — ví dụ như tin nhắn chào mừng, lời nhắc cuộc hẹn hoặc thông báo nhắc nhở để tương tác lại. API này cho phép bạn liệt kê, tạo, chỉnh sửa, gửi, kiểm tra, xóa và gửi các mẫu tin nhắn theo lập trình.

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 phần Xác thực để biết bốn phương thức được chấp nhận. Các ví dụ trên trang này sử dụng tiêu đề X-API-Key (và một dạng tham số truy vấn cho cURL).

Làm việc với các tài khoản phụ (đại lý) #

Các trạng thái phê duyệt #

Vì các tin nhắn gửi bên ngoài một cuộc hội thoại đang mở phải được WhatsApp xem xét trước, mỗi mẫu tin nhắn đều mang một status phê duyệt:

Chỉ các mẫu tin nhắn draft và rejected mới có thể được chỉnh sửa hoặc gửi (lại). Khi một mẫu tin nhắn đã ở trạng thái approved, nó sẽ bị khóa — hãy tạo một mẫu mới nếu bạn cần thay đổi.

Tự động phê duyệt: Một số kênh không yêu cầu bước xem xét bên ngoài. Các mẫu tin nhắn được tạo hoặc gửi cho một chiến dịch trên các kênh như vậy sẽ được lưu ngay lập tức dưới dạng approved, không có ID nội dung (sid).

Các mẫu trên tài khoản kết nối Meta #

Các điểm cuối này hoạt động theo cùng một cách bất kể tài khoản của bạn đang chạy trên kết nối WhatsApp nào, nhưng những gì xảy ra phía sau chúng lại khác nhau:

• Trên kết nối WhatsApp được quản lý, các mẫu được đăng ký với nhà cung cấp dịch vụ nhắn tin và sid là ID nội dung của nhà cung cấp (HXXXXXXXX…).
• Trên tài khoản có số điện thoại chạy trên Tài khoản WhatsApp Business riêng (một trong hai tùy chọn kết nối Meta), các mẫu được tạo và xem xét trong Tài khoản WhatsApp Business đó và sid là ID mẫu của riêng Meta — một chuỗi số như "3394843740694756". status vẫn sử dụng các giá trị trong bảng trên và rejection_reason vẫn chứa giải thích của Meta.

Có hai điểm cuối bổ sung cho việc này: một để hỏi bạn đang sử dụng kết nối nào và một để đồng bộ hóa danh sách mẫu của bạn với Tài khoản WhatsApp Business. Các mẫu đã tồn tại trong Tài khoản WhatsApp Business sẽ được nhập vào thư viện của bạn thông qua quá trình đồng bộ hóa, vì vậy GET /whatsapp-templates sau đó sẽ liệt kê chúng giống như bất kỳ mẫu nào khác.

Kiểm tra kết nối mà các mẫu đang chạy trên đó #

GET /whatsapp-templates/provider

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

Đồng bộ hóa các mẫu từ Meta #

Làm mới trạng thái phê duyệt của mọi mẫu nằm trong Tài khoản WhatsApp Business của bạn và nhập bất kỳ mẫu nào đã tồn tại ở đó nhưng chưa có trong thư viện của bạn. Bạn có thể gọi lệnh này bao nhiêu lần tùy thích. Trên kết nối được quản lý, không có gì để đồng bộ hóa, vì vậy lệnh gọi này không thực hiện gì cả và chỉ báo cáo số lượng mẫu bạn có.

POST /whatsapp-templates/meta-sync

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

Giao tiếp trực tiếp với Meta (nâng cao) #

Nếu bạn cần một tính năng mà các điểm cuối trên không cung cấp — tiêu đề mẫu, chân trang, nút hoặc một mẫu được xây dựng thủ công hoàn toàn — /v1/meta-templates sẽ chuyển yêu cầu của bạn trực tiếp đến API mẫu của Meta mà không lưu trữ bất kỳ thứ gì trong thư viện mẫu của bạn. Nó chỉ hoạt động trên các tài khoản có số điện thoại chạy trên Tài khoản WhatsApp Business của riêng họ; trên kết nối được quản lý, mọi lệnh gọi sẽ trả về 400 yêu cầu bạn kết nối ứng dụng Meta trước.

Một mẫu bị Meta từ chối sẽ trả về 400 với giải thích của riêng Meta trong error.

Liệt kê các mẫu tin nhắn #

Trả về tất cả các mẫu tin nhắn trong tài khoản của bạn, kèm theo bản tóm tắt nhẹ về từng mẫu.

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Phản hồi

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

Lấy một mẫu tin nhắn #

Trả về thông tin chi tiết đầy đủ của một mẫu đơn, bao gồm các biến, trạng thái và dấu thời gian của mẫu đó.

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

Một mẫu không tồn tại trong tài khoản của bạn sẽ trả về 404 với { "success": false, "error": "Template not found" }.

Tạo mẫu #

Tạo một mẫu cho tin nhắn mở đầu của chiến dịch và gửi đi để phê duyệt trong một bước duy nhất.

POST /whatsapp-templates

Các trình giữ chỗ biến có thể được viết là {{first_name}}, {first_name} hoặc [first_name] — tất cả đều được chuẩn hóa về dạng dấu ngoặc nhọn kép.

Kết quả phụ thuộc vào các kênh của chiến dịch:

• Chiến dịch WhatsApp Business API: nội dung được gửi đi để WhatsApp xem xét. Phản hồi sẽ bao gồm campaign_status (received hoặc pending) và một template_sid.
• Kênh không có bước xem xét bên ngoài: mẫu được lưu trữ và tự động phê duyệt (campaign_status: "approved", template_sid: null).
• Không có kênh WhatsApp trong chiến dịch: không có gì được tạo và campaign_status là not_applicable.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Phản hồi (đã gửi để xem xét)

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Tạo mẫu độc lập #

Tạo một mẫu trong thư viện mẫu của bạn mà không gắn nó với tin nhắn mở đầu của chiến dịch. Đây là bước tạo trong vòng đời mà phần còn lại của trang này tuân theo: tạo mẫu tại đây, chỉnh sửa, gửi để xét duyệt, kiểm tra trạng thái và xóa khi bạn không còn cần đến nữa.

POST /whatsapp-templates/docs

Các mẫu xác thực (mã dùng một lần). WhatsApp không chấp nhận các mẫu xác thực dạng văn bản tự do: nội dung tin nhắn được thiết lập sẵn bởi WhatsApp và mẫu phải có nút “sao chép mã”. Khi bạn tạo một mẫu với category: "authentication", chúng tôi sẽ gửi nó dưới dạng cố định đó cho bạn. body của bạn được giữ làm bản xem trước hiển thị trong ứng dụng, nhưng văn bản mà liên hệ của bạn nhận được là cách diễn đạt riêng của WhatsApp (mã, lời nhắc bảo mật và ghi chú hết hạn sau 10 phút). Hãy khai báo chính xác một biến, ví dụ ["code"], và truyền mã khi bạn gửi (xem trường variables trên Gửi mẫu cho liên hệ). Mã phải ngắn hơn 15 ký tự.

Tôi nên sử dụng phương thức tạo nào? Hãy sử dụng phương thức này khi bạn muốn có một mẫu mà bạn có thể tự chỉnh sửa và gửi. Sử dụng POST /whatsapp-templates (ở trên) khi bạn muốn thiết lập tin nhắn mở đầu của chiến dịch — phương thức đó yêu cầu campaign_id và ghi trực tiếp vào chiến dịch.

Một mẫu được tạo dưới dạng submitted sẽ được gửi để WhatsApp xét duyệt trong nền, vì vậy hãy kiểm tra endpoint trạng thái để biết kết quả thay vì mong đợi kết quả đó trong phản hồi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

Việc thiếu name, language, hoặc body, ngôn ngữ không được hỗ trợ, status không phải là draft hoặc submitted, type hoặc category không xác định, hoặc phần thân vượt quá 1024 ký tự sẽ trả về 400 kèm theo error giải thích. Một campaign_id không thuộc các chiến dịch của bạn sẽ trả về 404.

Cập nhật mẫu #

Chỉnh sửa một mẫu chưa được phê duyệt. Chỉ các mẫu có trạng thái draft hoặc rejected mới có thể được chỉnh sửa. Cung cấp bất kỳ tổ hợp nào của name, body, language và variables — chỉ các trường bạn gửi mới được thay đổi.

PUT /whatsapp-templates/{templateId}

Việc chỉnh sửa không gửi lại mẫu để xét duyệt. Hãy sử dụng endpoint gửi sau đó.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "template_id": "template_abc123"
}

Việc cố gắng chỉnh sửa một mẫu đã approved (hoặc không thể chỉnh sửa vì lý do khác), không gửi trường nào hoặc gửi giá trị không hợp lệ sẽ trả về 400 kèm theo error giải thích.

Gửi mẫu để phê duyệt #

Gửi một mẫu draft hoặc rejected để xét duyệt. Các mẫu trên kênh không yêu cầu xét duyệt bên ngoài sẽ được phê duyệt ngay lập tức; tất cả các mẫu khác sẽ được gửi đến WhatsApp và status được trả về (thường là received hoặc pending) sẽ được lưu trữ trên mẫu đó.

POST /whatsapp-templates/{templateId}/submit

Các mẫu tiếp theo phải khai báo và sử dụng các biến bắt buộc trước khi có thể gửi: một trình giữ chỗ cho tên, cộng với một trình giữ chỗ ngữ cảnh cá nhân cho các mẫu tiếp theo thông minh.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Kiểm tra trạng thái phê duyệt #

Một endpoint nhẹ để thăm dò trạng thái hiện tại của mẫu. Trạng thái được đọc từ bản ghi đã lưu, vốn được làm mới định kỳ trong nền, vì vậy một phê duyệt hoặc từ chối rất gần đây có thể mất một chút thời gian để hiển thị.

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

Xóa mẫu #

Xóa bản ghi mẫu khỏi tài khoản của bạn.

DELETE /whatsapp-templates/{templateId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { 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/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

Gửi mẫu cho một liên hệ #

Gửi một mẫu đã được phê duyệt cho một liên hệ, ngay cả khi không có cuộc hội thoại nào đang mở — hành động này sẽ mở lại phiên trò chuyện. Bạn có thể nhắm mục tiêu đến liên hệ bằng contactId hoặc bằng phoneNumber, và chọn mẫu bằng whatsappTemplateId hoặc bằng templateName.

POST /whatsapp-templates/send

Phần thân của mẫu hỗ trợ thay thế biến nâng cao:

• Các biến cơ bản: {{first_name}}, {{email}}, {{company}}
• Giá trị mặc định: {{first_name|there}} hiển thị there nếu trường trống
• Các phép biến đổi: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
• Kết hợp: {{company|Your Company|uppercase}}

Tín dụng: Việc gửi mẫu sẽ tiêu tốn tín dụng. Chi phí chính xác phụ thuộc vào quốc gia của người nhận và danh mục của mẫu.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Yêu cầu thiếu cả định danh liên hệ và cả hai định danh mẫu sẽ trả về 400. Nếu tài khoản của bạn thiếu thông tin xác thực nhắn tin cần thiết để gửi, phản hồi sẽ là 403.

Tạo hoặc cập nhật mẫu tin nhắn trực tiếp của chiến dịch #

Một cặp endpoint thứ hai cho mẫu tin nhắn mở đầu của chiến dịch, được xác định theo đường dẫn thay vì theo campaign_id trong phần nội dung. Đây là những endpoint cần sử dụng cho một chiến dịch đã hoạt động: không giống như Tạo mẫu tin nhắn ở trên, việc cập nhật tại đây cũng sẽ gửi lại các bản nháp tiếp theo của chiến dịch để xét duyệt, nhờ đó mẫu tin nhắn mở đầu và các tin nhắn tiếp theo luôn đồng bộ với nhau.

POST /whatsapp-templates/campaign/{campaignId} tạo mẫu tin nhắn mở đầu cho chiến dịch. PUT /whatsapp-templates/campaign/{campaignId} chỉnh sửa mẫu đó — chiến dịch phải có sẵn mẫu tin nhắn, nếu không hệ thống sẽ trả về 400.

cURL (tạo)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

Để chỉnh sửa, hãy đổi phương thức thành PUT và sử dụng các trường tương tự — thao tác này sẽ gửi lại mẫu tin nhắn mở đầu (và các bản nháp tiếp theo của chiến dịch, đối với chiến dịch WhatsApp API) để xét duyệt.

Một chiến dịch không thuộc tài khoản của bạn sẽ trả về 404; một chiến dịch thuộc tài khoản khác mà bạn không được ủy quyền sẽ trả về 403. Việc chỉnh sửa một chiến dịch chưa có mẫu tin nhắn sẽ trả về 400.

Gửi mẫu tin nhắn cho một liên hệ hiện có #

Một giải pháp thay thế đơn giản hơn, được xác định theo đường dẫn so với Gửi mẫu tin nhắn cho một liên hệ ở trên: cả mẫu tin nhắn và liên hệ đều phải tồn tại từ trước — không có thông tin nào được tra cứu theo tên hoặc tạo mới ngay lập tức.

POST /whatsapp-templates/{templateId}/send-to-contact

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Tín dụng: Việc gửi tin nhắn sẽ tiêu tốn tín dụng, với mức giá tương tự như endpoint ở trên. Một contactId bị thiếu hoặc không có trong tài khoản của bạn sẽ trả về 403; một templateId không tồn tại sẽ trả về 404.

Gửi hàng loạt mẫu tin nhắn #

Gửi một mẫu tin nhắn cho nhiều liên hệ trong một lần gọi duy nhất, kèm theo bản xem trước chi phí mà bạn có thể hiển thị trước khi xác nhận.

Ước tính chi phí trước #

Trả về chi phí gửi tin, được phân tách theo quốc gia đích, mà không thực sự gửi bất kỳ tin nhắn nào hoặc trừ tín dụng. Giá mẫu được tính theo quốc gia đích, vì vậy giá trị này phải được tính toán ở phía máy chủ dựa trên các liên hệ thực tế thay vì ước tính ở phía máy khách.

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts đếm các id bị thiếu, không thuộc về bạn hoặc không có số điện thoại — ước tính chỉ bao gồm các liên hệ còn lại, vì vậy giá trị khác không có nghĩa là lần gửi thực tế sẽ tiếp cận ít liên hệ hơn so với số lượng bạn đã chọn.

Gửi lô tin nhắn #

Gửi mẫu tin nhắn đến mọi liên hệ trong danh sách, giải quyết mọi biến thông minh cho từng liên hệ và trừ tín dụng cho mỗi lần gửi.

POST /whatsapp-templates/{templateId}/bulk-send

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

Một liên hệ bị lỗi (không tìm thấy, không có trong tài khoản của bạn hoặc lỗi gửi) sẽ bị bỏ qua và được tính vào failed thay vì dừng toàn bộ lô. Một contactIds trống, vượt quá 5000 ID trong một lần gửi (500 ID đối với ước tính) hoặc thiếu templateId sẽ trả về 400.

Thử lại tin nhắn thất bại #

Hai điểm cuối (endpoint) để gửi lại tin nhắn đã thất bại mà không cần tạo bản ghi tin nhắn mới hoặc tốn thêm tín dụng.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template thử lại một tin nhắn mẫu (template) cụ thể — nó sẽ phân giải lại nội dung mẫu từ chiến dịch nếu tin nhắn thất bại chưa chứa nội dung đó. Chỉ những tin nhắn có trạng thái failed và loại template mới có thể được thử lại theo cách này.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry không phụ thuộc vào kênh và hoạt động với bất kỳ tin nhắn không phải mẫu nào bị lỗi (ví dụ: WhatsApp Web), gửi tin nhắn đến đúng đường dẫn dựa trên kênh của tin nhắn đó. Nó chấp nhận trạng thái failed, failed_connection, limit_exceeded hoặc queued_retry.

Cả hai điểm cuối đều không yêu cầu phần thân yêu cầu (request body).

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": "Message retry initiated successfully"
}

Đối với phiên bản không phụ thuộc vào kênh, hãy đổi đường dẫn thành .../msg_abc789/retry. Một tin nhắn có trạng thái không đủ điều kiện để thử lại, hoặc (trên điểm cuối mẫu) không phải là tin nhắn mẫu, sẽ trả về 400. Một liên hệ hoặc tin nhắn bị thiếu sẽ trả về 404.

Hồ sơ WhatsApp Business #

Quản lý hồ sơ WhatsApp Business (giới thiệu, địa chỉ, mô tả, email, trang web, danh mục doanh nghiệp và logo) hiển thị cho các liên hệ trên WhatsApp. Hoạt động trên cả kết nối được quản lý và tài khoản đang chạy Tài khoản WhatsApp Business riêng.

Lưu hồ sơ #

PUT /whatsapp-templates/profile

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

Phản hồi

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

Thiếu phoneNumber, URL trang web không hợp lệ hoặc phoneNumber không được kết nối trên tài khoản của bạn sẽ trả về 400 hoặc 404.

Tải ảnh hồ sơ lên #

Tải xuống hình ảnh từ URL bạn cung cấp và tải nó lên WhatsApp, trả về một handle. Truyền handle đó dưới dạng profilePictureHandle trong lệnh lưu hồ sơ ở trên để đặt làm ảnh — endpoint này chỉ tải hình ảnh lên, nó không tự đặt ảnh.

POST /whatsapp-templates/profile/picture

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

Phản hồi

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

data là handle của hình ảnh đã tải lên. Thiếu phoneNumber hoặc fileUrl, hoặc phoneNumber không có mã thông báo truy cập WhatsApp trong hồ sơ, sẽ trả về 400; một fileUrl không thể truy cập hoặc không hợp lệ sẽ trả về lỗi mô tả lý do tải xuống thất bại.

Kiểm tra trạng thái người gửi #

Thăm dò (và làm mới) trạng thái gửi trực tiếp của một số WhatsApp đã kết nối với nhà cung cấp dịch vụ nhắn tin. Hữu ích để xác nhận một số thực sự có thể gửi tin nhắn trước khi bạn dựa vào nó.

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Phản hồi

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

data là một trong các giá trị ONLINE (đang gửi bình thường), PENDING (vẫn đang được xác minh), hoặc DELETED (nhà cung cấp không còn nhận diện người gửi này — hãy kết nối lại số điện thoại). Một phoneNumber không có thông tin doanh nghiệp WhatsApp trong hồ sơ sẽ trả về 404.

Tạo mẫu tin nhắn theo dõi bằng AI #

Nền tảng có thể tự viết các mẫu tin nhắn theo dõi qua WhatsApp cho chiến dịch của bạn — các tin nhắn nhắc nhở được gửi khi cuộc trò chuyện bị bỏ ngỏ — dựa trên hướng dẫn và mục tiêu của chính chiến dịch đó. Có một endpoint công việc chạy trong nền, cộng với ba endpoint cũ hơn được giữ lại cho các tích hợp hiện có. Tất cả đều sử dụng tín dụng AI.

Bắt đầu công việc tạo mẫu #

POST /campaigns/{campaignId}/template-generation

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

Phản hồi (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

Lệnh gọi trả về ngay khi công việc được xếp hàng. Hãy đọc chiến dịch (GET /campaigns/{campaignId}, xem API Chiến dịch) và theo dõi đối tượng template_generation_status của nó cho đến khi hoàn tất:

Các mẫu được tạo sẽ xuất hiện trên chiến dịch giống như bất kỳ mẫu nào khác, vì vậy chúng sẽ hiển thị trong Danh sách mẫu và vẫn phải trải qua quá trình phê duyệt của WhatsApp trước khi có thể gửi đi. 400 có nghĩa là type không phải là all hoặc cold_only; 404 có nghĩa là chiến dịch không tồn tại hoặc thuộc về một tài khoản khác.

Các Tác nhân (Agents) có một lệnh gọi tương tự, POST /agents/{agentId}/template-generation, giúp viết các tin nhắn theo dõi cho một Tác nhân và hoàn tất ngay trong lệnh gọi như thông thường — xem Tạo tin nhắn theo dõi trong API Tác nhân AI.

Các endpoint tạo mẫu cũ hơn #

Ba endpoint trước đó thực hiện cùng một công việc và được giữ lại để các tích hợp hiện có tiếp tục hoạt động. Mã mới nên sử dụng endpoint công việc ở trên.

Cả ba đều yêu cầu tính năng theo dõi tự động trên tài khoản và đủ tín dụng — 400 cho biết cái nào đang thiếu — và cặp endpoint dành cho chiến dịch sẽ trả về 403 khi chiến dịch thuộc về một tài khoản khác.

Lỗi API mẫu #

Các điểm cuối (endpoint) mẫu trả về cấu trúc lỗi tiêu chuẩn:

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

Một 404 trên các điểm cuối này thường có nghĩa là tài nguyên không được tìm thấy — hoặc là nó không tồn tại hoặc nó thuộc về một tài khoản khác. Một vài điểm cuối (tạo/cập nhật theo phạm vi chiến dịch, và gửi đến một liên hệ hiện có) trả về 403 thay vào đó khi chiến dịch hoặc liên hệ thuộc về người khác thay vì không tồn tại. Một số điểm cuối cũng bao gồm trường error_code phản ánh trạng thái HTTP. Các mã chia sẻ mà mọi điểm cuối có thể trả về — 400, 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.

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 Chiến dịch — quản lý các chiến dịch mà mẫu được đính kèm vào.