Nội dung tin nhắn nằm trong data.message bên trong một sự kiện. Dùng format: "plaintext" cho văn bản thuần hoặc format: "block" cho nội dung có cấu trúc. Thêm tệp qua mảng attachments riêng.
Các ví dụ JSON bên dưới là đối tượng tin nhắn hoặc block, như đã ghi chú. Ví dụ cuối cùng là một yêu cầu HTTP đầy đủ. Mọi tên, ID và URL chỉ mang tính minh họa.
Văn bản thuần
Đặt format là plaintext và đưa nội dung vào text:
{
"format": "plaintext",
"text": "Hello Alex!\nHow can we help?"
}
\n tạo một dấu xuống dòng. Thẻ HTML hay ký hiệu Markdown trong trường này không tạo định dạng block của Subiz. Để có chữ đậm hoặc liên kết có nhãn, hãy dùng tin nhắn block.
Tin nhắn block
Đặt format là block và đưa một đối tượng JSON vào block:
{
"format": "block",
"block": {
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Hello "
},
{
"type": "text",
"text": "Alex",
"bold": true
}
]
}
}
Nội dung hiển thị là “Hello Alex”. Block là một cây: type chọn loại nút, content chứa các nút con, và nút văn bản lưu nội dung trong text.
Đừng chuyển block thành chuỗi rồi đưa vào text. Subiz có thể tạo văn bản thuần từ cây block, nhưng hãy giữ block khi bạn cần định dạng của nó.
Chữ đậm và chữ thường
Áp dụng định dạng cho từng nút văn bản. Với chữ thường, bỏ bold hoặc đặt nó là false; không có cờ light riêng.
| Trường | Tác dụng khi true |
|---|---|
bold |
Chữ đậm. |
italic |
Chữ nghiêng. |
underline |
Chữ gạch chân. |
strike_through |
Chữ gạch ngang. |
Đây là một đối tượng block để đặt vào message.block:
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Regular. "
},
{
"type": "text",
"text": "Bold. ",
"bold": true
},
{
"type": "text",
"text": "Italic. ",
"italic": true
},
{
"type": "text",
"text": "Underlined. ",
"underline": true
},
{
"type": "text",
"text": "Struck through.",
"strike_through": true
}
]
}
Mỗi nút quyết định định dạng chữ của chính nó. Nút chữ thường đứng sau nút chữ đậm sẽ trở lại chữ thường. Bạn có thể kết hợp nhiều cờ, như bold: true và italic: true, trên cùng một nút văn bản. Chữ thường không có nghĩa là màu chữ nhạt hơn.
Liên kết trong block
Dùng nút link với text là nhãn hiển thị và href là đích đến. Đặt liên kết cạnh các nút khác trong mảng content của đoạn văn:
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Read our "
},
{
"type": "link",
"text": "delivery guide",
"href": "https://example.com/delivery"
},
{
"type": "text",
"text": " before ordering."
}
]
}
Kết quả là “Read our delivery guide before ordering.” Nhãn liên kết đặt trực tiếp trong text, không đặt trong nút con. Dùng URL HTTPS tuyệt đối cho đích đến trên web.
Liên kết trong dòng khác với tệp đính kèm xem trước liên kết, loại mang tiêu đề và mô tả riêng.
Đoạn văn và xuống dòng
Dùng hard_break để xuống dòng trong một đoạn văn. Để nhóm nhiều đoạn văn, đặt chúng trong một block div:
{
"type": "div",
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Hello Alex,"
},
{
"type": "hard_break"
},
{
"type": "text",
"text": "Your order is ready."
}
]
},
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Thank you!"
}
]
}
]
}
Nội dung này hiển thị lời chào, thông báo đơn hàng ở dòng tiếp theo và một đoạn cảm ơn riêng. Khoảng cách chính xác phụ thuộc vào trình hiển thị và kênh đích.
Gửi tin nhắn block
Dùng endpoint Gửi tin nhắn vào hội thoại. Thay ID hội thoại và access token trước khi gửi:
POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"type": "message_sent",
"data": {
"message": {
"format": "block",
"block": {
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Hello "
},
{
"type": "text",
"text": "Alex",
"bold": true
}
]
}
}
}
}
Với Gửi tin nhắn cho khách hàng, dùng cùng nội dung tin nhắn bên trong cấu trúc sự kiện của endpoint đó và cung cấp đích đến trên kênh. Body bên ngoài của yêu cầu đó khác.
Đọc tin nhắn mà không mất nội dung
Khi đọc phản hồi API hoặc sự kiện webhook:
- Kiểm tra
formattrước khi diễn giải nội dung. Giữ nguyên các định dạng chưa biết nếu tích hợp của bạn không hiển thị được. - Giữ cây block nếu định dạng quan trọng; chỉ dùng
textsẽ mất liên kết và kiểu chữ. - Kiểm tra
attachmentsngay cả khitextrỗng. - Thử nghiệm trên kênh đích. Schema block dùng chung không đảm bảo mọi kênh đều hiển thị mọi loại nút hay cờ định dạng.
Tiếp tục với Tệp đính kèm cho ảnh, video, âm thanh và các nội dung tin nhắn khác.