API Tại chỗ của Nền tảng WhatsApp Business

Thông báo tin nhắn đã nhận

Khi bạn nhận được một tin nhắn đến, hệ thống sẽ gửi thông báo đến URL Webhook mà bạn đã đặt trong phần cài đặt ứng dụng. Tài liệu này trình bày các loại tin nhắn đến mà bạn có thể nhận được cùng với ví dụ.

Đối tượng của thông báo

Thông báo tin nhắn đã nhận có thể chứa các đối tượng sau:

Khi bạn nhận được một tin nhắn có chứa file phương tiện, ứng dụng API WhatsApp Business sẽ tải file phương tiện đó xuống. Hệ thống sẽ gửi thông báo đến Webhook của bạn sau khi file phương tiện được tải xuống. Thông báo này chứa thông tin xác định đối tượng file phương tiện, đồng thời cho phép bạn tìm và truy xuất đối tượng đó. Hãy sử dụng điểm cuối File phương tiện cùng với id của file phương tiện để truy xuất file phương tiện đó.

Ví dụ về tin nhắn đã nhận

Tin nhắn văn bản

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
      },
    "wa_id": "16315551234"
  }],
  "messages":[{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1518694235",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

Tin nhắn có chứa vị trí tĩnh

{
  "contacts": [{
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
 "messages":[{
   "from":"16315551234",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.9806263495,
      "longitude":-131.9428612257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
 }]
}

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

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "contacts": [{
      "addresses": [{
        "city": "Menlo Park",
        "country": "United States",
        "country_code": "us",
        "state": "CA",
        "street": "1 Hacker Way",
        "type": "WORK",
        "zip": "94025"
      }],
      "birthday": "2012-08-18",
      "emails": [{
        "email": "kfish@fb.com",
        "type": "WORK"
      }],
      "ims": [{
        "service": "AIM",
        "user_id": "kfish"
      }],
      "name": {
        "first_name": "Kerry",
        "formatted_name": "Kerry Fisher",
        "last_name": "Fisher"
      },
      "org": {
        "company": "Meta",
 	"department": "WhatsApp"
      },
      "phones": [{
        "phone": "+1 (940) 555-1234",
        "type": "CELL"
        },
        {
          "phone": "+1 (650) 555-1234",
          "type": "WORK",
          "wa_id": "16505551234"
      }],
      "urls": [{
        "url": "https://www.facebook.com",
        "type": "WORK"
      }]
    }],
    "from": "16505551234",
    "id": "ABGGFlA4dSRvAgo6C4Z53hMh1ugR",
    "timestamp": "1537248012",
    "type": "contacts"
  }]
}

Cài đặt contact_image sẽ trống nếu khách hàng tiêu dùng đang sử dụng iPhone.

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

Tin nhắn có chứa hình ảnh:

{
	"messages": [{
		"from": "16315551234",
		"id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
		"image": {
			"file": "/usr/local/wamedia/shared/b1cf38-8734-4ad3-b4a1-ef0c10d0d683",
			"id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
			"mime_type": "image/jpeg",
			"sha256": "29ed500fa64eb55fc19dc4124acb300e5dcc54a0f822a301ae99944db",
			"caption": "Check out my new phone!",
			"status": "downloaded"
		},
		"timestamp": "1521497954",
		"type": "image"
	}]
}

Kể từ phiên bản 2.49.1, webhook tin nhắn có chứa file phương tiện sẽ chứa trạng thái và ID của file phương tiện đã nhận.

Trạng thái tải xuống

Trạng tháiMô tả

downloaded

File phương tiện đã được tải xuống thành công

retriable

File phương tiện chưa được tải xuống, nhưng có thể thử tải xuống lại bằng điểm cuối thử lại

undownloaded

File phương tiện có thể không được tải xuống

caption là trường không bắt buộc đối với tin nhắn có chứa file phương tiện. Trường này chỉ được thêm khi người dùng đặt chú thích.

Tin nhắn có chứa tài liệu:

{
  "messages": [{
    "from": "16315551234",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1522189546",
    "type": "document",
    "document": {
      "caption": "80skaraokesonglistartist",
			"file": "/usr/local/wamedia/shared/fc233119-733f-49c-bcbd-b2f68f798e33",
			"id": "fc233119-733f-49c-bcbd-b2f68f798e33",
			"mime_type": "application/pdf",
			"sha256": "3b11fa6ef2bde1dd14726e09d3edaf782120919d06f6484f32d5d5caa4b8e",
			"status": "downloaded"
		}
	}]
}

Tin nhắn thoại:

{
    "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "voice",
        "voice": {
            "file": "/usr/local/wamedia/shared/463e/b7ec/ff4e4d9bb1101879cbd411b2",
            "id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
            "mime_type": "audio/ogg; codecs=opus",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710",
            "status": "downloaded"
        }
  }]
}

