網站地圖 | FAQ | 客戶服務 | 發送簡訊
 
     回程式開發 伺服器位置 傳送訊息格式 回傳訊息格式 回傳碼意義
 
Socket to Air伺服器 IP : api.hiair.hinet.net (202.39.54.130)
 
 
Socket to Air伺服器 Port : 8000
 
 
  如有 架設防火牆,請記得開通。
 
 


struct CLIENT_SendMsg_STRUCT {
   unsigned char msg_type;
   unsigned char msg_coding;
   unsigned char msg_priority;
   unsigned char msg_country_code;
   unsigned char msg_set_len;
   unsigned char msg_content_len;
   char msg_set[100];
   char msg_content[160];
} ;

 
 
 
1.msg_type : 訊息型態
   0:帳號密碼檢查
   1:傳送文字簡訊
   2:查詢文字簡訊傳送結果
   3:接收文字簡訊 (一般用戶不開放)
 13:傳送 WAP PUSH
 14:查詢WAP PUSH 傳送結果
 15:傳送國際簡訊
   查詢國際簡訊傳送結果請用msg_type=2即可。
 16:取消預約文字簡訊
 
 
2.msg_coding : 訊息編碼種類
 1:big5
 2:binary
 3:unicode(UCS-2)
 4:unicode(UTF-8)
 
 
3. msg_priority : 訊息優先權 (此功能不開放)
 
 
4. msg_country_code : (保留用途)
 
 
5. msg_set_len : 為msg_set[ ] 訊息內容的長度,注意:此處包含字串最後結尾的‘\0’符號
 
 
6. msg_content_len : 為msg_content[ ] 訊息內容的長度
 •msg_type = 1、15:msg_content[ ]訊息內容的長度,不包含字串最後結尾的‘\0’符號
 •msg_type = 13:Wap Push 時,msg_content[ ]內容的兩個Item間 (含最後一個Item) 必須用null(\0)來作為區隔;
  msg_content[ ]訊息內容的長度包含字串最後結尾的‘\0’符號。
 
 
7. msg_set : 訊息相關資料設定,其格式說明如下:每一Item 間 (含最後一個Item) 必須用null(\0)來作為區隔。
msg_type = 0
 
用戶帳號 \0 用戶密碼 \0
msg_type = 1、15
  •即時傳送,傳送形式=01
 
接收門號 \0 傳送形式 \0
   
  •即時傳送加重送截止時間,傳送形式=02
 
接收門號 \0 傳送形式 \0 重送截止時間 \0
   
  •預約傳送,傳送形式=03
 
接收門號 \0 傳送形式 \0 預約時間 \0
   
  •預約傳送加重送截止時間,傳送形式=04
 
接收門號 \0 傳送形式 \0 預約時間 \0 重送截止時間 \0
msg_type = 2、14、16
 
MessageID \0
msg_type = 3
  接收簡訊,不用填入任何資料
msg_type = 13
 
接收門號 \0 傳送形式 \0
     
msg_set : 訊息相關資料設定,其格式說明如下
  •每一Item 的長度限制:
 
用戶帳號 8
用戶密碼 8
接收門號(國內) 10
接收門號(國外) 20
傳送形式 2
預約時間 12
重送截止時間 4
MessageID 20

•傳送形式:
 01 -->立即傳送,若為WAP PUSH 則為Service Indication
 02 -->立即傳送加重送截止時間,若為WAP PUSH 則為Service Loading(目前不提供SL)
 03 -->預約傳送
 04 -->預約傳送加重送截止時間

•預約傳送時間之格式:yymmddhhmmss:

 
yy 不含世紀之西元年(例如 06,07...)
mm 01~12
dd 01~31
hh 01~23
mm 01~59
ss 01-59

•重送截止時間之格式:mmmm

 
mmmm 0001 ~ 1440,單位分鐘
 
 
8. msg_content : 簡訊內容
msg_type = 0、2、3、14、16
  不用填
msg_type = 1、15
 

簡訊內容

    ※內容長度限制159,即使用BIG5與UCS-2編碼時,中、英文字混合可到70個字,純英文字或數字可到159個字。
   
msg_type = 13
 
