WhatsApp Template API

API dành cho nhà phát triển

Gửi mẫu tin WhatsApp đã được duyệt từ chính hệ thống của bạn chỉ với một lệnh gọi API; cuộc trò chuyện sau đó tiếp tục trong MonoChat.

WhatsApp
REST API
Chỉ có API

Cài đặt từ MonoStore Xem trên monochat.ai

Tổng quan

WhatsApp Template API cho phép CRM, ERP, website thương mại điện tử hoặc bất kỳ backend nào của bạn gửi tin nhắn mẫu WhatsApp đã được duyệt đến khách hàng qua MonoChat. Một yêu cầu nêu số WhatsApp gửi đi, số điện thoại của khách hàng, mẫu tin và các biến của mẫu.

Khi khách hàng trả lời, cuộc trò chuyện xuất hiện trong hộp thư MonoChat của bạn như mọi cuộc trò chuyện khác. Ứng dụng không có màn hình riêng: mọi thứ diễn ra qua ba endpoint API.

Điểm nổi bật

Một lệnh gọi API. Gửi mẫu tin theo tên và ngôn ngữ, với các biến tiêu đề, nội dung, nút và carousel được điền từ dữ liệu của bạn.
Thẳng vào cuộc trò chuyện. Mỗi lần gửi trả về id của cuộc trò chuyện và liên kết trực tiếp đến cuộc trò chuyện đó trong MonoChat.
Chào đón khách hàng mới. Nếu số điện thoại chưa phải là khách hàng, khách hàng sẽ được tạo với tên bạn gửi.

Cài đặt và thiết lập

Kết nối số WhatsApp Business của bạn với MonoChat và đảm bảo số đã được xác minh và có các mẫu tin được Meta duyệt.
Cài đặt WhatsApp Template API từ Cài đặt › MonoStore › Ứng dụng, hoặc mở liên kết cài đặt app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Nếu chưa có tài khoản MonoChat, liên kết sẽ cho phép bạn đăng ký trước rồi cài đặt ứng dụng cho bạn.
Tạo token API trong Hồ sơ › Token API. Token chỉ hiển thị một lần, vì vậy hãy sao chép ngay.
Gọi template/list.js để xem các mẫu tin đã được duyệt của bạn và các biến của chúng.
Gọi template/send.js với số của khách hàng và giá trị các biến để gửi mẫu tin đầu tiên của bạn.

Danh sách ứng dụng MonoStore trong cài đặt MonoChat, có WhatsApp Template API

Chi tiết WhatsApp Template API trong MonoStore với nút Cài đặt

ghi chú

Mỗi tin nhắn được tính phí như mọi tin nhắn mẫu gửi từ MonoChat.
URL phương tiện phải truy cập được cho đến khi WhatsApp tải xong tệp.
Chỉ gửi cho khách hàng đã đồng ý nhận tin từ bạn: WhatsApp có thể hạn chế các số bị chặn hoặc bị báo cáo tin nhắn.

Tính năng

Liệt kê mẫu

Các mẫu tin đã được duyệt của một số WhatsApp, kèm ngôn ngữ, danh mục, trạng thái và biến, để hệ thống của bạn biết có thể gửi những gì.

Gửi mẫu

Theo tên và ngôn ngữ của mẫu tin, với các biến tiêu đề, nội dung, nút và carousel. Thiếu một giá trị sẽ dừng việc gửi, nên không có tin nhắn điền dở dang nào đến tay khách hàng.

Giao cho nhân viên

Cung cấp email của một nhân viên và cuộc trò chuyện được mở dưới tên họ.

Tiêu đề phương tiện

Nhận thông tin xác thực tải lên có thời hạn ngắn, đưa hình ảnh, video hoặc tài liệu lên bộ lưu trữ của MonoChat và dùng URL của nó làm tiêu đề của mẫu tin.

Liên kết cuộc trò chuyện

Mỗi lần gửi trả về id phiên, id tin nhắn và một liên kết mở cuộc trò chuyện trong MonoChat.

Lỗi rõ ràng

Một lệnh gọi thất bại sẽ cho biết lỗi gì, ví dụ “Channel not found” hoặc “Variable missing”.

Trước khi bắt đầu

