Trước khi gửi
Gửi SMS hoặc MMS được hỗ trợ bằng số gửi đã được cấu hình cho tài khoản của bạn. Đây là thao tác trên hệ thống thực tế, có thể liên hệ với người nhận và phát sinh phí. Chỉ gửi đến những người nhận mà bạn được phép liên hệ và chỉ gửi loại lưu lượng đã được phê duyệt; các số điện thoại và mã tham chiếu trong ví dụ dưới đây đều là hư cấu.
Tài khoản của bạn cần được phê duyệt gửi tin nhắn đi và có các quyền áp dụng cho bên gửi, quốc gia và loại lưu lượng. Thông tin xác thực trực tiếp của người dùng Cá nhân/Người tiêu dùng không đủ điều kiện sử dụng API này. Thông tin xác thực API chuyên dụng đã được phê duyệt có quy trình xét điều kiện riêng; bên gửi P2P di động có thể cần thêm quyền P2P và quyền gửi tại Hoa Kỳ/Canada. Hãy xác nhận cách thiết lập tài khoản phù hợp với MultiTEL, thay vì xem việc có thông tin xác thực API là tự động được phép gửi mọi loại lưu lượng.
Gửi yêu cầu
Xác thực qua HTTPS bằng tài khoản API đã được kích hoạt, từ địa chỉ IP nguồn được cho phép của tài khoản đó. Lưu thông tin xác thực trong kho lưu trữ bí mật phía máy chủ. Sử dụng POST với các trường được mã hóa theo biểu mẫu, hoặc một đối tượng JSON khi không cung cấp trường biểu mẫu hay trường truy vấn nào. Không đưa thông tin xác thực hoặc nội dung tin nhắn vào URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Trường | Bắt buộc | Ý nghĩa |
|---|---|---|
| from | Có | Số gửi đã được cấu hình của bạn; nên dùng đầy đủ các chữ số theo định dạng quốc tế. |
| to | Có | Một số đích, nhiều số đích phân tách bằng dấu phẩy hoặc một mảng JSON. Nên dùng đầy đủ các chữ số theo định dạng quốc tế. Yêu cầu gửi theo nhóm có thể bị từ chối do các giới hạn P2P/quốc gia áp dụng cho yêu cầu đó; đây không phải là API gửi hàng loạt không giới hạn. |
| text | Đối với SMS | Nội dung văn bản của tin nhắn ở dạng UTF-8. Phải có ít nhất văn bản không rỗng hoặc nội dung đa phương tiện. Gửi các ký tự và dấu xuống dòng thực tế thay vì HTML hoặc văn bản được mã hóa bằng dấu phần trăm. Một số luồng qua nhà mạng chuẩn hóa các chuỗi escape được gửi dưới dạng ký tự nguyên văn. |
| media | Đối với MMS chỉ chứa nội dung đa phương tiện | Nội dung đa phương tiện được mã hóa Base64, không phải URL hoặc đường dẫn tệp. Khả năng sử dụng MMS, định dạng và kích thước phụ thuộc vào tuyến đã được cấu hình. Hãy xác nhận với MultiTEL về nội dung đa phương tiện được hỗ trợ; bộ xử lý này không thiết lập giới hạn kích thước nội dung đa phương tiện chung cho mọi trường hợp. |
| reference | Nên có | Nhãn đối chiếu của bạn, được lưu trong bản ghi/callback. Hãy cung cấp nhãn này để hỗ trợ khắc phục sự cố. Đây không phải là khóa bảo đảm tính lũy đẳng. |
| notifyurl | Không | Điểm nhận callback qua HTTPS của bạn. Bộ xử lý có thể gửi kết quả ban đầu bằng POST sau khi xử lý. Điểm nhận này phải do bạn kiểm soát và không được là URL của dịch vụ nội bộ. |
Khi dùng mảng JSON, hãy đặt một mảng thực sự trong to; không đặt chuỗi biểu diễn mảng JSON vào trường biểu mẫu. Hãy dùng việc gửi đến một người nhận làm phép thử tích hợp ban đầu. Khả năng hỗ trợ gửi theo nhóm và MMS khác nhau tùy tuyến, vì vậy hãy xác nhận tổ hợp được hỗ trợ trước khi sử dụng.
Đọc toàn bộ kết quả
Chỉ minh họa một số trường được chọn; chi phí hiển thị không phải là báo giá.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Kiểm tra đồng thời trạng thái HTTP, status.code trong JSON và status/message của phản hồi. Mã kết quả có thể là chuỗi. Lưu sms_log_id_ori và các giá trị thông điệp/tham chiếu được trả về để đối chiếu khi cần hỗ trợ. Các giá trị uniqueid và pid kiểu cũ thay đổi tùy tuyến; không suy diễn định dạng của chúng hoặc cho rằng chúng là mã thông báo bảo đảm tính lũy đẳng phía máy khách.
Success hoặc Message queued thường cho biết tuyến được chọn đã chấp nhận tin nhắn, không có nghĩa là điện thoại của người nhận đã nhận được tin. Chỉ riêng trạng thái callback ban đầu như sent không xác nhận việc chuyển phát cuối cùng.
Phân đoạn và các khoản phí
Sử dụng Phân tích độ dài SMS với toàn bộ nội dung văn bản cuối cùng trước khi gửi. Giá SMS phụ thuộc vào đích đến và dịch vụ của tài khoản; phí nhà mạng áp dụng được cộng theo từng phân đoạn. Luồng gửi cộng giá gửi đến các người nhận với các khoản phí áp dụng, sau đó nhân với số phân đoạn SMS đã tính. Trong phép tính này, một yêu cầu MMS được coi là một tin nhắn.
cost và permsg là các chuỗi tiền tệ đã được định dạng trong phản hồi kiểu cũ. carrier_fee_usd cho biết phần phí nhà mạng bằng USD và đã được bao gồm trong tổng phí gửi được tính; không cộng khoản này thêm lần nữa. Bạn phải kiểm tra mức giá thực tế và khả năng sử dụng tuyến dành cho tài khoản của mình. Yêu cầu này không phải là thao tác chỉ để xem giá.
Mã đã được rà soát thực hiện trừ tiền sau khi luồng gửi qua nhà mạng thành công, nhưng việc nhà mạng chấp nhận, lưu dữ liệu nội bộ và tính phí không nằm trong cùng một giao dịch. Lỗi hoặc hết thời gian chờ có thể xảy ra sau khi yêu cầu đã được hệ thống thượng nguồn chấp nhận. Không có khóa bảo đảm tính lũy đẳng nào được cung cấp cho máy khách: việc gửi lại cùng một mã tham chiếu có thể khiến tin nhắn được gửi và tính phí lần nữa.
Chuyển phát nội bộ và kết quả hỗn hợp
Các số được lưu trú trong hệ thống nội bộ có thể được chấp nhận (accepted) vào luồng tin nhắn đến của MultiTEL mà không cần gửi qua nhà mạng bên ngoài. Đối với yêu cầu có toàn bộ người nhận nội bộ, phản hồi có thể bao gồm accepted, message_id, provider và delivery_status. Việc chấp nhận nội bộ không bảo đảm rằng đích chuyển tiếp được cấu hình của người nhận đã hoạt động.
Kiểm tra local_delivery_results và partial khi có. Một người nhận có thể hiển thị accepted với giá trị true trong khi kết quả chuyển tiếp không thành công. Trong một yêu cầu hỗn hợp, các người nhận qua nhà mạng có thể đã được chấp nhận (accepted) còn phần nội bộ thì thất bại. Không tự động thử lại toàn bộ lô: hãy đối soát từng người nhận trước.
Trong luồng này, việc chấp nhận yêu cầu có toàn bộ người nhận nội bộ báo cáo chi phí gửi đi bằng không, nhưng người nhận vẫn có thể chịu phí tin nhắn đến thông thường. Không coi chi phí gửi đi bằng không là bảo đảm rằng không có tài khoản nào bị tính phí.
Callback và đối chiếu
Khi cung cấp notifyurl, callback ban đầu có cấu trúc bao ngoài status và các trường phản hồi bao gồm message_id, reference, from, to, status, status_text, error_code, timestamp và accepted. Kết quả nội bộ cũng có thể xuất hiện. Lưu thông tin đối chiếu nhưng không ghi thông tin xác thực API hoặc nội dung tin nhắn không cần thiết vào nhật ký.
Bộ xử lý này không thêm trường chữ ký vào callback ban đầu đó. Không dùng callback chưa được xác minh làm căn cứ cấp quyền duy nhất cho một hành động khác. Tham khảo cách thiết lập tích hợp/webhook được hỗ trợ cho tài khoản của bạn và đối soát các kết quả chưa chắc chắn với bản ghi trên cổng quản lý hoặc bộ phận hỗ trợ. Không cho rằng callback chỉ đến một lần hoặc đến theo thứ tự chuyển phát cuối cùng.
Lỗi và khôi phục an toàn
Lỗi kiểm tra tính hợp lệ có thể dùng mã API 403. Việc từ chối do phê duyệt tài khoản, P2P và chính sách quốc gia cũng có thể đặt trạng thái HTTP 403 và kèm theo response.code mà máy có thể đọc được. Giới hạn tần suất có thể dùng 429 kèm thông tin thử lại. Khi không thể truy xuất chính sách hoặc khi gửi/lưu dữ liệu nội bộ thất bại, mã trả về có thể là 503 hoặc 500; trường hợp không đủ số dư theo cơ chế cũ cũng có thể trả về 500.
Với 429, hãy tuân thủ Retry-After và mọi giá trị response.retry_after được cung cấp. Khi bị từ chối do tài khoản, bên gửi, quốc gia hoặc người nhận, hãy khắc phục nguyên nhân trước khi thử lại. Khi hết thời gian chờ hoặc kết quả gửi không rõ ràng, hãy lưu thời điểm yêu cầu, mã tham chiếu và các mã định danh được trả về, kiểm tra cổng quản lý và liên hệ bộ phận hỗ trợ trước khi gửi lại. Chỉ riêng việc không có bản ghi nhật ký không chứng minh rằng chưa có nhà mạng nào chấp nhận yêu cầu.