Tin nhắn có chứa nhãn dán:

{
  "messages":[{
        "from": "16315551234",
        "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
        "timestamp": "1521827831",
        "type": "sticker",
        "sticker": {
            "id": "b1c68f38-8734-4ad3-b4a1-ef0c10d683",
            "metadata": {
                "sticker-pack-id": "463eb7ec-ff4e-4d9b-b110-1879cbd411b2",
                "sticker-pack-name" : "Happy New Year",
                "sticker-pack-publisher" : "Kerry Fisher",
                "emojis": ["🐥", "😃"],
                "ios-app-store-link" : "https://apps.apple.com/app/id3133333",
                "android-app-store-link" : "https://play.google.com/store/apps/details?id=com.example",
                "is-first-party-sticker" : 0 | 1 # integer 
            },
            "mime_type": "image/webp",
            "sha256": "fa9e1807d936b7cebe63654ea3a7912b1fa9479220258d823590521ef53b0710"
        }  
    }]
}

Tin nhắn được tạo từ quảng cáo click đến WhatsApp

{
   "messages":[{
      "from":"12345678",
      "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "image":{
         "id":"b1c68f38-8734-4ad3-b4a1-ef0c10d683",
         "mime_type":"image/jpeg",
         "sha256":"29ed500fa64eb55fc19dc4124acb300e5dcca0f822a301ae99944db"
         "caption": "Check out my product!",
      },
      "timestamp":"1521497954",
      "type":"image",
      "referral" : {
        "headline": "Our new product",
        "body" : "This is a great product",
        "source_type": "<SOURCE_TYPE>",
        "source_id": "<SOURCE_ID>",
        "source_url": "<SOURCE_URL>", //for the moment, this will always be a Facebook owned domain
        "video": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45",
      }     
    }
  }]
}

Xem thêm thông tin về thuộc tính referral.

Ví dụ: Tin nhắn không được hỗ trợ

Bạn có thể nhận được thông báo gọi lại unknown. Dưới đây là ví dụ về loại tin nhắn không được hỗ trợ mà bạn nhận được từ khách hàng.

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
  "messages": [{
		"errors": [{
			"code": 501,
			"details": "Message type is not currently supported",
			"title": "Unknown message type"
		}],
		"from": "16315551234",
		"id": "ABGGFRBzFymPAgo6N9KKs7HsN6eB",
		"timestamp": "1531933468",
		"type": "unknown"
	}]
}

Tin nhắn được chuyển tiếp

Bạn có thể xem liệu tin nhắn mình nhận được đã được chuyển tiếp hay thường xuyên được chuyển tiếp. Dưới đây là thông báo về một tin nhắn được chuyển tiếp:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sOGh7pv13wVJ",
    "text": {
      "body": "Party at Dotty's tonight!"
    },
    "timestamp": "1593068329",
    "type": "text"
  }]
}

Dưới đây là thông báo về một tin nhắn thường xuyên được chuyển tiếp:

