← Tham chiếu API
Tin nhắnPOST

Gửi tin nhắn liên hệ (vCard)

Gửi một thẻ liên hệ. message.type là contact và message.contacts là mảng có cấu trúc (một hoặc nhiều thẻ); UnifyPort tạo ra vCard. Mỗi thẻ bắt buộc có name; phones[].number, emails[].address, organization và title là tùy chọn. Hiện chỉ WhatsApp hỗ trợ; mảng contacts rỗng hoặc thẻ thiếu name trả về 400 invalid_request, còn các nhà cung cấp không phải WhatsApp trả về 400 unsupported_message_type. 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.

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.

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

Nội dung văn bản khi message.type là text.

url
string

URL media công khai dùng cho tin nhắn media.

file_url
string

URL media thay thế được adapter dạng tệp của provider hỗ trợ.

file_key
string

Tham chiếu tệp phía provider hoặc kho lưu trữ khi được hỗ trợ.

caption
string

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

contacts[]
object[]

Một hoặc nhiều danh thiếp có cấu trúc khi message.type là contact.

name
string

Tên hiển thị của liên hệ; bắt buộc với mỗi danh thiếp.

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.

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 / waveform cho âm thanh WhatsApp. Dùng reply_to cấp cao nhất cho trả lời trích dẫn.

seconds
integer

Thời lượng âm thanh tùy chọn theo giây cho tin nhắn audio WhatsApp; phải từ 0 trở lên.

waveform
string

Chuỗi dữ liệu dạng sóng tùy chọn cho tin nhắn audio WhatsApp.

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.

mentions[]
object[]

Các thành viên được tham chiếu bằng placeholder {{@<id>}} trong text hoặc caption.

id
string

Định danh thành viên phía provider tương ứng với placeholder {{@<id>}}.

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": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}'

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>"
  }
}