Gởi tin nhắn chủ động


Tổng quan

API SMS FPT cho phép bạn triển khai ứng dụng client có thể gửi tin nhắn chủ động đến khách hàng của bạn thông qua tổng đài tin nhắn của FPT.

Mô tả

Sơ đồ hệ thống

Sơ đồ hệ thống của API SMS FPT

Chuẩn bị

Bên đối tác:

- Tên ứng dụng không quá 200 kí tự

- IP Server gọi API RESTFull

- Sau khi được FPT cung cấp account truy cập vào trang quản lý ứng dụng. Bên đối tác tiến hành đăng ký ứng dụng với các thông tin trên để lấy CLIENT_IDCLIENT_SECRET ở môi trường sandbox

- Bên đối tác sử dụng tài liệu của FPT cung cấp để kết nối đến sandbox

- Sau khi kết nối đến sandbox thành công. Đối tác chuyển sang sử dụng các thông tin ở môi trường live để chạy ứng dụng.

Bên FPT:

- Khi tiến hành kết nối, FPT sẽ cung cấp cho đối tác thông tin tài khoản để đăng ký các thông tin như:

  • CLIENT_ID
  • CLIENT_SECRET

- Tài liệu:

  • Gửi tin nhắn chủ động
  • Code ví dụ
    • PHP
    • JSP
    • ASP.NET
  • SDK
    • PHP
    • JSP
    • ASP.NET

Thiết lập thư viện

Một số thư viện client được cung cấp trong các ngôn ngữ khác nhau. Các thư viện này sẽ giúp bạn có thể dễ dàng hơn trong việc tương tác với API SMS FPT.

Để sử dụng được API bạn cần phải đăng ký thông tin ứng dụng để nhận CLIENT_IDCLIENT_SECRET. Để xem hướng dẫn đăng ký, vui lòng click vào đây.

- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/php-tech-sdk-lastest.zip sau đó giải nén ra vào project của bạn.

- Thiết lập cấu hình của bạn trong file path/to/TechAPI/bootstrap.php.

- Thêm đoạn code sau trong project của bạn:

- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/jsp-tech-sdk-lastest.zip sau đó giải nén và include vào project của bạn.

- Tạo file YourProject/src/java/techsdk.properties với nội dung như sau:

- Trong Servlet hoặc Controller của bạn thiết lập như bên dưới:

- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/dot-net-tech-sdk-lastest.zip sau đó giải nén và add reference hai file TechSDK.dll, Newtonsoft.dll vào project của bạn.

- Tạo file Config.cs trong thư mục App_Code của bạn với nội dung như sau:

 

Gọi API gửi tin nhắn

API SMS FPT phát triển dựa trên mô hình cấp phát API bảo mật OAuth 2.0. Để có thể đơn giản trong việc tích hợp ứng dụng, bạn nên sử dụng thư viện do chúng tôi cung cấp.

- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/php_client_demo.zip

- Trong bộ API SMS FPT có sử dụng thư viện JSON, nên bạn cần phải import thư viện JSON vào project của bạn. Nếu như chưa có, bạn có thể tải thư viện JSON về tại đây

- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/jsp_client_demo.zip

- Lưu ý: Source tham khảo sử dụng mô hình Spring Web MVC Framework, và kết nối cơ sở dữ liệu MySQL bằng thư viện JDBC MySQL

- Trong WebForm bạn xử lý như sau:

- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/dot-net-client-demo.zip

Tham số đầu vào

Tên tham số Kiểu dữ liệu Bắc buộc Mô tả
ServiceNum String Đầu số gửi tin nhắn đã đăng ký với FPT.
MOId Int ID của tin nhắn MO.
Syntax Int Cú pháp tin nhắn dịch vụ.
Phone String Số điện thoại của người nhận tin nhắn, chỉ được gửi 01 lần 01 số điện thoại. VD:
0943533xxx, 01234010xxx, 84943533xxx hoặc 841234010xxx
Message String Nội dung của tin nhắn. Phải được mã hóa base64, nếu sử dụng thư viện của FPT cung cấp thì nội dung sẽ được tự động mã hóa.

Dữ liệu trả về

Tên tham số Kiểu dữ liệu Mô tả
MTActiveId Int Id của tin chủ động gửi đi.
MOId Int Id tin nhắn MO.
ServiceNum String Đầu số tin nhắn gửi đi.
ServiceNumGroup String Nhóm đầu số dịch vụ.
Telco String Nhà mạng.
Phone String Số điện thoại nhận tin nhắn.
Syntax String Cú pháp dịch vụ.
Message String Nội dung tin nhắn.
PartnerId String Mã đối tác.

Bảng mã lỗi