{
  "contacts": [{
    "profile": {
      "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  }],
  "messages": [{
    "context": {
      "frequently_forwarded": true
    },
    "from": "16315558011",
    "id": "ABGGFmkiWVVPAgo-sBTHfS3swNIl",
    "timestamp": "1593068225",
    "type": "video",
    "video": {
      "id": "e144be57-12b1-4035-a520-703fcc87ef45",
    "mime_type": "video/mp4",
    "sha256": "02c4e68a4f0d6af5ec6ef02120e20d15f520a4dd473b535abec1aab175c4e8b9"
    }
  }]
}

Đã bật thông báo bảo mật

Nếu bạn đặt thông số show_security_notifications thành true trong phần cài đặt ứng dụng, tất cả thông báo tin nhắn đến sẽ có thông tin sau đây về danh tính của người dùng bên trong đối tượng identity:

{
  "contacts": [{
		"profile": {
			"name": "Kerry Fisher"
		},
		"wa_id": "16315551234"
	}],
   "messages": [{
        "from": "16315553601",
        "id": "ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
        "identity": {
            "acknowledged": true,
            "created_timestamp": 1602532300000,
            "hash": "Sjvjlx8G6Z0="
        },
        "text": {
            "body": "Hi from new number 3601"
        },
        "timestamp": "1602532300",
        "type": "text"
    }]
}

Tin nhắn khi nhấp vào nút trả lời nhanh

Khi khách hàng nhấp vào nút trả lời nhanh, phản hồi sẽ được gửi. Bên dưới là ví dụ về định dạng của lệnh gọi lại. Lưu ý: Khách hàng có thể không nhấp được vào nút và trả lời tin nhắn tương tác hoặc chỉ gửi tin nhắn cho bạn. Đảm bảo rằng bạn cũng có thể hỗ trợ loại trường hợp này. Hãy xem Tài liệu về Webhook để biết thêm thông tin. 
{
    "contacts": [
        {
            "profile": {
                "name": "Kerry Fisher"
            },
            "wa_id": "16505551234"
        }
    ],
    "messages": [
        {
            "button": {
                "payload": "No-Button-Payload",
                "text": "No"
            },
            "context": {
                "from": "16315558007",
                "id": "gBGGFmkiWVVPAgkgQkwi7IORac0"
            },
            "from": "16505551234",
            "id": "ABGGFmkiWVVPAgo-sKD87hgxPHdF",
            "timestamp": "1591210827",
            "type": "button"
        }
    ]
    # If there are any errors, an errors field (array) will be present        
    "errors": [ { ... } ]
}

Tin nhắn đến trả lời cho tin nhắn đã gửi

Người dùng có thể trả lời một tin nhắn cụ thể trong WhatsApp. Chúng tôi thêm đối tượng context nhằm giúp doanh nghiệp hiểu được ngữ cảnh của tin nhắn trả lời. Đối tượng context này cung cấp id của tin nhắn mà khách hàng đã trả lời, ID WhatsApp của người gửi tin nhắn ban đầu và ID của bất kỳ sản phẩm nào mà khách hàng có thể đang đề cập đến.

Bài viết Cách trả lời tin nhắn sẽ cung cấp thêm thông tin.

Ví dụ: Khách hàng đã trả lời tin nhắn của bạn

Dưới đây là ví dụ về một tin nhắn đến trả lời cho tin nhắn bạn đã gửi. Hãy xem phần đối tượng context ở bên dưới để biết thêm thông tin.

{
  "contacts": [ {
    "profile": {
        "name": "Kerry Fisher"
    },
    "wa_id": "16315551234"
  } ],
   "messages":[{
      "context":{
         "from":"16315558011",
         "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf"
         },
      "from":"16315551234",
      "id":"gBGGFlA5FpafAgkOuJbRq54qwbM",
      "text":{"body":"Yes, count me in!"},
      "timestamp":"1521499915",
      "type":"text"
  }]
}

text là trường không bắt buộc đối với tin nhắn có chứa file phương tiện. Nếu trường này tồn tại, giá trị text sẽ là chú thích của file phương tiện đã gửi hoặc phần nội dung của câu trả lời trong trường hợp câu trả lời là tin nhắn văn bản.

Ví dụ: Khách hàng đã trả lời Tin nhắn có chứa danh sách

{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

Ví dụ: Khách hàng đã trả lời Tin nhắn có chứa nút trả lời

{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
        }
      } # end interactive node
    } # end message item
  ] # end messages array
}

Ví dụ: Khách hàng hỏi thêm thông tin về một sản phẩm cụ thể

{
  "contacts": [
    {
      "profile": {
        "name": "customer-name"
      },
      "wa_id": "customer-whatsapp-ID"
    }
  ],
  "messages": [
    {
      "from": "customer-whatsapp-ID",
      "id": "message-ID",
      "text": {
        "body": "Can I get this in another color?"
      },
      "context": {
        "referred_product": {
          "catalog_id": "catalog-ID",
          "product_retailer_id": "product-ID"
        }
      },
      "timestamp": "message-received-timestamp",
      "type": "text"
    }
  ]
}