WAP URL \0 WAP標題 \0
    •WAP URL與 WAP訊息兩者合計最多90byte,每個半形英文、數字算一個byte,每個全形的英文、
    數字、符號與中文字則算成三個bytes。
•WAP URL與WAP標題皆需有值,且WAP URL要http開頭
•WAP URL目前只開放使用半形的英文、數字、符號。
 
 


struct CLIENT_RetMsg_STRUCT {
   unsigned char ret_code ;
   unsigned char ret_coding ;
   unsigned char ret_set_len;
   unsigned char ret_content_len;
   char ret_set[80];
   char ret_content[160];
} ;

 
 
 
建立連線 --> 帳號/密碼確認 (msg_type = 0)
ret_code ret_content 原 因
0 ID/Password check successful 帳號/密碼檢查成功
1 Password error 密碼錯誤
2 The account not exist 帳號不存在
3 Over the maximun allowed connection numbe 超過允許的最大連線數目
4 The account status not correct 帳號狀態不正確或已退租
5 get account data error 無法取得帳號資料
6 get password data error 無法取得密碼資料
7 System error, try again later 暫時無法檢查帳號/密碼
 
 
訊息傳送 (msg_type = 1、13、15)
 
ret_code ret_content 原 因
0 messageid(用於查詢傳送結果) 訊息傳送成功
1 Country code format error 國別格式錯誤
2 Coding format error 編碼格式錯誤
3 Priority format error 優先權格式錯誤
4 Msg_content_len format error Msg_content_len格式錯誤
5 Msg_content_len not the same with msg_content Msg_content_len與msg_content的長度不相符
6 Telphone number format error 接收手機號碼格式錯誤
7 Transfer type format error 傳送型式的格式錯誤
8 Limit time format error 限時傳送格式錯誤
9 Ordered time format error 預約傳送格式錯誤
10 send to forign not allow now 目前暫不開放傳送至國外
11 Message sending failure, try again 系統暫時無法傳送訊息
13 wappush url length is zero wap push的url沒有設定
14 wappush msg_content length bigger than 88 wap push的訊息內容超過88個byte
16 message has 9-10 digits tel number 簡訊內容包含連續9-10碼的電話號碼,不合規定。
22 message content deny 簡訊內容不合規定(疑似詐財簡訊)
 
 
查詢訊息傳送結果 (msg_type = 2、14)
ret_code ret_content 原 因 備註
0 Successful 訊息已送達對方(包含送達時間)  
1 Mobile turn off/Mobile out of scope 手機未開或在受訊範圍外(系統會Retry) 可重查
2 System contains no data 系統無此messageID的資料
發送後馬上做查詢可能會產生此結果,建議稍後再查詢
可重查(20150821 update)
3 MessageID format error MessageID 格式有誤  
4 has send to SMC, query no complete 已送至簡訊中心,尚未完成結果回報 可重查
5 Ordered time beyond xx hours 預約傳送時間有誤  
6 Send binary data to pager 傳送二進位訊息到呼叫器  
7 Code transfer fail 訊息轉碼失敗  
8 telephone number or message content format error 手機號碼或簡訊內容格式錯誤  
9 has expired at queue server 簡訊在Queue Server端,已過期  
10 SMC without the data OR over re-transmission time 簡訊在簡訊中心已被移除或超過重送時間  
15 Message status unknown 訊息狀態有誤  
16 Message sending failure 傳送失敗(例如預約時間小於目前時間等問題)  
17 Message can not send to GSM/Pager 訊息無法送達對方  
18 other error 無法判斷的錯誤訊息  
19 Message is submitted to SMSC 訊息已送至簡訊中心 可重查
20 reserve message, waiting send 預約簡訊,等待傳送中。  
21 reserve message, cancel send 預約簡訊,已取消傳送。  
22 message content deny 簡訊內容不合規定(疑似詐財簡訊)  
23 Message is barred by customer 受訊客戶要求拒收加值簡訊,請不要重送  
 
 
 
※備註欄為可重查,表示簡訊尚在發送中,可過一段時間再查詢最新狀態
※一般查詢發送結果時,常見的code值為0、1、17。0表示已發送成功到接收方,1表示還在發送中,17表示發送失敗(通常為門號失效、手機長時間關機等因素)。
 
 
接收簡訊 (msg_type = 3)(一般用戶不提供此功能)
ret_code ret_content 原 因
0 Message 簡訊內容
1 No Data 系統無待接收之簡訊
2 Get data error, try again 系統失敗
 
     
 
