Tài liệu REST API
REST API SMS & MMS
Gửi các tin nhắn ứng dụng đã được phê duyệt và xử lý việc tiếp nhận, sự kiện chuyển phát, phân đoạn và cước phí.
Chọn API và thông tin xác thực cùng nhau
Các tài khoản Nhà phát triển & Tự động hóa, Doanh nghiệp và Nhà cung cấp truyền thông đã được phê duyệt có thể tích hợp các dịch vụ đã được bật. Một nhà phát triển cá nhân không cần phải giả danh là công ty. SMS/MMS ứng dụng yêu cầu phê duyệt gửi tin và đăng ký phù hợp. Dịch vụ Cá nhân & Gia đình không có API khởi tạo tin nhắn nào mà khách hàng có thể truy cập.
| Nhóm API | URL cơ sở | Xác thực và kết quả |
|---|---|---|
| Communications v3 | https://api.multitel.net/v3 | Thông tin xác thực Basic đã được phê duyệt; chỉ dùng token được cấp phát đủ điều kiện cho những thao tác có hỗ trợ. JSON status và response. |
| Đăng ký dịch vụ gọi khẩn cấp | https://api.multi.tel/emergency | Thông tin xác thực Basic đã được phê duyệt hoặc quyền truy cập bearer được cấp phát riêng. JSON code, message và data. |
| Tích hợp REST của cổng thông tin | Máy chủ và thao tác được hiển thị trong tài liệu tham chiếu dành cho nhà phát triển của tài khoản bạn | Hãy dùng thông tin xác thực, phạm vi quyền (scope) và lược đồ đã được ghi trong tài liệu của thao tác đó. Các yêu cầu từ phiên trình duyệt thuộc một giao diện riêng biệt. |
Hãy đặt MULTITEL_API_USERNAME và MULTITEL_API_PASSWORD thông qua cấu hình bí mật của máy chủ bạn trước khi dùng các ví dụ. Tuyệt đối không nhúng chúng vào JavaScript công khai trên trình duyệt, URL hoặc kho quản lý mã nguồn. Thông tin xác thực chuyên dụng được quản lý tại cài đặt tích hợp API.
Chuẩn bị một yêu cầu SMS
Hãy dùng một số gửi đã được phê duyệt, hỗ trợ SMS và thuộc sở hữu của tài khoản, cùng người nhận đã đồng ý nhận tin nhắn; đồng thời hoàn tất đăng ký Brand/Campaign hoặc xác minh số miễn cước cho người gọi (toll-free) theo yêu cầu. Ví dụ bên dưới sẽ gửi một tin nhắn thật khi được điền bằng thông tin xác thực và số điện thoại đang hoạt động; đây không phải là môi trường sandbox.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"Hãy thay các trình giữ chỗ người gửi và người nhận bằng số điện thoại ở định dạng quốc tế, chỉ gồm chữ số và có mã quốc gia. Với MMS, hãy cung cấp URL phương tiện được hỗ trợ và có thể truy xuất công khai trong media, đồng thời xác minh trước tính đủ điều kiện và giá của MMS.
Được chấp nhận không có nghĩa là đã chuyển phát
Hãy kiểm tra cả trạng thái ứng dụng bên ngoài lẫn kết quả nhắn tin được trả về. Ghi lại mã định danh tin nhắn do dịch vụ cung cấp, và theo dõi trạng thái chuyển phát cùng các sự kiện webhook. Việc gửi thành công không thể chứng minh rằng thiết bị của người nhận đã nhận được tin nhắn.
SMS được tính phí theo từng phân đoạn. Mã hóa và độ dài tin nhắn có thể tạo ra nhiều phân đoạn; phí phương tiện và phí liên quan đến nhà mạng có thể khác với SMS. Hãy đọc giá bán hiện tại của tài khoản trước khi gửi. Tuyệt đối không thử lại một cách mù quáng một lần gửi bị hết thời gian chờ: hãy kiểm tra kết quả đã được ghi lại của nó trước.
Xử lý lỗi và thử lại
- Lỗi xác thực hoặc quyền truy cập
- Hãy kiểm tra trạng thái bật của thông tin xác thực API, dịch vụ được phép và giới hạn IP nguồn. Cookie phiên cổng thông tin không phải là thông tin xác thực tích hợp.
- Không đủ tín dụng hoặc chưa đáp ứng điều kiện phê duyệt
- Hãy giải quyết vấn đề số dư tài khoản, phê duyệt gửi tin hoặc yêu cầu về tài liệu trước khi lặp lại thao tác.
- Không có kết quả
- Hãy xử lý kho số trống hoặc không có tên người gọi như một kết quả bình thường. Đừng cho rằng một số hợp lệ về mặt cú pháp thì có đầy đủ mọi dịch vụ.
- Hết thời gian chờ mạng hoặc lỗi dịch vụ
- Với các thao tác đọc, hãy thử lại có giới hạn kèm backoff. Với thao tác mua, gửi hoặc đăng ký, hãy kiểm tra trạng thái thao tác trước; thử lại một yêu cầu đã được chấp nhận có thể tạo ra thao tác bị tính phí trùng lặp.
Khả năng hỗ trợ idempotency tùy thuộc vào từng nhóm API. Emergency API hỗ trợ khóa thử lại; điều đó không làm cho các yêu cầu v3 tùy ý trở nên idempotent. Hãy lưu lại dấu thời gian, ID được trả về và các phản hồi đã ẩn thông tin nhạy cảm để phục vụ hỗ trợ.
Tiếp tục với tài liệu tham chiếu dành cho tài khoản của bạn
Tài liệu tham chiếu sau khi đăng nhập lọc các thao tác theo quyền và các dịch vụ đã bật của bạn. Hãy dùng đúng máy chủ, loại thông tin xác thực, trường yêu cầu và lược đồ phản hồi được nêu trong đó. Các bảng điều khiển có thể thực thi thao tác thực, bao gồm mua hàng và gửi tin nhắn.