API Đám mây
Quay lại Tiếng Việt
Tài liệu này đã được cập nhật.
Bản dịch sang Tiếng Việt chưa hoàn tất.
Cập nhật bằng tiếng Anh: 1 tháng 2

Nền tảng WhatsApp Business > API Đám mây > Tài liệu tham khảo

Tin nhắn

Sử dụng điểm cuối /PHONE_NUMBER_ID/messages để gửi tin nhắn văn bản, tin nhắn có chứa file phương tiện, tin nhắn có chứa thông tin liên hệ, tin nhắn có chứa thông tin vị trí và tin nhắn tương tác, cũng như các mẫu tin nhắn cho khách hàng. Tìm hiểu thêm về tin nhắn bạn có thể gửi.

Điểm cuốiXác thực

/PHONE_NUMBER_ID/messages

(Xem phần Lấy ID số điện thoại)

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

Mỗi tin nhắn có một ID riêng (WAMID). Bạn có thể theo dõi trạng thái tin nhắn qua Webhooks bằng WAMID. Bạn cũng có thể dùng điểm cuối messages để đánh dấu một tin nhắn đến là đã đọc. WAMID này không được dài quá 128 ký tự.

Với API Đám mây, bạn không có cách nào để kiểm tra rõ ràng xem một số điện thoại có ID WhatsApp hay không. Để gửi tin nhắn cho ai đó qua API Đám mây, bạn chỉ cần gửi trực tiếp đến số điện thoại của khách hàng – sau khi khách hàng đã chọn tham gia. Hãy xem ví dụ trong Tài liệu tham khảo, Tin nhắn.

Đối tượng message

Để gửi tin nhắn, trước tiên, bạn phải tập hợp một đối tượng message có chứa nội dung bạn muốn gửi. Dưới đây là các thông số được dùng trong đối tượng message:

TênMô tả (Nhấp vào mũi tên ở cột bên trái để xem các tùy chọn được hỗ trợ.)

audio

đối tượng

Bắt buộc khi type=audio.

Một đối tượng media có chứa âm thanh.

biz_opaque_callback_data

chuỗi

Không bắt buộc.

Một chuỗi tùy ý, hữu ích để theo dõi.


Ví dụ: bạn có thể chuyển ID mẫu tin nhắn vào trường này để theo dõi hành trình của khách hàng kể từ tin nhắn đầu tiên mà bạn gửi. Sau đó, bạn có thể theo dõi ROI của các loại mẫu tin nhắn khác nhau để xác định loại hiệu quả nhất.


Bất kỳ ứng dụng nào mà bạn đăng ký trường webhook messages trên Tài khoản WhatsApp Business đều có thể lấy chuỗi này, vì đây là chuỗi có trong đối tượng statuses của phần tải dữ liệu webhook.


API Đám mây không xử lý trường này, mà chỉ trả về trong webhook thông báo đã gửi/đã phân phối/đã đọc.


Tối đa 512 ký tự.


Chỉ API Đám mây.

contacts

đối tượng

Bắt buộc khi type=contacts.

Một đối tượng contacts.

context

đối tượng

Bắt buộc nếu trả lời bất kỳ tin nhắn nào trong cuộc trò chuyện.

Một đối tượng có chứa ID của tin nhắn trước đó mà bạn đang trả lời. Ví dụ:


{"message_id":"MESSAGE_ID"}


Chỉ API Đám mây.

document

đối tượng

Bắt buộc khi type=document.

Một đối tượng media có chứa tài liệu.

hsm

đối tượng

Chứa đối tượng hsm. Chúng tôi đã ngừng sử dụng tùy chọn này trong v2.39 của API Tại chỗ. Thay vào đó, hãy sử dụng đối tượng template.


Chỉ API Tại chỗ.

image

đối tượng

Bắt buộc khi type=image.

Một đối tượng media có chứa hình ảnh.

interactive

đối tượng

Bắt buộc khi type=interactive.

Một đối tượng interactive. Thành phần của mỗi đối tượng interactive thường tuân theo một mẫu nhất quán, đó là: header, body, footer và action.

location

đối tượng

Bắt buộc khi type=location.

Một đối tượng location.

messaging_product

chuỗi

Bắt buộc

Dịch vụ nhắn tin được dùng cho yêu cầu. Hãy sử dụng "whatsapp".


Chỉ API Đám mây.

