API Document

TÀI LIỆU MÔ TẢ KẾT NỐI SMS

Thông Số Kỹ Thuật, Version 1.5

1. Mục đích

  • Để các Partner (đối tác) dễ dàng kết nối các dịch vụ SMS.
  • EB2B đã xây dựng cổng kết nối hai chiều (chiều MO & chiều MT) phục vụ cho việc gửi và nhận SMS (hay còn gọi là SMS Gateway. Cổng kết nối này được xây dựng trên giao thức SOAP/XML.
  • EB2B cung cấp dịch vụ Brand Name SMS, Partner có thể tham khảo 1 trong các mục sau để kết nối API:
    • Kết nối MT theo giao thức RESTful (EB2B cung cấp 2 tùy chọn);
    • Kết nối MT theo giao thức SOAP (EB2B cung cấp 2 tùy chọn);
    • Kết nối MT Send SMS Bulk API với cấu trúc JSON.
  • Dữ liệu trao đổi qua cổng kết nối đều được lưu lại ở hai bên để làm cơ sở tính cước và đối soát khi có khiếu nại xảy ra.

2. Thuật ngữ

STT Tên Mô tả
1. MO (Mobile Originated) Sử dụng cho tin nhắn được gửi từ điện thoại của khách hàng đến tổng đài di động (6x89, 99x, 8x99…)
2. MT (Mobile Terminated) Sử dụng cho tin nhắn trả từ tổng đài di động đến điện thoại của khách hàng
3. Khách hàng Là người sử dụng điện thoại nhắn tin đến tổng đài dịch vụ
4. Partner (Đối tác) Là đơn vị hợp tác với EB2B trong việc sử dụng đầu số dịch vụ di động, thực hiện tiếp nhận các tin nhắn đến (MO) từ tổng đài và trả các tin nhắn kết quả (MT) về cho khách hàng qua tổng đài
5. EB2B Là công ty cung cấp cổng kết nối dịch vụ SMS Gateway
6. SMS Gateway Là hệ thống phần mềm cho phép kết nối đến các tổng đài thông tin di động của các Telco, nhận các tin nhắn đến (MO) từ tổng đài của Telco và chuyển qua các đối tác xử lý đồng thời gửi các tin nhắn đi (MT) tới Telco để gửi cho khách hàng
7. Telcos Các công ty cung cấp dịch vụ viễn thông di động như Mobifone, Vinaphone, Viettel, Vietnamobile, Gmobile

3. Mô hình kết nối

Mô hình kết nối

Hệ thống kết nối SMS gồm có 2 chiều:

3.1. Chiều nhận MO, khách hàng nhắn tin đến đầu số dịch vụ 6089 theo cú pháp quy định trước

  • Tin nhắn MO từ di động của khách hàng đến Telcos.
  • Telco gửi MO sang Gateway SMS của EB2B.
  • Client gửi MO của EB2B sẽ gửi MO sang Webservice nhận MO của Partner. Nếu thành công, lưu lại MO này vào hệ thống billing của EB2B; nếu không gửi được thì client tự động gửi lại sau một thời gian đặt trước.
  • Webservice nhận MO tại Partner sau khi nhận được MO sẽ gửi vào hệ thống xử lý nội dung tin nhắn.
  • Kết thúc chiều nhận MO.

3.2. Chiều gửi MT, tin nhắn được gửi đến di động của khách hàng

  • Hệ thống xử lý SMS tạo nội dung MT theo yêu cầu và chuyển MT sang cho client gửi MT tại Partner.
  • Client gửi MT tại Partner sẽ gửi MT sang Webservice nhận MT tại EB2B. Nếu Webservice nhận MT thành công thì client gửi MT tiến hành lưu MT vào Database logs, dùng cho đối soát sau này. Nếu không thành công thì thực hiện gửi lại sau một khoảng thời gian đặt trước.
  • MT được Gateway SMS của EB2B gửi sang Telco, khi gửi thành công sẽ lưu MT vào hệ thống billing. Nếu không thành công thì gửi lại sau một khoảng thời gian định trước.
  • Telco gửi MT đến di động của khách hàng.
  • Kết thúc quá trình gửi MT.

4. Cấu trúc thông tin trao đổi giữa EB2B và Partner

4.1. Kết nối chiều MO

Kết nối đến Webservice của Partner gồm các trường sau

STT Tên trường Kiểu dữ liệu Mô tả
1. User_ID varchar(15) Số điện thoại khách hàng
2. Service_ID varchar(10) Số dịch vụ - 6x89, 996,997,998 …
3. Command_Code varchar(10) Mã dich vụ - GO, SC, …
4. Info varchar(160) Nội dung tin nhắn khách hàng gửi đến đầu số
5. Request_ID decimal(10) Số thứ tự tin nhắn của khách hàng do hệ thống của EB2B sinh ra, tăng dần và duy nhất

Giá trị trả về:

1: thành công
-1: thất bại

4.2. Kết nối chiều MT

  • Khi Partner muốn gửi nội dung phản hồi cho khách hàng, sẽ gửi thông tin qua Web service cho EB2B qua hàm SendSMS. Chi tiết kết nối được mô tả tại địa chỉ: https://sms.etelecom.vn/Webservice/SendMT2.asmx (opens new window) (account truy cập sẽ được cấp sau, địa chỉ có thể bổ sung hoặc thay đổi sang địa chỉ khác tuỳ theo số lượng Partner kết nối và khi phân tải hệ thống)
  • Đặc tả: Hàm SendSMS của Web service gồm các trường sau:
STT Tên trường Kiểu dữ liệu Mô tả
1. Account_name varchar(20) EB2B sẽ cung cấp cho Partner một tài khoản để gửi
2. Account_password varchar(20) Mật khẩu tài khoản để gửi tin
3. User_ID varchar(15) Số di động gửi đến (Theo chuẩn quốc tế, bắt đầu bằng 84, không phải là 09xxx hay 01xxx)
4. Content varchar(1000) Nội dung tin nhắn
5. Service_ID varchar(10) Số dịch vụ (Các số mà EB2B đang sở hữu: 6x89, 996, 997, 998, 19001255, …).
6. Command_Code varchar(10) Mã của dịch vụ, mã này sẽ phục vụ cho việc thống kê và quản lý MT phát sinh. Ví dụ: GO, SC …
7. Request_ID decimal(10) Số thứ tự tin nhắn của khách hàng do EB2B sinh ra. Số này sẽ do EB2B chuyển sang kèm với nội dung SMS của khách hàng ở kết nối chiều MO. Số này dùng để xác định MT này là của MO nào. Trong trường hợp bản tin phát sinh từ đối tác (không có MO) thì request_id được đặt = 0
8. Message_Type number(1) Loại tin nhắn, giá trị số này là 0 hoặc 1. Trong đó: 0: SMS phát sinh từ dịch vụ, không tính tiền khách hàng; 1: Có trừ tiền của khách hàng.
9. Total_Message number(2) 1 (Mặc định)
10. Message_Index number(2) 1 (Mặc định)
11. IsMore number(1) 0
12. Content_Type number(1) Loại nội dung gửi cho khách hàng (0: Text; 1: ringtone; 2: logo; 4: picture message)

5. Kết nối chiều MT Brand Name và AlphaSMS giữa EB2B và Partner

EB2B cung cấp dịch vụ Brand Name SMS (tin nhắn thương hiệu) và Alpha SMS (0901800020), nội dung trước khi gửi phải được đăng ký dưới dạng Template với nhà mạng. Phía Partner có thể kết nối API thông qua RESTful API

Mô tả Chi tiết
JSON end point https://sms.etelecom.vn/API/Sms/SMSService.svc/ccsms/json
  • Lưu ý: nếu Partner truyền giá trị UUID trong request, EB2B sẽ dùng giá trị này trong cấu trúc Response. Ngược lại, nếu Partner không sử dụng giá trị này thì cần truyền UUID = 0 cho EB2B.
  • UUID tham khảo tại: https://www.uuidgenerator.net/ (opens new window) Ví dụ: UUID: 54abc383-9fec-4dc3-aa03-02067dd4dbad

5.1. HTTP Methods

− Tất cả các request được submit thông qua phương thức HTTP POST, và phải thực hiện việc UTF-8 encoding and URL encoded cho tham số. − Content-Type cho phương thức POST là application/json.

5.2. Xác thực

  • Tất cả các request đều yêu cầu giá trị cho tham số "api_key" và "api_secret", các giá trị này sẽ được EB2B cung cấp.

5.3. Khách hàng gọi API EB2B để gửi SMS

JSON end point

Cấu trúc Resquest và Response cho JSON như sau: Gửi SMS với Sender Brandname SMS hoặc AlphaSMS: https://sms.etelecom.vn/API/Sms/SMSService.svc/ccsms/json

Request data Yêu cầu truyền đầy đủ các field như mô tả bên dưới

{
  "submission": {
    "api_key":"${api_key}",
    "api_secret":"${api_secret}",
    "sms": [
      {
        "id":"${UUID}",
        "brandname":"${brandname or AlphaSMS}",
        "text":"${text}",
        "to":"${recipient}",
        "feetypeid": "0",
        "msgcontenttypeid": "12"
      }
    ]
  }
}

// Ví dụ:
// Brandname SMS:
{
  "submission": {
    "api_key":"54xb216",
    "api_secret":"83cz115",
    "sms": [{
      "id":"54abc383-9fec-4dc3-aa03-02067dd4dbad",
      "brandname":"EB2B",
      "text":"Hi There !",
      "to":"0975783183",
      "feetypeid": "0",
      "msgcontenttypeid": "12"
    }]
  }
}

// Alpha SMS:
{
  "submission": {
    "api_key":"54xb216",
    "api_secret":"83cz115",
    "sms": [{
      "id":"54abc383-9fec-4dc3-aa03-02067dd4dbad",
      "brandname":"901800020",
      "text":"Day la tin nhan duoc gui ra tu he thong EB2B",
      "to":"0975783183",
      "feetypeid": "0",
      "msgcontenttypeid": "12"
    }]
  }
}

Mô tả giá trị các fields:

  • text: Nội dung tin nhắn, đã được đăng ký template từ trước
  • feetypeid:
    • 0: Gửi bằng brandname
    • 1: Gửi bằng đầu số (6089) - có tính phí MO
  • msgcontenttypeid:
    • 0: Gửi tin nhắn không dấu
    • 12: Gửi tin nhắn có dấu

Response data

{
  "submission": {
    "sms": [
      {
        "id": "54abc383-9fec-4dc3-aa03-02067dd4dbad",
        "status": "",
        "error_message": ""
      }
    ]
  }
}

6. Kết nối chiều MT Send SMS Bulk API

  • Khi Partner muốn gửi tin nhắn 1 http request với nhiều SMS có nội dung Chăm sóc khách hàng cho khách hàng, với Sender là Brandname SMS hoặc Alpha SMS, gửi thông qua API EB2B cấp. Link gọi vào https://sms.etelecom.vn/smsapi/Service.svc/submission. Giới hạn cho một lần request data với body truyền vào từ 1 đến 100 SMS.

  • SMS mà Partner gửi thông qua API có cấu trúc là JSON. Với Content-Type cho phương thức POST là application/json

    Tham số Mô tả
    api_key tham số này do EB2B cấp
    api_secret tham số này do EB2B cấp
    id mỗi SMS mà Partner truyền vào có id là duy nhất, EB2B dựa vào id này để response về status tương ứng với id gửi sang EB2B
    brandname là thương hiệu (Brandname) đăng ký để gửi tin hoặc Alpha SMS (0901800020)
    text nội dung tin nhắn cần gửi
    to số điện thoại nhận tin

Request Data

{
  "submission": {
    "api_key": "EB2B cấp",
    "api_secret": "EB2B cấp",
    "sms": [
      {
        "id": "123",
        "brandname": "EB2B",
        "text": "EB2B test SMS 1",
        "to": "0375388376"
      },
      {
        "id": "124",
        "brandname": "EB2B",
        "text": "EB2B test SMS 2",
        "to": "0966118093"
      },
      {
        "id": "125",
        "brandname": "EB2B",
        "text": "EB2B test SMS 3",
        "to": "0966118092"
      },
      {
        "id": "126",
        "brandname": "EB2B",
        "text": "EB2B test SMS 4",
        "to": "09975783183"
      },
      {
        "id": "127",
        "brandname": "EB2B",
        "text": "EB2B test SMS 6",
        "to": "0586040215"
      },
      {
        "id": "128",
        "brandname": "EB2B",
        "text": "EB2B test SMS 7",
        "to": "0586040216"
      },
      {
        "id": "129",
        "brandname": "EB2B",
        "text": "EB2B test SMS 8",
        "to": "0586040217"
      },
      {
        "id": "130",
        "brandname": "EB2B",
        "text": "EB2B test SMS 9",
        "to": "0586040218"
      },
      {
        "id": "131",
        "brandname": "EB2B",
        "text": "EB2B test SMS 10",
        "to": "0586040219"
      },
      {
        "id": "132",
        "brandname": "PHUC",
        "text": "EB2B test SMS 11",
        "to": "0586040210"
      }
    ]
  }
}

Response Data

{
  "submission": {
    "sms": [
      {
        "id": "123",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "124",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "125",
        "status": 0,
        "error_message": " Thành công"
      },
      {
        "id": "126",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "127",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "128",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "129",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "130",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "131",
        "status": 0,
        "error_message": "Thành công"
      },
      {
        "id": "132",
        "status": 0,
        "error_message": "Thành công"
      }
    ]
  }
}

7. Các ký tự đặc biệt

Các ký tự đặc biệt sau được tính 2 ký tự:

^ { } [ ]
~
\
|
\n

8. Quy tắc tách bản tin theo nội dung tin

Khi Partner gửi tin nhắn có chiều dài > 160 ký tự thì tin nhắn được tính như sau:

  • 1 SMS: từ 1 đến 160 ký tự.
  • 2 SMS: từ 161 ký tự đến 306 ký tự.
  • 3 SMS: từ 307 ký tự đến 459 ký tự.

9. Các trạng thái trả về chiều MT dịch vụ Brand Name SMS và Alpha SMS

ID Mô tả
0 Gửi thành công
2 Lỗi hệ thống
3 Sai user hoặc mật khẩu
4 IP không được phép
5 Chưa khai báo brandname/dịch vụ
6 Lặp nội dung
7 Thuê bao từ chối nhận tin
8 Không được phép gửi tin
9 Chưa khai báo template
10 Định dạng thuê bao không đúng
11 Có tham số không hợp lệ
12 Tài khoản không đúng
13 Gửi tin: lỗi kết nối
14 Tài khoản không đủ
15 Tài khoản hết hạn
16 Hết hạn dịch vụ
17 Hết hạn mức gửi test
18 Hủy gửi tin (CSKH)
19 Hủy gửi tin (KD)
20 Gateway chưa hỗ trợ Unicode
21 Chưa set giá trả trước
22 Tài khoản chưa kích hoạt
25 Chưa khai báo partner cho user
26 Chưa khai báo GateOwner cho user
27 Gửi tin: gate trả mã lỗi
31 Số điện thoại 11 số đã chuyển sang 10 số

← Tổng đài →