Mã lỗi Mô tả
Lỗi phản hồi từ server
1001 Request không hợp lệ.
1002 Client không được cấp phép truy cập.
1003 Truy cập bị từ chối.
1004 Loại response yêu cầu không được hỗ trợ.
1005 Các scope không hợp lệ
1006 Lỗi server.
1007 Server tạm thời không thể xử lý request từ client.
1008 Thông tin client không đúng.
1009 Loại hình cấp quyền không hợp lệ.
1010 Scope không đủ để truy cập API
1011 Access token không hợp lệ
1012 Access token đã bị thay đổi
1013 Access token hết hạn
1014 Các tham số truyền vào bị lỗi
1015 Không hỗ trợ kiêu loại hình cấp quyền này
Lỗi xảy ra ở client
2001 CLIENT_ID bắt buộc và không được trống.
2002 CLIENT_SECRET bắt buộc và không được trống.
2003 Access token hết hạn.
2004 Thời gian kết nối bị quá hạn.

Nhận tin nhắn từ MO


Tổng quan

Webservice Soap giúp cho FPT lấy được tin nhắn MO từ đối tác.

Mô tả

  • Chuẩn webservice: Soap.

Sơ đồ hệ thống

Sơ đồ hệ thống Soap MO

Chuẩn bị

Bên đối tác:

- Server hoặc Hosting để chứa ứng dụng

- URL của Webservice SOAP để bên FPT đẩy tin nhắn sang

- Nội dung tin nhắn trả về cho khách hàng theo tin nhắn của FPT đẩy sang.

Bên FPT:

- Cung cấp tài liệu cho đối tác:

  • Gửi tin nhắn MT theo MO
  • Code ví dụ
    • PHP
    • JSP
    • ASP.NET

- Tiến hành cấp cú pháp cho đối tác.

- Sau khi đối tác xây dựng xong Webservice SOAP và cung cấp URL gọi Webservice SOAP cho FPT. FPT tiến hành kiểm tra hoạt động của Webservice bên đối tác. Khi kết nối thành công. FPT sẽ cấu hình kết nối dịch vụ đến cú pháp mà đối tác đã đăng ký.

Thiết lập Webservice

Một số thư viện client được cung cấp trong các ngôn ngữ khác nhau. Các thư viện này sẽ giúp bạn có thể dễ dàng hơn trong việc tương tác với API SMS FPT.

- Đối với PHP bạn sử dụng thư viện nusoap. Download tại đây

- Hoặc tải code mẫu tại đây

- Bước 1: Tạo file functions.php (Chưa hàm thực thi) có nội dung như sau

- Bước 2: Tạo file server.php

- Bước 3: Tạo file client.php trả về kết quả

- Xem link hướng dẫn tạo WebService JSP bằng NetBeans tại đây

- Xem code mẫu tại đây

- Trong project Web tạo file WebService có phương thức ReceiveResponse có nội dung như sau:

- Đối với ASP.Net trong project bạn thêm một Item Web Service(ASMX) có tên Webservice.asmx

- Sau đó mở file Webservice.cs trong thư mục App_Code và thay đổi như file dưới đây

- Hoặc tải code mẫu tại đây

Tham số đầu vào

Tên tham số Kiểu dữ liệu Bắc buộc Mô tả
MOId Int ID của tin nhắn MO.
Telco String Nhà mạng: viettel, vina, mobi...
ServiceNum String Đầu số tin nhắn gửi đi.
Phone String Số điện thoại của người nhận tin nhắn, chỉ được gửi 01 lần 01 số điện thoại. VD:
0943533xxx, 01234010xxx, 84943533xxx hoặc 841234010xxx
Syntax String Cú pháp tin nhắn dịch vụ.
EncryptedMessage String Nội dung của tin nhắn ở dạng mã hóa base64.
Signature String Signature = SHA1(MOId + ServiceNum + Phone + MessageRequest + PrivateKey).
Trong đó:
MessageRequest = TOLOWER(Base64Decode(EncryptedMessage))

Dữ liệu trả về

- Xử lý và trả về kết quả theo định dạng MessageCode|MessageResponse

Tham số Kiểu dữ liệu Bắt buộc Mô tả
MessageCode String Trạng thái xử lý, có 2 giá trị:
- 01: Quá trình xử lý không thành công, có lỗi.
- 00: Quá trình xử lý thành công, trả về nội dung tin nhắn.
MessageResponse String Nội dung trả về:
- Thông báo lỗi.
- Nội dung tin nhắn.
Ví dụ:
- Thành công: 00|Bạn đã đăng ký thành công dịch vụ sms của FPT
- Có lỗi: 01|Tham số truyền vào không chính xác