preview_url

boolean

Bắt buộc nếu type=text.

Cho phép xem trước URL trong tin nhắn văn bản - Xem phần Gửi URL trong tin nhắn văn bản. Đây là trường không bắt buộc nếu tin nhắn không có URL. Giá trị:false (mặc định), true.


Chỉ API Tại chỗ. Người dùng API Đám mây có thể sử dụng chức năng tương tự với trường preview_url bên trong đối tượng văn bản.

recipient_type

chuỗi

Không bắt buộc.

Hiện tại, bạn chỉ có thể gửi tin nhắn cho cá nhân. Hãy đặt trường này thành individual.


Giá trị mặc định: individual

status

chuỗi

Trạng thái của tin nhắn. Bạn có thể sử dụng trường này để đánh dấu tin nhắn là read. Hãy xem hướng dẫn dưới đây để biết thông tin:


sticker

đối tượng

Bắt buộc khi type=sticker.

Một đối tượng media có chứa nhãn dán.


API Đám mây: Hỗ trợ nhãn dán gửi đi dạng tĩnh và có hoạt ảnh của bên thứ ba, ngoài mọi loại nhãn dán gửi đến. Nhãn dán tĩnh cần phải có kích thước 512x512 pixel và không được vượt quá 100KB. Nhãn dán có hoạt ảnh phải có kích thước 512x512 pixel và không được vượt quá 500KB.


API Tại chỗ: Chỉ hỗ trợ nhãn dán gửi đi dạng tĩnh của bên thứ ba, ngoài mọi loại nhãn dán gửi đến. Nhãn dán tĩnh cần phải có kích thước 512x512 pixel và không được vượt quá 100KB. Không hỗ trợ nhãn dán có hoạt ảnh.

template

đối tượng

Bắt buộc khi type=template.

Một đối tượng template.

text

đối tượng

Bắt buộc đối với tin nhắn văn bản.

Một đối tượng text.

to

chuỗi

Bắt buộc.

ID WhatsApp hoặc số điện thoại của khách hàng mà bạn muốn gửi tin nhắn. Hãy xem phần Định dạng số điện thoại.


Nếu cần, người dùng API Tại chỗ có thể lấy số này bằng cách gọi điểm cuối contacts.

type

chuỗi

Không bắt buộc.

Loại tin nhắn mà bạn muốn gửi. Nếu bạn bỏ qua, giá trị mặc định sẽ là text.

Dưới đây là các đối tượng được lồng vào trong đối tượng message:

Đối tượng contacts

NameDescription

addresses

object

Optional.

Full contact address(es) formatted as an addresses object. The object can contain the following fields:

streetstring – Optional. Street number and name.

citystring – Optional. City name.

statestring – Optional. State abbreviation.

zipstring – Optional. ZIP code.

countrystring – Optional. Full country name.

country_codestring – Optional. Two-letter country abbreviation.

typestring – Optional. Standard values are HOME and WORK.

birthday

Optional.

YYYY-MM-DD formatted string.

emails

object

Optional.

Contact email address(es) formatted as an emails object. The object can contain the following fields:

emailstring – Optional. Email address.

typestring – Optional. Standard values are HOME and WORK.

name

object

Required.

Full contact name formatted as a name object. The object can contain the following fields:

formatted_namestring – Required. Full name, as it normally appears.

first_namestring – Optional*. First name.

last_namestring – Optional*. Last name.

middle_namestring – Optional*. Middle name.

suffixstring – Optional*. Name suffix.

prefixstring – Optional*. Name prefix.


*At least one of the optional parameters needs to be included along with the formatted_name parameter.

org

object

Optional.

Contact organization information formatted as an org object. The object can contain the following fields:

companystring – Optional. Name of the contact's company.

departmentstring – Optional. Name of the contact's department.

titlestring – Optional. Contact's business title.

phones

object

Optional.

Contact phone number(s) formatted as a phone object. The object can contain the following fields:

phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number.

typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK.

wa_idstring – Optional. WhatsApp ID.

urls

object

Optional.

Contact URL(s) formatted as a urls object. The object can contain the following fields:

urlstring – Optional. URL.

typestring – Optional. Standard values are HOME and WORK.

Đối tượng interactive

TênMô tả

action

đối tượng

Bắt buộc.

Hành động bạn muốn người dùng thực hiện sau khi đọc tin nhắn.

