Tin nhắn

/v1/messages

Sử dụng nút messages để gửi tin nhắn văn bản, file phương tiện, thông tin liên hệ, 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.

Hãy xem các hướng dẫn sau để biết thông tin về những loại tin nhắn cụ thể mà bạn có thể 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ệ và thông tin vị trí, Tin nhắn tương tác, Mẫu tin nhắn, Mẫu tin nhắn có chứa file phương tiện và Mẫu tin nhắn tương tác.

Trước khi bạn bắt đầu

Bạn cần:

• Tự xác thực và nhận mã xác thực để truy cập vào dịch vụ. Hãy xem tài liệu về Đăng nhập và xác thực để biết thêm thông tin về cách thực hiện việc này.
• Để xác minh tài khoản WhatsApp mà bạn muốn nhắn tin và lấy ID người dùng WhatsApp, hãy xem tài liệu về Contacts để biết thêm thông tin về cách thực hiện việc này.
• Đáp ứng các yêu cầu của dịch vụ kiểm soát giới hạn đối với tin nhắn.

Giới hạn

• Các loại tin nhắn sau được hỗ trợ: văn bản, mẫu tin nhắn, hình ảnh, tài liệu và âm thanh.
• Tin nhắn văn bản có thể dài tối đa 4096 ký tự.

Tạo

Bạn gửi tin nhắn bằng cách thực hiện lệnh gọi POST đến nút /messages bất kể loại tin nhắn là gì. Nội dung của phần nội dung tin nhắn JSON khác nhau tùy vào từng loại tin nhắn (văn bản, hình ảnh, v.v.).

Thông số

Sau đây là những thông số chính được dùng trong yêu cầu POST /messages:

Đối tượng văn bản

Đối tượng file phương tiện

Đối với API Tại chỗ, ID đối tượng file phương tiện được trả về khi bạn tải thành công file phương tiện lên ứng dụng WhatsApp Business tại chỗ/tham chiếu qua điểm cuối media.

Đối tượng Contacts

Bên trong contacts, bạn có thể lồng các đối tượng sau: addresses, emails, name, org, phone và urls. Các đối tượng số nhiều sẽ được gói vào một mảng như minh họa trong ví dụ ở bên dưới.

Ví dụ về một đối tượng contacts có các đối tượng số nhiều được lồng bên trong:

"contacts": [
    {
        "addresses": [
            {
                "city": "city name",
                "country": "country name",
                "country_code": "code",
                "state": "Contact's State",
                "street": "Contact's Street",
                "type": "Contact's Address Type",
                "zip": "Contact's Zip Code"
            }
        ],
        "birthday": "birthday",
        "emails": [
            {
                "email": "email",
                "type": "HOME"
            },
            {
                "email": "email",
                "type": "WORK"
            }
        ],
        "name": {
            "first_name": "first name value",
            "formatted_name": "formatted name value",
            "last_name": "last name value",
            "suffix": "suffix value"
        },
        "org": {
            "company": "company name",
            "department": "dep name",
            "title": "title"
        },
        "phones": [
            {
                "phone": "Phone number",
                "wa-id": "WA-ID value",
                "type": "MAIN"
            },
            {
                "phone": "Phone number",
                "type": "HOME"
            },
            {
                "phone": "Phone number",
                "type": "WORK"
            }
        ],
        "urls": [{
            "url": "some url",
            "type": "WORK"
        }]
    }
]

Đối tượng Location

Đối tượng Template

Bên trong template, bạn có thể lồng đối tượng components và language.

Đối tượng Components

Bên trong components, bạn có thể lồng đối tượng parameters. Ngoài ra, bạn có thể đặt type là button.

Đối tượng Parameter

Loại nút

Bên trong đối tượng components, bạn có thể đặt type là button. Sau đây là các thông số nút:

Ví dụ về loại button có sub_type quick_reply:

 {
    "type": "button",
    "sub_type": "quick_reply",
    "index": 0,
    "parameters": 
     [{
    	"type": "payload",
    	"payload": "Yes-Button-Payload"
     }]
 } 

Ví dụ về loại button có sub_type copy_code

    
 { 
    "type": "button", 
    "sub_type": "copy_code", 
    "index": 0, 
    "parameters": 
    [{ 
     "type": "coupon_code", 
     "coupon_code": "DISCOUNT20" 
    }] 
 }

Đối tượng Hsm

Đối tượng Interactive

Đối tượng Action

Ví dụ

Tin nhắn thoại:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

Tin nhắn tài liệu, sử dụng filename:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "filename": "your-document-filename"
  }
}

Tin nhắn tài liệu, sử dụng link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }     
    }
}

Tin nhắn video, sử dụng link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
    }
  }
}

Tin nhắn văn bản:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

Tin nhắn tương tác (danh sách):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

Tin nhắn tương tác (nút trả lời):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

Tin nhắn tương tác (Tin nhắn gồm một sản phẩm và Tin nhắn gồm nhiều sản phẩm):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "
      
      _id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

Tin nhắn tương tác (Tin nhắn gồm nhiều sản phẩm):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"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": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

Tin nhắn tương tác (Tin nhắn chứa danh mục):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "catalog_message",
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "name": "catalog_message",
      	"parameters":{ 
      	  "thumbnail_product_retailer_id": "product-SKU-in-catalog"
      	}
     },  
    }
}

Tin nhắn tương tác (Quy trình):

{
  "recipient_type": "individual",
  "to": "{{Recipient-WA-ID}}",
  "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": { # optional
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}

Sau đây là ví dụ về payload trong một phản hồi; các đối tượng meta và lỗi được lược bỏ cho ngắn gọn.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

Nếu yêu cầu thành công, bạn sẽ nhận được một phản hồi kèm ID tin nhắn. Nếu yêu cầu đó trả về một phần errors, hãy kiểm tra tin nhắn khởi điểm và sửa các lỗi đó trước khi gửi lại yêu cầu. Để biết thêm thông tin về lỗi, hãy xem phần Mã lỗi của ứng dụng WhatsApp Business tại chỗ/tham chiếu và Mã trạng thái HTTP.

Nếu yêu cầu bị giữ lại để đánh giá chất lượng, phản hồi sẽ chứa một thuộc tính message_status kèm theo thông báo cho biết rằng tin nhắn không được gửi ngay mà sẽ được gửi hoặc bị hủy bỏ sau khi hệ thống xác thực chất lượng. Thuộc tính này sẽ chỉ tồn tại nếu tin nhắn bị giữ lại.

    {
      "messages": [{ 
        "id": "message-id",
        "message_status": "Message has been held because quality assessment is pending",
      }]    
    }
    

Định dạng trong tin nhắn văn bản

WhatsApp cho phép một số định dạng trong tin nhắn. Để định dạng tất cả hoặc một phần tin nhắn, hãy sử dụng các ký hiệu định dạng sau:

Hiệu quả

Trong ngữ cảnh này, hiệu quả biểu thị số lượng tin nhắn có thể được gửi trong một giây cụ thể bất kỳ thông qua ứng dụng WhatsApp Business tại chỗ/tham chiếu. Hiệu quả tối đa có thể đạt được phụ thuộc vào nhiều yếu tố. Yếu tố quan trọng nhất là lựa chọn thiết lập ứng dụng của bạn và việc tin nhắn đang được gửi cho người dùng mới hay người dùng hiện tại - quy trình thiết lập phiên mã hóa sẽ lâu hơn một chút khi nhắn tin cho người dùng mới.

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

Tìm hiểu thêm

• Tài liệu về Đăng nhập và xác thực
• Tài liệu về Contacts
• Mã lỗi của ứng dụng WhatsApp Business tại chỗ/tham chiếu
• Mã trạng thái HTTP