Số WhatsApp Business của bạn đã được kết nối với MonoChat và xác minh. Xem Kênh.
Các mẫu tin bạn muốn gửi đã được Meta duyệt. Mẫu tin là cách để bạn nhắn trước, hoặc tiếp cận khách hàng ngoài khung 24 giờ. Xem Tin nhắn mẫu.
Bạn có token API từ Hồ sơ › Token API. Xem Token API.
Bạn biết tenant slug của mình: phần nằm sau /tenants/ trong địa chỉ MonoChat của bạn. Trong https://app.monochat.ai/tenants/mybusiness thì slug là mybusiness.

Tài liệu tham khảo API

Ứng dụng không có màn hình riêng. Mọi thứ diễn ra qua ba endpoint, mỗi endpoint là một POST với nội dung JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Chức năng
`template/list.js`	Liệt kê các mẫu tin của một trong các số WhatsApp của bạn, kèm các biến của chúng.
`template/send.js`	Gửi một mẫu tin đến khách hàng và trả về liên kết đến cuộc trò chuyện.
`upload/get-token.js`	Cấp thông tin xác thực tải lên có thời hạn ngắn cho hình ảnh, video hoặc tài liệu làm tiêu đề.

Số điện thoại luôn được viết kèm mã quốc gia và không có +, ví dụ 905334445566. Một lệnh gọi thành công trả về 200 cùng dữ liệu của endpoint trong result.

1. Liệt kê mẫu

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Liệt kê mọi mẫu tin của số WhatsApp Business được chỉ định: tên, mã ngôn ngữ, danh mục, các thành phần (tiêu đề, nội dung, chân trang, nút), loại biến và trạng thái duyệt.

Trường	Bắt buộc	Mô tả
`phoneNumber`	có	Số WhatsApp Business của bạn trong MonoChat, kèm mã quốc gia, không có `+`.
`options`	không	Phân trang và bộ lọc, ví dụ `{ "pagination": { "currentPage": 1, "pageItems": 50 } }`.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Phản hồi (rút gọn):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Cách đọc:

name: tên hệ thống mà bạn dùng để gửi mẫu tin.
languageCode: ngôn ngữ để gửi.
category: danh mục WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
components: các phần cấu thành mẫu tin.

Thành phần	Nội dung	Mô tả
`HEADER`	`IMAGE`, `VIDEO`, `DOCUMENT` hoặc văn bản	Với phương tiện, `format` được nêu; các biến xuất hiện trong `variables`.
`BODY`	Văn bản có biến	Nội dung tin nhắn, với các chỗ giữ chỗ như `{{1}}`, `{{2}}`.
`FOOTER`	Văn bản	Thường không có biến.
`BUTTONS`	URL, trả lời nhanh…	Nội dung các nút và biến của chúng, nếu có.

Mẫu tin ví dụ ở trên cần một hình ảnh cho tiêu đề và hai đoạn văn bản cho nội dung (tên khách hàng và tên sản phẩm). Chân trang cố định ("Teşekkürler") và không có nút.

2. Gửi mẫu

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Gửi một mẫu tin đã được duyệt đến khách hàng. Nếu số điện thoại chưa phải là khách hàng, khách hàng sẽ được tạo; cuộc trò chuyện được mở (hoặc dùng lại) và mẫu tin được gửi trong đó.

Trường	Bắt buộc	Mô tả
`phoneNumber`	có	Số WhatsApp Business dùng để gửi. Số này phải được kết nối với MonoChat và xác minh.
`templateMessageName`	có	`name` của mẫu tin, đúng như danh sách trả về.
`languageCode`	có	Ngôn ngữ của mẫu tin, như danh sách trả về (ví dụ `tr-TR`).
`customerPhoneNumber`	có	Số WhatsApp của khách hàng.
`variables`	khi mẫu tin có biến	Giá trị các biến của mẫu tin (xem bên dưới).
`customerFirstName`, `customerLastName`	không	Được dùng khi khách hàng chưa có trong MonoChat.
`agentEmailAddress`	không	Giao cuộc trò chuyện cho nhân viên có email này.

Biến. Mỗi phần tử của mảng variables có một type và danh sách parameters, được đưa ra theo thứ tự các chỗ giữ chỗ của mẫu tin:

`type`	`parameters`
`HEADER`	Biến văn bản của tiêu đề, hoặc URL công khai của hình ảnh, video hoặc tài liệu làm tiêu đề.
`BODY`	`{{1}}`, `{{2}}`, … của nội dung, theo thứ tự.
`BUTTONS`	Một giá trị cho mỗi nút có biến (ví dụ phần động của nút URL hoặc mã giảm giá), theo thứ tự nút.
`CAROUSEL`	Thay cho `parameters`, là mảng `cards` với một phần tử cho mỗi thẻ carousel, mỗi thẻ có `components` riêng.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Thiếu một giá trị sẽ dừng việc gửi với lỗi Variable missing, nên không có tin nhắn điền dở dang nào đến tay khách hàng. FOOTER hiếm khi có biến.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Phản hồi:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

