Chuyển tới nội dung chính
ZZalo Platforms

Sự kiện người dùng gửi tin nhắn

Khi người dùng gửi tin nhắn đến Official Account, hệ thống Zalo sẽ gửi một request HTTP đến Webhook Url đã đăng ký của ứng dụng

  • URL: Webhook Url của ứng dụng bên thứ 3
  • Method: POST
  • Content Type: application/json
  • X-ZEvent-Signature: mac = sha256(appId + data + timeStamp + OAsecretKey), với data là chuỗi json trả về dưới đây.

Ví dụ:​

{
    "app_id": "360846524940903967",
    "sender": {
        "id": "246845883529197922"
    },
    "user_id_by_app": "552177279717587730",
    "recipient": {
        "id": "388613280878808645"
    },
    "event_name": "user_send_text",
    "message": {
        "text": "message",
        "msg_id": "96d3cdf3af150460909"
    },
    "timestamp": "154390853474"
}

Mô tả thuộc tính​

Thuộc tính

Kiểu dữ liệu

Mô tả

app_id

String

Id của ứng dụng đang nhận sự kiện.

sender

Json Object

Ví dụ:

{
    "id": "246845883529197922"
}

Trong đó:

  • "id": Id của User gửi tin nhắn

recipient

Json Object

Ví dụ:

{
    "id": "388613280878808645"
}

Trong đó:

  • "id": Id của Official Account nhận tin nhắn

event_name

String

Xác định loại event, gồm các giá trị sau:

  • event _name="user_send_text": Người dùng gửi tin nhắn văn bản
  • event _name="user_send_image": Người dùng gửi tin nhắn hình ảnh
  • event _name="user_send_link": Người dùng gửi tin nhắn liên kết
  • event _name="user_send_audio": Người dùng gửi tin nhắn âm thanh
  • event _name="user_send_video": Người dùng gửi tin nhắn video
  • event _name="user_send_sticker": Người dùng gửi tin nhắn sticker
  • event _name="user_send_location": Người dùng gửi vị trí
  • event_name="user_send_business_card": Người dùng gửi danh thiếp
  • event_name="user_send_file": Người dùng gửi file

message

Json Object

Tùy theo event_name mà message sẽ có định dạng khác nhau, chi tiết sẽ được định nghĩa bên dưới bảng này.

Ví dụ:

{
    "text": "message",
    "msg_id": "96d3cdf3af150460909"
}

Trong đó:

  • "text": Nội dung tin nhắn người dùng gửi cho Official Account.
  • "msg_id": Id của tin nhắn.
Ngoài ra:
  • Nếu tin nhắn được gửi là tin nhắn đa phương tiện (Hình ảnh, ảnh gif, video,...) thì sẽ có thêm thuộc tính attachments.
  • Nếu trong data trả về có thuộc tính “quote_msg_id” thì tin nhắn này được gửi qua “Trả lời"

timestamp

String

Thời điểm request được gửi, tính bằng milisecond

Cấu trúc thuộc tính attachments​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Các dạng tin nhắn đa phương tiện (Hình ảnh, ảnh gif, video,...) sẽ có phần attachments chứa các thông tin chi tiết kèm theo tin nhắn đó.

Cấu trúc attachments đối với từng loại tin nhắn:​

1. Tin nhắn hình ảnh​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
    {
        "payload": {
            "thumbnail": "http://t.f6.photo.talk.zdn.vn/9c2db3ccc0a223fc7ab3.jpg",
            "url": "http://f6.photo.talk.zdn.vn/9c2db3ccc0a223fc7ab3.jpg"
        },
        "type": "image"
    }
]

Trong đó:

  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • thumbnail: thumbnail của ảnh
    • url: đường dẫn đến hình ảnh gốc
  • type: Loại tin nhắn

2. Tin nhắn ảnh gif​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "thumbnail": "http://cgif.zp.zdn.vn/634e85277d6a07b_t.jpg",
      "url": "http://cgif.zp.zdn.vn/634e81577d6a07b_n.gif"
    },
    "type": "gif"
  }
]

Trong đó:

  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • thumbnail: thumbnail của ảnh gif
    • url: đường dẫn đến ảnh gif
  • type: Loại tin nhắn

3. Tin nhắn liên kết​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "thumbnail": "https://link.photo.talk.zdn.vn/photolinkv2/720/YyZw==",
      "description": "Trang thông tin về Zalo dành cho cộng đồng lập trình viên",
      "url": "https://developers.zalo.me/"
    },
    "type": "link"
  }
]

Trong đó:

  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • thumbnail: Hình ảnh hiển thị
    • description: Thông tin mô tả của trang web đó.
    • url: đường dẫn đến trang web
  • type: Loại tin nhắn

4. Tin nhắn âm thanh​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "url": "http://f1.voice.talk.zdn.vn/507667510983167001/7e00789a51e4b9bae0f5.amr"
    },
    "type": "audio"
  }
]
  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • url: đường dẫn đến file âm thanh
  • type: Loại tin nhắn

5. Tin nhắn video​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "url": "https://f4-zvc.zdn.vn/9ae8cac9eead07f35ebc/494930035692638423",
      "thumbnail": "http://f7.photo.talk.zdn.vn/2111897866637249674/3665d4b4022a37cfa33.jpg",
      "description": ""
    },
    "type": "video"
  }
]
  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • url: đường dẫn đến trang web
    • thumbnail: Hình ảnh hiển thị
    • description: Thông tin mô tả của trang web đó.
  • type: Loại tin nhắn

6. Tin nhắn sticker​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "url": "https://api.zalo.me/api/emoticon/oasticker?eid=73585551855742711&size=130",
      "id": "e1540df031b5deb81a4"
    },
    "type": "sticker"
  }
]
  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • url: đường dẫn đến sticker
    • id: id của sticker
  • type: Loại tin nhắn

7. Tin nhắn về vị trí​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
      "coordinates": {
        "latitude": "10.7642473",
        "longitude": "106.65643139999999"
      }
    },
    "type": "location"
  }
]
  • payload: Chứa thông tin chi tiết của tin nhắn đa phương tiện
    • coordinates: Chứa thông tin tọa độ theo latitude và longitude
  • type: Loại tin nhắn

8. Tin nhắn đính kèm file​

Thuộc tính

Kiểu dữ liệu

Mô tả

attachments

Json Array

Ví dụ:

[
  {
    "payload": {
        "size": "233947",
        "name": "developer.docx",
        "checksum": "db8f0a790d28e3d8658a0ff0846189",
        "type": "docx",
        "url": "https://f7-group-zf.zdn.vn/xxx484bd4258d6a/xxx52598708747"
    },
    "type": "file"
  }
]
  • payload:
    • size: kích thước của file
    • name: tên file
    • checksum: kết quả nhận được khi hash MD5 file, dùng để check tính toàn vẹn của file.
    • type : loại file
    • url" đường dẫn để download file
  • type: Loại tin nhắn