Ví dụ: Khách hàng đã đặt hàng sau khi nhận được Tin nhắn có chứa nhiều hoặc một sản phẩm

{
   "messages": [ {
      "from": "customer-whatsapp-id",
      "group_id": "group-id",
      "id": "message-ID",
      "timestamp": "message-timestamp",
      "type": "order"
      "order": {
         "catalog_id": "catalog_id",
         "product_items": [
            {
            "product_retailer_id":"product-ID",
            "quantity":"number-of-items",
            "item_price":"unitary-price-of-item",
            "currency":"price-currency"
            },
                 ...
         ],
         "text":"text-message-sent-along-with-the-order"
      }
   }
}

Tin nhắn đến từ hệ thống

Hệ thống sẽ tạo tin nhắn hệ thống khi sự kiện nào đó xảy ra.

Ví dụ: Người dùng đã thay đổi số điện thoại của họ

Nếu đặt thông số notify_user_change_number thành true trong phần cài đặt ứng dụng, bạn sẽ nhận được tin nhắn đến từ hệ thống khi người dùng thay đổi số điện thoại của họ.

{
    "messages": [
        {
            "from": "16315558889",
            "id": "ABGGFjFVWIifAzNzeXMtMTYzMTU1NTg4ODlAcy53aGF0c2FwcC5uZXQtMTU3NDA4MDEwMjIxMy1jaGFuZ2U",
            "system": {
                "body": "‎User A changed from ‎+1 (631) 555-8889 to ‎+1 (631) 555-8890‎",
                "new_wa_id": "16315558890",
                "type": "user_changed_number"
            },
            "timestamp": "1574080102",
            "type": "system"
        }
    ]
}

Ví dụ: Người dùng có khả năng đã thay đổi

Nếu đặt thông số show_security_notifications thành true trong phần cài đặt ứng dụng, bạn sẽ nhận được tin nhắn đến từ hệ thống khi người dùng (đang trò chuyện với bạn) có khả năng đã thay đổi trên WhatsApp.

Tất cả tin nhắn gửi đến người dùng này sẽ bị chặn cho đến khi thông báo này được xác nhận qua điểm cuối identity. Bạn vẫn sẽ nhận được các tin nhắn đến như mong đợi.

{
    "messages": [
        {
            "from": "16315553601",
            "id": "ABGGFjFVU2AfAzVzeXMtMTYzMTU1NTM2MDFAcy53aGF0c2FwcC5uZXQtMTYwMjUzNTM1NjMzMi1pZGVudGl0eQ",
            "system": {
  		"body": "Test security code change",
                "identity": "Rc/eg9Rl0JA=",
                "type": "user_identity_changed",
                "user": "16315553601"
            },
            "timestamp": "1602535356",
            "type": "system"
        }
    ]
}

Loại tin nhắn hệ thống

Loại tin nhắn hệ thốngMô tả

user_changed_number

Số điện thoại của người dùng đã thay đổi

user_identity_changed

Người dùng có khả năng đã thay đổi trên WhatsApp

Nhắc đến người dùng trong tin nhắn

Khi bạn gửi một tin nhắn trực tiếp nhắc đến ID WhatsApp cụ thể và có người trả lời tin nhắn đó, bạn sẽ thấy ID được nhắc đến trong đối tượng context và trong mảng mentions. Vì nhiều số điện thoại có thể được nhắc đến nên trường mentions là một mảng các số điện thoại, ngay cả khi bạn chỉ nhắc đến một số điện thoại.

Ví dụ: Khách hàng trả lời tin nhắn

Dưới đây là ví dụ về khách hàng trả lời một tin nhắn nhắc đến số điện thoại. Đối tượng context chứa các số điện thoại được nhắc đến trong tin nhắn ban đầu. Tin trả lời trong đối tượng text lại nhắc đến chính các số điện thoại đó.

{   
  "messages": [{
    "context": {
      "from": "16315555544",
      "id": "gBGGFlA5FpafAgkOuJbRq54qwbM",
      "mentions": [
        "16315551000",
        "16315551099"
      ]
    },
    "from": "16315551234 ",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "1504902988",
    "text": {
      "body": "@16315551000 and @16315551099 are mentioned"
    },
    "type": "text"
  }]
}