Tham chiếu API

Tin nhắn

Nhắc đến (@) thành viên trong tin nhắn nhóm

Nhắc đến (@) thành viên nhóm. Khai báo ids trong mentions và đặt {{@<id>}} trong message.text hoặc caption. WhatsApp hỗ trợ văn bản và caption media; LINE hiện chỉ hỗ trợ văn bản. Provider khác bỏ qua mentions. provider_data.mentions cũ đã ngừng dùng.

POSThttps://api.unifyport.ai/v1/messages

Trước khi gọi

Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.

Hoàn tất xác thực và kiểm tra runtime_status. Xác thực và kết nối là hai trạng thái riêng; HTTP thành công chưa chứng minh sẵn sàng.

Nguồn tham số
account_id
Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản
to.id · to.type
Khi trả lời, sao chép data.conversation.id và data.conversation.type từ message.received vào to.id và to.type. Người nhận mới tuân theo quy tắc ID của kênh. Hỗ trợ gửi tin nhắn hợp nhất

Tham số yêu cầu

Tiêu đề

X-Api-Key
stringbắt buộc

API key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.

Content-Type
stringbắt buộc

Dùng application/json khi gửi nội dung yêu cầu JSON.

Nội dung yêu cầu

account_id
stringbắt buộc

Tài khoản nhà cung cấp gửi tin nhắn.

minLength: 1

to
objectbắt buộc

Đích nhận với id và type.

id
stringbắt buộc

Định danh người nhận ở phía provider.

minLength: 1

type
stringbắt buộc

Loại người nhận: user, group hoặc channel.

enum: user, group, channel

message
objectbắt buộc

Payload tin nhắn chuẩn hóa. Văn bản dùng message.text; media dùng message.url.

type
stringbắt buộc

Loại tin nhắn: text, image, video, audio, document, file hoặc contact.

enum: text, image, video, audio, document, file, contact

text
string

Văn bản không rỗng, bắt buộc khi message.type=text.

minLength: 1

caption
string

Chú thích không bắt buộc cho tin nhắn image, video, document hoặc file.

url
string

URL HTTP(S) tuyệt đối không rỗng; media cần url, file_url hoặc file_key.

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_url
string

URL HTTP(S) tuyệt đối thay thế không rỗng; media cần một nguồn.

format: uri · pattern: ^[Hh][Tt][Tt][Pp][Ss]?://

file_key
string

Tham chiếu tệp provider hoặc storage không rỗng; media cần một nguồn.

minLength: 1

contacts[]
object[]

Mảng danh thiếp không rỗng, bắt buộc khi message.type=contact.

minItems: 1

name
string

Tên hiển thị không rỗng, bắt buộc với mỗi danh thiếp.

minLength: 1

phones[]
object[]

Danh sách số điện thoại trong danh thiếp.

number
string

Số điện thoại; bắt buộc với mỗi mục phone.

type
string

Nhãn điện thoại không bắt buộc, chẳng hạn CELL hoặc WORK.

emails[]
object[]

Danh sách địa chỉ email trong danh thiếp.

address
string

Địa chỉ email; bắt buộc với mỗi mục email.

format: email

type
string

Nhãn email không bắt buộc, chẳng hạn WORK hoặc HOME.

organization
string

Tên tổ chức không bắt buộc của liên hệ.

title
string

Chức danh không bắt buộc của liên hệ.

provider_data
object

Tuỳ chọn riêng của provider như parse_mode của Telegram hoặc seconds cho WhatsApp audio / video dưới dạng số nguyên không âm. Chỉ với video, phạm vi cho phép là từ 0 đến 4294967295; waveform vẫn chỉ dành cho audio. Dùng reply_to cấp cao nhất cho trả lời trích dẫn.

seconds
integer

Thời lượng tùy chọn tính bằng giây cho tin nhắn WhatsApp audio và video dưới dạng số nguyên không âm. Chỉ với video, phạm vi cho phép là từ 0 đến 4294967295.