body

đối tượng

Không bắt buộc đối với loại product. Bắt buộc đối với các loại tin nhắn khác.

Một đối tượng có chứa nội dung tin nhắn.


Đối tượng body chứa trường sau đây:

textchuỗi - Bắt buộc nếu có nội dung. Nôi dung tin nhắn. Hỗ trợ biểu tượng cảm xúc và markdown. Độ dài tối đa: 1.024 ký tự.

footer

đối tượng

Không bắt buộc. Một đối tượng có chứa phần dưới cùng của tin nhắn.


Đối tượng footer chứa trường sau đây:

textchuỗi - Bắt buộc nếu có phần dưới cùng. Nội dung phần dưới cùng. Hỗ trợ biểu tượng cảm xúc, markdown và liên kết. Độ dài tối đa: 60 ký tự.

header

đối tượng

Bắt buộc đối với loại product_list. Không bắt buộc đối với các loại khác.

Nội dung tiêu đề hiển thị ở đầu tin nhắn. Bạn không thể đặt tiêu đề nếu đối tượng interactive thuộc loại product. Hãy xem đối tượng header để biết thêm thông tin.

type

đối tượng

Bắt buộc.

Loại tin nhắn tương tác mà bạn muốn gửi. Giá trị được hỗ trợ:


  • button: Dùng cho Nút trả lời.
  • catalog_message: Dùng cho Tin nhắn về danh mục.
  • list: Dùng cho Tin nhắn có chứa danh sách.
  • product: Dùng cho Tin nhắn về một sản phẩm.
  • product_list: Dùng cho Tin nhắn về nhiều sản phẩm.
  • flow: Dùng cho Tin nhắn về quy trình.

Dưới đây là các đối tượng được lồng vào trong đối tượng interactive:

Đối tượng action

TênMô tả

button

chuỗi

Bắt buộc đối với Tin nhắn có chứa danh sách.

Nội dung nút. Không được là chuỗi trống và phải là duy nhất trong tin nhắn. Hỗ trợ biểu tượng cảm xúc, không hỗ trợ markdown.


Độ dài tối đa: 20 ký tự.

buttons

mảng đối tượng

Bắt buộc đối với Nút trả lời.

Đối tượng button có thể chứa các thông số sau:


  • type: loại duy nhất được hỗ trợ là reply (đối với Nút trả lời)
  • title: Tiêu đề nút. Không được là chuỗi trống và phải là duy nhất trong tin nhắn. Hỗ trợ biểu tượng cảm xúc, không hỗ trợ markdown. Độ dài tối đa: 20 ký tự.
  • id: Thông tin nhận dạng duy nhất cho nút. ID này được trả về trong webhook khi người dùng nhấp vào nút. Độ dài tối đa: 256 ký tự.

Bạn có thể có tối đa 3 nút. Khi đặt ID, bạn không được để khoảng trắng ở đầu hoặc ở cuối.

catalog_id

chuỗi

Bắt buộc đối với Tin nhắn về một sản phẩm và Tin nhắn về nhiều sản phẩm.

Thông tin nhận dạng duy nhất của danh mục trên Facebook được liên kết với Tài khoản WhatsApp Business của bạn. Bạn có thể truy xuất ID này qua Công cụ quản lý thương mại trên Meta.

product_retailer_id

chuỗi

Bắt buộc đối với Tin nhắn về một sản phẩm và Tin nhắn về nhiều sản phẩm.

Thông tin nhận dạng duy nhất của sản phẩm trong danh mục.


Để lấy ID này, hãy chuyển đến Công cụ quản lý thương mại trên Meta và chọn Tài khoản kinh doanh của bạn trên Meta. Bạn sẽ nhìn thấy một danh sách các cửa hàng đã kết nối với tài khoản nêu trên. Hãy nhấp vào cửa hàng bạn muốn sử dụng. Ở bảng điều khiển bên trái, hãy nhấp vào Danh mục > Mặt hàng, rồi tìm mặt hàng bạn muốn nhắc đến. ID của mặt hàng đó hiển thị bên dưới tên mặt hàng.

sections

mảng đối tượng

Bắt buộc đối với Tin nhắn có chứa danh sách và Tin nhắn về nhiều sản phẩm.

Mảng đối tượng section. Tối thiểu là 1, tối đa là 10. Hãy xem đối tượng section.

mode