url: mở cuộc trò chuyện trong MonoChat, dành cho những người đã đăng nhập và được phép xem.
sessionId: id của cuộc trò chuyện.
messageId: id của tin nhắn trong MonoChat. Trạng thái đã gửi và đã đọc của tin nhắn hiển thị trong cuộc trò chuyện như mọi tin nhắn khác.

Phương tiện trong mẫu tin. WhatsApp tải phương tiện của tiêu đề từ URL bạn cung cấp, nên URL phải hợp lệ và truy cập công khai được. Các liên kết cần đăng nhập sẽ không hoạt động. Nếu bạn đã tải tệp lên bằng upload/get-token.js, hãy dùng URL của tệp được tạo từ phản hồi đó.

3. Tải phương tiện lên cho tiêu đề

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Khi tiêu đề của mẫu tin là hình ảnh, video hoặc tài liệu, tệp cần có địa chỉ công khai để WhatsApp tải về. Endpoint này cấp cho bạn quyền có thời hạn ngắn để đưa tệp lên bộ lưu trữ của MonoChat.

Trường	Bắt buộc	Mô tả
`fileName`	có	Tên tệp kèm phần mở rộng, ví dụ `product.jpg` hoặc `promo.pdf`.

Tệp luôn được lưu trong thư mục chat-assets của workspace bạn; các ví dụ cũ gửi trường key vẫn hoạt động, không cần giá trị này.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

Phản hồi cho biết nơi đặt tệp và cung cấp thông tin xác thực để thực hiện:

Trường	Mô tả
`bucket`, `region`, `path`	Nơi tệp được đặt.
`temporaryCredentials`	Thông tin xác thực chỉ để tải lên cho đúng đường dẫn đó, có hiệu lực trong 15 phút.
`baseUrl`	Địa chỉ công khai của bộ lưu trữ. URL của tệp là `baseUrl` + `/` + `path`.

Hãy tải tệp lên ngay bằng bất kỳ ứng dụng khách S3 nào với các thông tin xác thực này, rồi truyền URL của tệp làm tham số HEADER khi bạn gửi mẫu tin. Tệp quá lớn hoặc định dạng WhatsApp không hỗ trợ (WhatsApp chấp nhận các định dạng hình ảnh, video và PDF phổ biến) sẽ thất bại.

Ví dụ: mẫu tin có tiêu đề hình ảnh

Giả sử bạn có một mẫu tin đã được duyệt new_product_announcement với tiêu đề hình ảnh và hai biến nội dung (tên khách hàng và tên sản phẩm), và bạn muốn gửi cho một khách hàng.

Liệt kê các mẫu tin. Gọi template/list.js với số WhatsApp của bạn và tìm new_product_announcement. Các thành phần của nó cho thấy một biến IMAGE trong tiêu đề và hai biến TEXT trong nội dung.
Tải hình ảnh lên. Gọi upload/get-token.js với { "fileName": "urun.jpg" }, tải tệp lên bằng thông tin xác thực được trả về và tạo URL của nó từ baseUrl và path.
Gửi mẫu tin. Gọi template/send.js với URL của tệp làm tham số HEADER và ["Ayşe", "XYZ Telefon"] làm các tham số BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Nếu mẫu tin có biến cho nút, bạn sẽ thêm một phần tử BUTTONS theo cách tương tự.
Mở cuộc trò chuyện. url trong phản hồi mở cuộc trò chuyện; khi khách hàng trả lời, cuộc trò chuyện tiếp tục trong hộp thư MonoChat của bạn.

Lỗi

Một lệnh gọi thất bại trả về mã trạng thái lỗi và một thông báo cho biết đã xảy ra lỗi gì. Hãy ghi lại các thông báo này trong hệ thống của bạn và hiển thị thông báo có ý nghĩa cho người dùng khi cần.

