Hướng dẫn tích hợp contact us API
Back to ezysupportContact Us API cho phép website hoặc ứng dụng gửi thông tin liên hệ của khách hàng vào hệ thống hỗ trợ. Sau khi request hợp lệ, hệ thống sẽ lưu nội dung liên hệ như một message/mail nội bộ, lưu thêm metadata được cho phép, rồi gửi email thông báo tới danh sách supporter đã cấu hình.
Endpoint
POST /api/v1/contact-us
Khi gửi thành công, API trả về:
204 No Content
Nếu tính năng Contact Us đang bị tắt, API trả về:
404 Not Found
Nếu dữ liệu không hợp lệ, API trả về lỗi
400 Bad Request kèm danh sách field lỗi.Request Body
API nhận các field sau:
| Field | Bắt buộc | Mô tả |
|---|---|---|
contactUsYourName | Có | Tên người gửi, tối đa 120 ký tự |
contactUsYourEmail | Có | Email người gửi, phải đúng định dạng email |
contactUsYourPhoneNumber | Không | Số điện thoại, nếu truyền lên phải đúng định dạng phone |
contactUsSubject | Có | Chủ đề liên hệ, tối đa 300 ký tự |
contactUsMessage | Có | Nội dung liên hệ, tối đa 6000 ký tự |
Ví dụ request dạng JSON:
curl -X POST https://example.com/api/v1/contact-us \ -H "Content-Type: application/json" \ -d '{ "contactUsYourName": "Nguyen Van A", "contactUsYourEmail": "a@example.com", "contactUsYourPhoneNumber": "+84901234567", "contactUsSubject": "Can tu van san pham", "contactUsMessage": "Toi muon duoc tu van them ve dich vu." }'
Với form HTML, có thể submit các field cùng tên:
<form id="contactUsForm"> <input name="contactUsYourName" /> <input name="contactUsYourEmail" /> <input name="contactUsYourPhoneNumber" /> <input name="contactUsSubject" /> <textarea name="contactUsMessage"></textarea> </form>
Metadata mở rộng
Ngoài các field mặc định, client có thể gửi thêm metadata, ví dụ:
{
"contactUsYourName": "Nguyen Van A",
"contactUsYourEmail": "a@example.com",
"contactUsSubject": "Can tu van",
"contactUsMessage": "Toi can tu van goi dich vu.",
"utmSource": "google",
"productCode": "PRO-001"
}
Tuy nhiên, hệ thống chỉ lưu các metadata key đã được cấu hình trong danh sách cho phép. Những key không nằm trong whitelist sẽ bị bỏ qua. Thiết kế này giúp tránh việc client gửi dữ liệu tùy ý vào hệ thống lưu trữ.
Luồng xử lý
sequenceDiagram
participant Client as Website/App
participant API as Contact Us API
participant Config as Cấu hình hệ thống
participant Validator as Bộ kiểm tra dữ liệu
participant MailStore as Kho message/mail
participant Metadata as Kho metadata
participant Email as Dịch vụ gửi email
participant Supporter as Supporter
Client->>API: POST /api/v1/contact-us
API->>Config: Kiểm tra Contact Us có bật không
alt Tính năng bị tắt
API-->>Client: 404 Not Found
else Tính năng đang bật
API->>Validator: Validate tên, email, phone, subject, message
alt Dữ liệu không hợp lệ
Validator-->>API: Danh sách lỗi theo field
API-->>Client: 400 Bad Request
else Dữ liệu hợp lệ
API->>Config: Lấy danh sách metadata key được phép
API->>MailStore: Lưu contact message
API->>Metadata: Lưu phone và metadata hợp lệ
API->>Config: Lấy danh sách supporter email
API->>Email: Gửi email thông báo
Email-->>Supporter: Email "[Contact Us] ..."
API-->>Client: 204 No Content
end
end
Validate dữ liệu
API kiểm tra các điều kiện chính sau:
| Field | Điều kiện lỗi |
|---|---|
contactUsYourName | Rỗng hoặc dài hơn 120 ký tự |
contactUsYourEmail | Rỗng hoặc không đúng định dạng email |
contactUsYourPhoneNumber | Không rỗng nhưng không đúng định dạng phone |
contactUsSubject | Rỗng, dài hơn 300 ký tự, hoặc chứa script tag |
contactUsMessage | Rỗng, dài hơn 6000 ký tự, chứa script tag, chứa iframe, hoặc HTML không hợp lệ |
Ví dụ response lỗi:
{
"contactUsYourEmail": "invalid",
"contactUsMessage": "required"
}
Các mã lỗi phổ biến gồm:
| Mã lỗi | Ý nghĩa |
|---|---|
required | Field bắt buộc đang rỗng |
invalid | Giá trị không hợp lệ |
overLength | Giá trị vượt quá độ dài cho phép |
Authentication
Endpoint được thiết kế để có thể gắn thông tin người dùng nếu request đến từ người dùng đã đăng nhập. Client không cần tự gửi
userId trong body. Nếu hệ thống nhận diện được user hiện tại, message sẽ được liên kết với user đó; nếu không, message vẫn được lưu theo luồng contact thông thường.Cấu hình cần chuẩn bị
Trước khi tích hợp production, nên kiểm tra các cấu hình sau:
| Cấu hình | Mục đích |
|---|---|
| Bật/tắt Contact Us | Quyết định API có hoạt động hay trả về 404 |
| Supporter emails | Danh sách email nhận thông báo khi có liên hệ mới |
| Accepted metadata keys | Danh sách key metadata được phép lưu |
Nếu danh sách supporter email chưa được cấu hình, message vẫn có thể được lưu, nhưng email thông báo có thể không đến được người phụ trách.
Kết quả sau khi submit
Sau khi submit thành công:
- Contact message được lưu vào hệ thống mail/message nội bộ.
- Email người gửi và tên người gửi được lưu trong thông tin
from. - Số điện thoại được lưu như metadata riêng.
- Các metadata hợp lệ khác được lưu kèm message.
- Hệ thống gửi email thông báo tới supporter với tiêu đề dạng
[Contact Us] {subject}. - Admin có thể xem, tìm kiếm, đánh dấu đã đọc hoặc xóa contact message trong khu vực quản trị.
Lưu ý tích hợp
Không nên gửi dữ liệu nhạy cảm qua metadata nếu không thật sự cần thiết. Với các field mở rộng như
utmSource, campaign, productCode, hãy cấu hình whitelist metadata trước, sau đó mới gửi từ client.Client nên xử lý riêng các trạng thái:
-
204: gửi thành công, reset form hoặc hiển thị thông báo thành công. -
400: hiển thị lỗi theo từng field. -
404: tính năng Contact Us chưa bật hoặc không khả dụng. -
5xx: lỗi hệ thống, nên cho phép người dùng thử lại sau.