chuỗi

Không bắt buộc đối với Tin nhắn về quy trình.

Chế độ hiện tại của Quy trình: draft hoặc published.


Giá trị mặc định: published

flow_message_version

chuỗi

Bắt buộc đối với Tin nhắn về quy trình.

Phải là 3.

flow_token

chuỗi

Bắt buộc đối với Tin nhắn về quy trình.

Một mã do doanh nghiệp tạo để dùng làm thông tin nhận dạng.

flow_id

chuỗi

Bắt buộc đối với Tin nhắn về quy trình.

Thông tin nhận dạng duy nhất của Quy trình do WhatsApp cung cấp.

flow_cta

chuỗi

Bắt buộc đối với Tin nhắn về quy trình.

Văn bản trên nút CTA, ví dụ: "Đăng ký".


Độ dài tối đa: 20 ký tự (không có biểu tượng cảm xúc).

flow_action

chuỗi

Không bắt buộc đối với Tin nhắn về quy trình.

navigate hoặc data_exchange. Sử dụng navigate để xác định trước màn hình đầu tiên làm thành phần của tin nhắn. Sử dụng data_exchange cho trường hợp sử dụng nâng cao có màn hình đầu tiên do điểm cuối của bạn cung cấp.


Giá trị mặc định: navigate

flow_action_payload

đối tượng

Không bắt buộc đối với Tin nhắn về quy trình.

Chỉ bắt buộc nếu flow_action là navigate. Đối tượng này có thể chứa các thông số sau:

screenchuỗi - Bắt buộc.id cho màn hình đầu tiên của Quy trình.

datađối tượng – Không bắt buộc. Dữ liệu đầu vào cho màn hình đầu tiên của Quy trình. Phải là đối tượng không trống.

Đối tượng header

TênMô tả

document

đối tượng

Bắt buộc nếu type được đặt thành document.

Chứa đối tượng media cho tài liệu này.

image

đối tượng

Bắt buộc nếu type được đặt thành image.

Chứa đối tượng media cho hình ảnh này.

text

chuỗi

Bắt buộc nếu type được đặt thành text.

Văn bản cho tiêu đề. Định dạng hỗ trợ biểu tượng cảm xúc, nhưng không hỗ trợ markdown.


Độ dài tối đa: 60 ký tự.

type

chuỗi

Bắt buộc.

Loại tiêu đề bạn muốn sử dụng. Giá trị được hỗ trợ:


  • text: Dùng cho Tin nhắn có chứa danh sách, Nút trả lời và Tin nhắn về nhiều sản phẩm.
  • video: Dùng cho Nút trả lời.
  • image: Dùng cho Nút trả lời.
  • document: Dùng cho Nút trả lời.

video

đối tượng

Bắt buộc nếu type được đặt thành video.

Chứa đối tượng media cho video này.

Đối tượng section

TênMô tả

product_items

mảng đối tượng

Bắt buộc đối với Tin nhắn về nhiều sản phẩm.

Mảng đối tượng product. Mỗi phần phải có tối thiểu 1 sản phẩm và tất cả các phần có tối đa 30 sản phẩm.


Mỗi đối tượng product chứa trường sau đây:


  • product_retailer_idchuỗi - Bắt buộc đối với Tin nhắn về nhiều sản phẩm. Thông tin nhận dạng duy nhất của sản phẩm trong danh mục. Để lấy ID này, hãy chuyển đến Công cụ quản lý thương mại trên Meta, chọn tài khoản của bạn và cửa hàng bạn muốn sử dụng. Sau đó, hãy nhấp vào Danh mục > Mặt hàng, rồi tìm mặt hàng bạn muốn nhắc đến. ID của mặt hàng đó hiển thị bên dưới tên mặt hàng.

rows

mảng đối tượng

Bắt buộc đối với Tin nhắn có chứa danh sách.

Chứa danh sách các hàng. Bạn có thể có tổng cộng 10 hàng trong các phần.


Mỗi hàng phải có một tiêu đề (Độ dài tối đa: 24 ký tự) và một ID (Độ dài tối đa: 200 ký tự). Nếu muốn, bạn có thể thêm nội dung mô tả (Độ dài tối đa: 72 ký tự).


Ví dụ:

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

title

chuỗi

Bắt buộc nếu tin nhắn có nhiều phần.

Tiêu đề phần.


