Tin nhắn

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

Gửi danh thiếp. message.contacts phải là mảng không rỗng và name của mỗi thẻ không được rỗng. Hiện chỉ WhatsApp hỗ trợ; dữ liệu không hợp lệ trả 400 invalid_request.

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

Kênh được hỗ trợ

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

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

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

provider_data

object

Tùy chọn gửi riêng của provider, chỉ có hiệu lực với provider và loại tin nhắn được hỗ trợ. seconds của WhatsApp audio/video là số nguyên không âm. Chỉ với video, dùng giá trị từ 0 đến 4294967295, waveform chỉ dành cho audio. Dùng reply_to cấp cao nhất cho trả lời trích dẫn khi được hỗ trợ. Với sticker, bỏ qua provider_data hoặc dùng đối tượng rỗng; giá trị không phải đối tượng trả về 400 invalid_request, đối tượng không rỗng trả về 400 provider_invalid_request.

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.

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 hội thoại chuẩn: user, group hoặc channel. Nhóm thông báo cộng đồng WhatsApp vẫn sử dụng group.

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, contact, link_preview, poll hoặc sticker.

enum: text, image, video, audio, document, file, contact, link_preview, poll, sticker

text

string

Nội dung không rỗng, bắt buộc cho text và link_preview. Với link_preview, phải có ký tự không phải khoảng trắng; WhatsApp còn yêu cầu nội dung chứa nguyên văn link_preview.url.

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.

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ệ.

link_preview

object

Chỉ dùng cho message.type=link_preview, bắt buộc cùng text; không được trộn với payload khác. Cấu trúc chung chỉ bắt buộc url; title và description tùy chọn cho phép chuỗi rỗng nhưng không cho phép null. Chính sách gửi WhatsApp của API này yêu cầu title/image_url không rỗng, giới hạn title ở 255 và description ở 1024 ký tự Unicode.

url

string

Liên kết đích bắt buộc: URI HTTP(S) tuyệt đối có tên máy chủ và không có khoảng trắng; địa chỉ trong ngoặc vuông chỉ chấp nhận IPv6 literal. Giữ nguyên văn, không bảo đảm tài nguyên truy cập được.

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

title

string

Tiêu đề xem trước tùy chọn; cho phép chuỗi rỗng, không cho phép null. WhatsApp yêu cầu không rỗng và tối đa 255 ký tự Unicode.

description

string

Tóm tắt xem trước tùy chọn; cho phép chuỗi rỗng, không cho phép null. WhatsApp cho phép tối đa 1024 ký tự Unicode.

image_url

string

URI ảnh tùy chọn, bắt buộc và không rỗng với WhatsApp. Phải là URI HTTP(S) tuyệt đối có tên máy chủ và không có khoảng trắng; địa chỉ trong ngoặc vuông chỉ chấp nhận IPv6 literal. Giữ nguyên văn, không bảo đảm tài nguyên truy cập được.

pattern: ^[Hh][Tt][Tt][Pp][Ss]?://(?:[^/?#@\s]*@)?(?:\[[0-9A-Fa-f:.]+\]|[^/?#:@\s\[\]]+)(?::[0-9]*)?(?:[/?#]|$)

poll

object

Bắt buộc và chỉ dùng cho message.type=poll; không được trộn với text hoặc payload khác. Bắt buộc có question, options và max_selections. Giữ nguyên văn câu hỏi và tiêu đề lựa chọn. Cấu trúc chung không giới hạn độ dài câu hỏi, số lựa chọn tối đa hay tiêu đề trùng lặp; provider có thể áp dụng giới hạn bổ sung.

question

string

Câu hỏi bình chọn bắt buộc, phải chứa ký tự không phải khoảng trắng; giữ nguyên văn.

minLength: 1 · pattern: \S

options[]

object[]

Mảng lựa chọn bắt buộc có ít nhất hai lựa chọn, mỗi lựa chọn phải có title.

minItems: 2

title

string

Tiêu đề lựa chọn bắt buộc có ký tự không phải khoảng trắng. Khi gửi không trim, đổi chữ hoa/thường hoặc chuẩn hóa Unicode.

minLength: 1 · pattern: \S

max_selections

integer

Số lựa chọn tối đa cho mỗi người bình chọn, bắt buộc; không phải số người bình chọn. Số nguyên từ 1 đến số lượng options, được API kiểm tra. Các giá trị nguyên như 1.0 và 1e0 tương đương 1; giá trị không nguyên không hợp lệ.

minimum: 1

reply_to

object

Mục tiêu trả lời trích dẫn. Sao chép nguyên data.message.reply_token từ sự kiện tin nhắn có thể trích dẫn hoặc data.reply_token từ phản hồi gửi vào reply_to.reply_token, dùng tài khoản và hội thoại gốc; không thay bằng ID tin nhắn.

reply_token

string

Handle không trong suốt từ data.message.reply_token của sự kiện tin nhắn có thể trích dẫn hoặc data.reply_token của phản hồi gửi. Dùng nguyên với tài khoản và hội thoại gốc; không thay bằng ID tin nhắ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 — Handle không rỗng, không trong suốt của WhatsApp có thể trả về sau khi gửi thành công nếu ngữ cảnh trích dẫn đầy đủ, gồm cả khảo sát vừa gửi để văn bản thường trích dẫn. Bỏ qua nếu không có, không đổi trạng thái accepted. Dùng nguyên vẹn với tài khoản và hội thoại gốc; không phải ID tin nhắn.

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

Handle không rỗng, không trong suốt của WhatsApp có thể trả về sau khi gửi thành công nếu ngữ cảnh trích dẫn đầy đủ, gồm cả khảo sát vừa gửi để văn bản thường trích dẫn. Bỏ qua nếu không có, không đổi trạng thái accepted. Dùng nguyên vẹn với tài khoản và hội thoại gốc; không phải ID tin nhắn.

minLength: 1

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.
missing_api_key · 11000 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.
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.