取消預約文字簡訊 (msg_type = 16)
ret_code ret_content 原 因
0 Successful 取消成功
1 Message is not reserving 此簡訊目前非預約狀態
2 System contains no data 系統無此訊息
3 MessageID format error MessageID 資料有誤
 
     
 
其它 值說明
ret_code ret_content 原 因
30 Message length is smaller than definition 傳送的訊息長度有誤
31 network error, try again 網路傳輸發生錯誤
32 msg_type not know 訊息種類無法辨識
40 dataBase error 系統內部錯誤
41 System internal error, try again later 系統內部錯誤
50 ID/Password has not been checked 尚未經過密碼檢查就發送
51 ID/Password checking again 已通過密碼檢查,又送來帳號密碼檢查
52 text Service not apply yet 文字簡訊傳送未申請
53 receive text service not apply yet 接收文字簡訊未申請
58 foreign message not apply yet 國際簡訊未申請
 
   
 
ret_coding : 訊息編碼種類
1:big5
2:binary
3:unicode(ucs-2)
 
   
 
ret_set_len : ret_set 訊息內容的長度,注意:此處包含字串最後結尾的‘\0’符號
 
   
 
ret_content_len : ret_set 訊息內容的長度,注意:此處包含字串最後結尾的‘\0’符號
•msg_type = 3:ret_content訊息內容的長度,不包含字串最後結尾的‘\0’符號;此時ret_content資料內容
    代表手機回傳的訊息,
•msg_type = 0、1、2、13、14 、15、16:ret_content訊息內容的長度,不包含字串最後結尾的‘\0’符號;
    此時ret_content的資料內容為ret_code的描述或傳訊成功的messageID
 
   
 
ret_set : 目前僅msg_type=3,接收訊息時會用到,其格式說明如下,每一Item間以null(\0)來作為區隔。
發送者手機號碼 \0 發送時間 \0 接收的用戶代碼 \0 哪家電信業者 \0
 
     
 
ret_content : 訊息內容
•msg_type = 3:手機傳回的訊息內容
•msg_type = 0、1、2、13、14、15、16:ret_code的描述或傳訊成功的messageID
 
     
  注意事項  
 
 
  1.傳送訊息或接收訊息的資料結構,其資料長度不足部分請依據規格一律補滿,建議補‘\0’字元;所以每次傳送
   訊息的資料結構長度為266個byte,接收訊息的資料結構長度為244個byte。
    2.每種程式語言對字串的處理方式不同,如要取得接收訊息傳回的訊息代碼,請記得擷取ret_content_len 長度
  的資料。
    3.簡訊費用計算皆以實際總字數所需則數計算(包含長、短簡訊)收取。例如:內容總長度300字的簡訊,
   用短簡訊格式發送會切成5則送到手機並顯示為5則,收取5則費用;用長簡訊格式發送也需要5個分則,
   但會連在一起顯示成一大則,收取5則費用。
    4.簡訊發送成功後,系統會回傳訊息代碼(MessageID),用戶端程式稍後(最好10分鐘以後)可以利用此訊息代碼來
   查詢剛剛傳送的簡訊是否有送達對方手機。若沒取得訊息代碼,則不算發送成功。
    5.如有使用接收簡訊功能,用戶端向系統詢問有無手機回覆訊息,若有會馬上將簡訊內容回傳至用戶端,若無則會
   Delay 3秒鐘才回傳 "無資料" 之訊息至用戶端。
    6.使用WAP Push功能時,msg_coding(訊息編碼種類)一律為 big5編碼,且不支援預約功能。
    7.國際簡訊除了msg_type設為15外,其接收門號的第一個字需用+表示,如+869123456782。
  8.為確保系統資源與服務品質,若客戶端API在1分鐘內未進行發訊或查詢,簡訊主機與COM元件會主動關閉逾時
  之連線,COM元件會收到代碼-4。
 
 
 

中華電信股份有限公司All Right Reserved. 版權所有.盜版必究 | 隱私權聲明