Thông báo	Nguyên nhân
`phoneNumber field is required`	`template/list.js` được gọi mà không có `phoneNumber`.
`phoneNumber, templateMessageName, customerPhoneNumber fields are required`	Thiếu một trường bắt buộc của `template/send.js`.
`Channel not found`	`phoneNumber` không phải là số WhatsApp của workspace bạn.
`Channel is not verified`	Số WhatsApp đã được kết nối nhưng chưa được xác minh.
`Template message not found`	Không có mẫu tin đã duyệt nào với tên và ngôn ngữ đó trên số này. Hãy kiểm tra chính tả và `languageCode`.
`Template message is not approved`	Mẫu tin tồn tại nhưng chưa được Meta duyệt.
`Variable missing: …`	`variables` không khớp với mẫu tin, ví dụ mẫu tin cần hai giá trị nội dung nhưng bạn chỉ gửi một.
`Agent user not found`	Không có nhân viên nào có email trong `agentEmailAddress`.
`Customer Channel not found`	Không thể tạo hoặc tìm thấy danh tính WhatsApp của khách hàng.

Các mã trạng thái HTTP bạn có thể gặp:

401 Unauthorized: thiếu header Authorization: Bearer <API_TOKEN>, hoặc token sai hoặc đã hết hạn. Hãy dùng token hợp lệ từ tài khoản của bạn.
403 Forbidden: token không có quyền truy cập workspace hoặc ứng dụng này, ví dụ do tenant slug sai.
404 Not Found: địa chỉ endpoint sai. Hãy kiểm tra đường dẫn đầy đủ /api/<slug>/custom-functions/template-app/api/....
500 Internal Server Error: sự cố bất ngờ trong MonoChat hoặc ở nhà cung cấp WhatsApp, hoặc WhatsApp từ chối (số không có trên WhatsApp, khách hàng đã chặn bạn, giới hạn chất lượng hoặc tốc độ). Hãy thử lại sau và liên hệ hỗ trợ MonoChat nếu sự cố vẫn tiếp diễn.

Ảnh chụp màn hình

Gửi mẫu tin WhatsApp đã duyệt từ hệ thống CRM, ERP hoặc thương mại điện tử chỉ với một lệnh gọi API qua MonoChat

Danh sách các mẫu tin WhatsApp đã duyệt cùng các biến của chúng

Gửi mẫu tin đến một số mới sẽ tự động tạo khách hàng

Một mẫu tin được gửi bằng nhiều ngôn ngữ

Các mẫu tin có tiêu đề hình ảnh, video, tài liệu và PDF

Câu hỏi thường gặp

WhatsApp Template API có giao diện người dùng không?

Không. Đây là ứng dụng chỉ có API với ba endpoint: liệt kê mẫu tin, gửi mẫu tin và lấy thông tin xác thực tải lên cho tiêu đề phương tiện.

Tôi cần gì trước khi có thể sử dụng?

Một số WhatsApp Business đã kết nối với MonoChat và xác minh, các mẫu tin được Meta duyệt, và một token API từ Hồ sơ › Token API.

Điều gì xảy ra khi khách hàng trả lời?

Cuộc trò chuyện xuất hiện trong hộp thư MonoChat của bạn như mọi cuộc trò chuyện khác. Mỗi lần gửi cũng trả về liên kết trực tiếp đến cuộc trò chuyện, và bạn có thể giao cho một nhân viên qua email.

Tôi có thể gửi đến số chưa phải là khách hàng không?

Có. Nếu số điện thoại chưa phải là khách hàng, khách hàng sẽ được tạo với tên bạn gửi.

Tin nhắn mẫu có chi phí bao nhiêu?

Mỗi tin nhắn được tính phí như mọi tin nhắn mẫu gửi từ MonoChat. Meta định giá mẫu tin theo danh mục và quốc gia của người nhận; hãy dùng công cụ tính chi phí gửi tin hàng loạt WhatsApp để ước tính một đợt gửi.

Tổng quan​

Điểm nổi bật​

Cài đặt và thiết lập​

Tính năng​

Liệt kê mẫu​

Gửi mẫu​

Giao cho nhân viên​

Tiêu đề phương tiện​

Liên kết cuộc trò chuyện​

Lỗi rõ ràng​

Trước khi bắt đầu​

Tài liệu tham khảo API​

1. Liệt kê mẫu​

2. Gửi mẫu​

3. Tải phương tiện lên cho tiêu đề​

Ví dụ: mẫu tin có tiêu đề hình ảnh​

Lỗi​

Ảnh chụp màn hình​

Câu hỏi thường gặp​

WhatsApp Template API có giao diện người dùng không?​

Tôi cần gì trước khi có thể sử dụng?​

Điều gì xảy ra khi khách hàng trả lời?​

Tôi có thể gửi đến số chưa phải là khách hàng không?​

Tin nhắn mẫu có chi phí bao nhiêu?​

Liên quan​