Độ dài tối đa: 24 ký tự.

Đối tượng location

NameDescription

latitude

Required.

Location latitude in decimal degrees.

longitude

Required.

Location longitude in decimal degrees.

name

Required.

Name of the location.

address

Required.

Address of the location.

Đối tượng media

Hãy xem phần Lấy ID file phương tiện để biết thông tin về cách lấy ID của đối tượng media. Để biết thông tin về loại file phương tiện được hỗ trợ cho API Đám mây, hãy xem phần Loại file phương tiện được hỗ trợ.

NameDescription

id

string

Required when type is audio, document, image, sticker, or video and you are not using a link.


The media object ID. Do not use this field when message type is set to text.

link

string

Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server).

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.


Do not use this field when message type is set to text.


Cloud API users only:


  • See Media HTTP Caching if you would like us to cache the media asset for future messages.
  • When we request the media asset from your server you must indicate the media's MIME type by including the Content-Type HTTP header. For example: Content-Type: video/mp4. See Supported Media Types for a list of supported media and their MIME types.

caption

string

Optional.


Media asset caption. Do not use with audio or sticker media.


On-Premises API users:

  • For v2.41.2 or newer, this field is is limited to 1024 characters.
  • Captions are currently not supported for document media.

filename

string

Optional.


Describes the filename for the specific document. Use only with document media.


The extension of the filename will specify what format the document is displayed as in WhatsApp.

provider

string

Optional. On-Premises API only.

This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

Đối tượng template

Mô hình định giá theo cuộc trò chuyện đã thay đổi. Hãy xem bài viết Định giá để tìm hiểu cách hoạt động của mô hình định giá theo cuộc trò chuyện mới.

Ngoài ra, chế độ hiển thị của metric_types đã thay đổi kể từ ngày 01/07/2023. Vui lòng xem bảng Dữ liệu phân tích cuộc trò chuyện để biết thêm chi tiết.

NameDescription

name

Required.

Name of the template.

language

object

Required.

Contains a language object. Specifies the language the template may be rendered in.


The language object can contain the following fields:

policystring – Required. The language policy the message should follow. The only supported option is deterministic. See Language Policy Options.

codestring – Required. The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). For all codes, see Supported Languages.

components

array of objects

Optional.

Array of components objects containing the parameters of the message.

namespace

Optional. Only used for On-Premises API.

Namespace of the template.

Dưới đây là các đối tượng được lồng vào trong đối tượng template:

Đối tượng parameter cho nút

TênMô tả (Nhấp vào mũi tên ở cột bên trái để xem các tùy chọn được hỗ trợ.)

type

chuỗi

Bắt buộc.

Cho biết loại thông số của nút.

Tùy chọn được hỗ trợ

  • "payload"
  • "text"

payload

Bắt buộc đối với nút quick_reply.

Ngoài văn bản hiển thị trên nút, phần tải dữ liệu do nhà phát triển xác định sẽ được trả về khi người dùng nhấp vào nút.


Hãy xem ví dụ trong phần Lệnh gọi lại khi nhấp vào nút câu trả lời nhanh.

text

Bắt buộc đối với nút URL.

Hậu tố do nhà phát triển cung cấp được thêm vào URL tiền tố định sẵn trong mẫu.

Đối tượng components

NameDescription (Click the arrow in the left column for supported options.)

type

string

Required.

Describes the component type.


Example of a components object with an array of parameters object nested inside:

 "components": [{
   "type": "body",
   "parameters": [{
                "type": "text",
                "text": "name"
            },
            {
            "type": "text",
            "text": "Hi there"
            }]
      }]

Supported Options

  • header
  • body
  • button

For text-based templates, we only support the type=body.

sub_type

string

Required when type=button. Not used for the other types.

Type of button to create.

Supported Options

  • quick_reply: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
  • url: Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
  • catalog: Refers to a previously created catalog button that allows for the customer to return a full product catalog.

parameters

array of objects

Required when type=button.

Array of parameter objects with the content of the message.

For components of type=button, see the button parameter object.

index

Required when type=button. Not used for the other types.

Position index of the button. You can have up to 10 buttons using index values of 0 to 9.

Đối tượng currency

TênMô tả

fallback_value

Bắt buộc.

Văn bản mặc định nếu không bản địa hóa được.

code

Bắt buộc.

Mã đơn vị tiền tệ theo quy định trong ISO 4217.