minimum: 0

waveform
string

Dữ liệu waveform tùy chọn cho tin nhắn audio WhatsApp. Giá trị không rỗng phải dùng mã hóa Base64 chuẩn và sau khi decode phải là dữ liệu waveform JSON có thể parse; chuỗi rỗng được xem như chưa cung cấp, các định dạng sai khác trả về HTTP 400 provider_invalid_request.

reply_to
object

Mục tiêu trả lời trích dẫn. Sao chép nguyên vẹn data.message.reply_token từ webhook đến vào reply_to.reply_token của yêu cầu gửi.

reply_token
string

Token trả lời không trong suốt được sao chép nguyên vẹn từ data.message.reply_token của webhook đến.

minLength: 1

mentions[]
object[]

Danh sách mục tiêu @ của tin nhắn nhóm. type=member dùng id thành viên Provider tương ứng; type=all nghĩa là @tất cả, chỉ có hiệu lực khi Provider hỗ trợ, nếu không sẽ trả về unsupported_message_type.

type
string

Loại mục tiêu @. Nếu bỏ qua sẽ xử lý như member để tương thích yêu cầu cũ; type=member bắt buộc có id, còn type=all không gửi id và chỉ áp dụng cho chat nhóm.

enum: member, all

id
string

Định danh thành viên Provider bắt buộc khi type=member.

minLength: 1

Hiểu kết quả

Lưu message_id và provider_ref để đối chiếu sự kiện sau đó hoặc chẩn đoán. accepted không xác nhận đã giao. Chỉ xác nhận qua sự kiện biên nhận khi kênh hỗ trợ; định dạng mã định danh khác nhau theo kênh.

reply_token — Opaque reply handle WhatsApp có thể trả về khi kênh cung cấp định danh tin nhắn có thể phản hồi; đây không phải id tin nhắn cha.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "message_id": "msg_example",
    "account_id": "acc_example",
    "status": "accepted",
    "provider_ref": "provider_msg_example",
    "reply_token": "<opaque WhatsApp reply handle>"
  }
}

Nội dung phản hồi

message_id
string

Định danh tin nhắn UnifyPort (msg_...) cho tin nhắn đã được chấp nhận.

account_id
string

Tài khoản nhà cung cấp mà phản hồi này tham chiếu tới.

status
string

Trạng thái chấp nhận; accepted nghĩa là tin nhắn đã được xếp hàng để gửi tới nhà cung cấp.

provider_ref
string

Tham chiếu tin nhắn phía nhà cung cấp, một khi nhà cung cấp gán một giá trị.

reply_token
string

Opaque reply handle WhatsApp có thể trả về khi kênh cung cấp định danh tin nhắn có thể phản hồi; đây không phải id tin nhắn cha.

Phản hồi

200

200 OK

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

409

Conflict

Thao tác đang yêu cầu xung đột với tài khoản hoặc tài nguyên nhà cung cấp đã có.

500

Internal Server Error

Dịch vụ gặp lỗi không mong muốn.

501

Not Implemented

Provider đã chọn chưa triển khai thao tác này.

502

Bad Gateway

Adapter hoặc upstream provider không thể hoàn tất thao tác.

Khi yêu cầu thất bại

Kiểm tra HTTP và error.code/numeric_code, giữ request_id. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. Tham chiếu mã lỗi

invalid_request · 10000 · 400
Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
invalid_api_key · 11001 · 401
Kiểm tra X-Api-Key và workspace còn hoạt động.
provider_not_ready · 30009 · 409
Khôi phục xác thực và kết nối, xác nhận kết quả cũ trước khi thử lại.
unsupported_message_type · 36000 · 400
Chọn thao tác hoặc loại tin được hỗ trợ. Gửi lại không bổ sung khả năng cho kênh.
invalid_reply_token · 36006 · 400
Sao chép nguyên reply_token nhận được, không tạo từ ID tin. Cần kênh hỗ trợ trả lời trích dẫn.