← Tham chiếu API
Tin nhắnPOST

Gửi tin nhắn văn bản

Gửi tin nhắn văn bản. message.text không được rỗng; provider_data chứa trường riêng và trả lời trích dẫn dùng reply_to cấp cao nhất. 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.

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

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.

Tham số đường dẫn

Điểm cuối này không có tham số đường dẫn.

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

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.

Yêu cầu

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "text",
    "text": "Hello from UnifyPort"
  },
  "provider_data": {
    "parse_mode": "markdown"
  }
}'

Phản hồi

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