amount_1000

Bắt buộc.

Số tiền nhân với 1.000.

Đối tượng date_time

TênMô tả

fallback_value

Bắt buộc.

Văn bản mặc định. Đối với API Đám mây, chúng tôi luôn sử dụng giá trị dự phòng và không cố gắng bản địa hóa bằng các trường không bắt buộc khác.

Đối tượng parameter

TênMô tả

type

chuỗi

Bắt buộc.

Mô tả loại thông số. Giá trị được hỗ trợ:


  • currency
  • date_time
  • document
  • image
  • text
  • video

Đối với mẫu dạng văn bản, các loại thông số được hỗ trợ duy nhất là currency, date_time và text.

text

chuỗi

Bắt buộc khi type=text.

Văn bản của tin nhắn. Giới hạn ký tự khác nhau tùy theo loại thành phần có trong tin nhắn sau đây.


Đối với loại thành phần header:

  • 60 ký tự

Đối với loại thành phần body:

  • 1.024 ký tự nếu có các loại thành phần khác
  • 32.768 ký tự nếu chỉ có loại thành phần body

currency

đối tượng

Bắt buộc khi type=currency.

Một đối tượng currency.

date_time

đối tượng

Bắt buộc khi type=date_time.

Một đối tượng date_time.

image

đối tượng

Bắt buộc khi type=image.

Một đối tượng media thuộc loại image. Không hỗ trợ chú thích khi dùng trong mẫu file phương tiện.

document

đối tượng

Bắt buộc khi type=document.

Một đối tượng media thuộc loại document. Mẫu tin nhắn dạng file phương tiện chỉ hỗ trợ tài liệu PDF. Không hỗ trợ chú thích khi dùng trong mẫu file phương tiện.

video

đối tượng

Bắt buộc khi type=video.

Một đối tượng media thuộc loại video. Không hỗ trợ chú thích khi dùng trong mẫu file phương tiện.

Đối tượng text

TênMô tả

body

chuỗi

Bắt buộc đối với tin nhắn văn bản.

Văn bản của tin nhắn văn bản - có thể chứa URL bắt đầu bằng http:// hoặc https:// và định dạng. Hãy xem các tùy chọn định dạng có sẵn ở đây.


Nếu bạn thêm URL vào văn bản và muốn thêm hộp xem trước vào tin nhắn văn bản (preview_url: true), hãy đảm bảo rằng URL bắt đầu bằng http:// hoặc https:// - ưu tiên URL https://. Bạn phải thêm tên máy chủ vì hệ thống sẽ không so khớp địa chỉ IP.


Độ dài tối đa: 4.096 ký tự

preview_url

boolean

Không bắt buộc. Chỉ API Đám mây.

Đặt thành true để ứng dụng WhatsApp Messenger và WhatsApp Business cố gắng hiển thị một bản xem trước liên kết của bất kỳ URL nào trong chuỗi văn bản body. URL phải bắt đầu bằng http:// hoặc https://. Nếu chuỗi văn bản body có nhiều URL, chỉ URL đầu tiên sẽ hiển thị.


Nếu bạn bỏ qua preview_url hoặc nếu hệ thống không thể truy xuất bản xem trước, một liên kết có thể nhấp vào sẽ hiển thị.


Đối với người dùng API Tại chỗ, hãy sử dụng preview_url trong phần tải dữ liệu tin nhắn cấp cao nhất. Hãy xem phần Thông số.

Đối tượng reaction

TênMô tả

message_id

chuỗi

Bắt buộc.

ID tin nhắn WhatsApp (WAMID) của tin nhắn sẽ hiện cảm xúc. Hệ thống sẽ không gửi cảm xúc nếu:


  • Tin nhắn tồn tại hơn 30 ngày
  • Tin nhắn có chứa cảm xúc
  • Tin nhắn đã bị xóa

Nếu đây là ID của một tin nhắn đã bị xóa, hệ thống sẽ không phân phối tin nhắn đó.

emoji

chuỗi

Bắt buộc.

Biểu tượng cảm xúc sẽ hiện trên tin nhắn.


  • Hỗ trợ tất cả biểu tượng cảm xúc mà thiết bị Android và iOS hỗ trợ.
  • Hỗ trợ biểu tượng cảm xúc được hiển thị.
  • Nếu sử dụng giá trị Unicode của biểu tượng cảm xúc, bạn phải mã hóa giá trị bằng ký tự thoát Java hoặc JavaScript.
  • Chỉ có thể gửi 1 biểu tượng cảm xúc trong một tin nhắn có chứa cảm xúc
  • Dùng chuỗi trống để gỡ biểu tượng cảm xúc đã gửi trước đó.

Tổng quan

Hướng dẫn

Hãy xem các hướng dẫn sau đây để biết đầy đủ thông tin về cách gửi tin nhắn thông qua điểm cuối /messages:

Ví dụ

Tin nhắn văn bản

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "PHONE_NUMBER",
      "type": "text",
      "text": { // the text object
        "preview_url": false,
        "body": "MESSAGE_CONTENT"
        }
    }'

Tin nhắn có chứa cảm xúc

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLM...",
    "emoji": "\uD83D\uDE00"
  }
}'

Tin nhắn có chứa file phương tiện

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM-PHONE-NUMBER-ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA-OBJECT-ID"
  }
}'

Tin nhắn có chứa thông tin vị trí

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": LONG_NUMBER,
    "latitude": LAT_NUMBER,
    "name": LOCATION_NAME,
    "address": LOCATION_ADDRESS
  }
}'

Tin nhắn có chứa thông tin liên hệ

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "contacts",
  "contacts": [{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
    }]
}'

Tin nhắn tương tác

Tin nhắn về một sản phẩm

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "product_retailer_id": "ID_TEST_ITEM_1"
     }
   }
 }'

Tin nhắn về nhiều sản phẩm

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
 "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product_list",
     "header":{
       "type": "text",
       "text": "header-content"
     },
     "body": {
       "text": "body-content"
     },
     "footer": {
       "text": "footer-content"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "sections": [
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         },
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         }
       ]
     }
   }
 }

Tin nhắn về danh mục

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type" : "catalog_message",
    "body" : {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "catalog_message",
      "parameters": { 
        "thumbnail_product_retailer_id": "<Product-retailer-id>"
      }
    }
  }
}'

Tin nhắn về quy trình

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}'

Tin nhắn có chứa danh sách

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "HEADER_TEXT"
    },
    "body": {
      "text": "BODY_TEXT"
    },
    "footer": {
      "text": "FOOTER_TEXT"
    },
    "action": {
      "button": "BUTTON_TEXT",
      "sections": [
        {
          "title": "SECTION_1_TITLE",
          "rows": [
            {
              "id": "SECTION_1_ROW_1_ID",
              "title": "SECTION_1_ROW_1_TITLE",
              "description": "SECTION_1_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_1_ROW_2_ID",
              "title": "SECTION_1_ROW_2_TITLE",
              "description": "SECTION_1_ROW_2_DESCRIPTION"
            }
          ]
        },
        {
          "title": "SECTION_2_TITLE",
          "rows": [
            {
              "id": "SECTION_2_ROW_1_ID",
              "title": "SECTION_2_ROW_1_TITLE",
              "description": "SECTION_2_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_2_ROW_2_ID",
              "title": "SECTION_2_ROW_2_TITLE",
              "description": "SECTION_2_ROW_2_DESCRIPTION"
            }
          ]
        }
      ]
    }
  }
}'

Nút trả lời

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "BUTTON_TEXT"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_1",
            "title": "BUTTON_TITLE_1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_2",
            "title": "BUTTON_TITLE_2"
          }
        }
      ]
    }
  }
}'

Tin nhắn mẫu

Mô hình định giá theo cuộc trò chuyện đã thay đổi. Hãy xem bài viết Định giá để tìm hiểu cách hoạt động của mô hình định giá theo cuộc trò chuyện mới.

Ngoài ra, chế độ hiển thị của metric_types đã thay đổi kể từ ngày 01/07/2023. Vui lòng xem bảng Dữ liệu phân tích cuộc trò chuyện để biết thêm chi tiết.

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

Tin nhắn trả lời

curl -X POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "context": {
     "message_id": "MESSAGE_ID"
  },
  "to": "PHONE_NUMBER",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "your-text-message-content"
  }
}’

Phản hồi thành công

    {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
      ]
    }

Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.

Messages will have one of the following statuses which will be returned in each of the messages objects

  • "message_status":"accepted" : means the message was sent to the intended recipient
  • "message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point

      {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
          "message_status": "accepted",
        }
      ]
    }