繁体中文

應用程式編輯程式介面(SMS API)

請一定要看 如何在您做任何更深入的工作之前,謝謝!

發送簡訊API

功能: sendSms

發送 GSM 以及 Unicode 簡訊. 自動串連成長簡訊 最高至5則 (765個字元).
Returns a JSON object confirming the request (or stating an error).

POST/GET 範例

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

指令參數

參數 說明 種類
number 國際形式的手機號碼. 例如 49123456789 或 +49123456789 或 0049123456789 string
message 簡訊內文. My-Cool-SMS 自動偵測所輸入的編碼,並照著此編碼處理簡訊為 GSM 或 Unicode.
您可使用自選Unicode參數強制建立一個特定的編碼, 如果 Unicode 的設定是 true, 簡訊將會以 Unicode 發送並且必須以 Unicode UCS2 標記法來提供訊息參數. 如果 Unicode 的設定是 false, 簡訊將會以 GSM 發送並且訊息參數必須包含只有 GSM7 字母的字元.
長簡訊會自動串連成一封來寄送. GSM 簡訊可容納長達765個字元或是 Unicode 長達335個字元.
請記住當您送出 GET 請求時, 務必要使用 unicode 參數
string
注意事項: 尋找更多關於 GSM, UnicodeUCS2.

自選參數

參數 說明 種類
unicode 在簡訊上強制建立特定的 Unicode 或 GSM 編碼. 如果設定為 true, 訊息參數必須以 UCS2 標記法發送. 如果設定為 false, 則訊息參數必須包含只有 GSM7 字母的字元.
如果沒有設定或是設定為 NULL, My-Cool-SMS 將會自動偵測輸入的編碼
boolean
senderid 國際形式的手機號碼, 例如: +44123456789或是一個11字元內字母與數字組合的發訊者ID, 例如: Company string
scheduletime 在特定的時間發送簡訊. 使用ATOM格式和時區, 例如: "2011-04-17T17:59:36.67+08" 或 "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl 回調URL來接收此則簡訊的狀態更新和傳送報告. 例如: http://www.myserver.com/callback.php string
注意事項: 尋找更多關於 傳送報告回調.

成功回報範例

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "callbackurl":"http://www.my-server.com/callback.php"
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
smsid 此則簡訊的唯一識別碼. 建議將其妥善保存並做為傳送報告的參考 string(32)
body Unicode 的簡訊內文 string
bodyucs2 UCS2 位元組碼標記法的簡訊內文 string
bodygsm7 GSM7 位元組碼標記法的簡訊內文 (或是NULL, 如果簡訊以 Unicode 發送) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled 顯示目的地號碼是否支援動態發訊者ID boolean
unicode 顯示簡訊是否以 Unicode 或 GSM 發送 boolean
numchars 顯示簡訊中包含幾個字元 integer
escapenumchars 顯示幾個字元必須被移除 integer
smscount 顯示簡訊是否已串連成一封長簡訊並提供已使用的則數 integer
charge 顯示此則簡訊從帳戶中扣除多少金額 float
balance 帳戶餘額 float
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl 此則訊息的狀態更新和回傳報告將會被送至指定的回調URL string || NULL

功能特定的API錯誤

錯誤代碼 錯誤說明
210 電話號碼不正確
211 訊息參數空白
212 訊息參數過長
213 Unicode參數是設定來強制建立Unicode, 但是此訊息參數不是以UCS2標記法發送
214 Unicode參數是設定來強制建立GSM, 但是此訊息參數不是以UCS2標記法發送
215 Unicode參數是設定來強制建立GSM, 但是此訊息參數包含了 GSM7 字母以外的字元
216 The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).
217 不允許輸入發訊者ID簡碼
218 callbackurl 參數不正確
219 日程表時間不正確. 使用ATOM格式和時區, 例如: "2011-04-17T17:59:36.67+08" 或 "2011-04-17 17:59:36-02"
注意事項: 另外也查看一般性錯誤章節

接收的簡訊API

回調: pushIncomingSms

My-Cool-SMS會自動將SMS資料送至您的伺服器如果您的收件箱設定中有一個明確的屬於您號碼的回調URL. 您可以利用My-Cool-SM網站介面在收件箱設定中編輯您的回調URL

回調範例

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}
注意事項: 由此觀看 here 更多如何處理 JSON 回調的資訊.

回調值

關鍵 說明 種類
from 與訊息一併發送的發訊者ID. 可以為一個國際形式的號碼或一個字母與數字的組合ID string
fromcountrycode 如果參數為一個號碼, 則包含2個字元的發訊者ISO國家代碼. 如果參數為一個字母與數字組合, 則包含NULL string(2) || NULL
to 接收訊息的號碼(您的虛擬電話號碼) string
unicode 顯示此訊息是否以Unicode或是GSM發送 boolean
smscount 顯示簡訊是否已串連成一封長簡訊並提供已使用的則數 integer
body Unicode 的簡訊內文 string
bodyucs2 UCS2 位元組碼標記法的簡訊內文 string
bodygsm7 GSM7 位元組碼標記法的簡訊內文 (或是NULL, 如果簡訊以 Unicode 發送) string
numchars 顯示簡訊中包含幾個字元 integer
escapenumchars 顯示幾個字元必須被移除 integer
cost 顯示此則簡訊從帳戶中扣除多少金額 float

功能: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing inbound SMS. Can be customized by using the optional parameters.

POST/GET 範例

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

指令參數

參數 說明 種類

自選參數

參數 說明 種類
thresholdid Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0. integer
limit The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied. integer
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string(2)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

成功回報範例

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
total The total number of messages on this virtual number integer
fetched The number of messages that were fetched integer
maxid The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages. integer
minid The lowest sms id found for this user. Can be used for client side reference. integer
messages Contains an array of SMS text objects (with self-explaining attribute names, see example). array

功能特定的API錯誤

錯誤代碼 錯誤說明
232 電話號碼不正確
233 The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.
234 The provided thresholdid is invalid
235 無效的限制參數
236 Invalid order parameter
242 No virtual numbers found.
注意事項: 另外也查看一般性錯誤章節

餘額查詢API

功能: getBalance

回傳一個包含帳戶餘額的JSON物件(或是錯誤說明)

POST/GET 範例

username=xxx&password=yyyy&function=getBalance

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

成功回報範例

{
    "success":true,
    "balance":752.210
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
balance 歐元餘額 float

傳送回報API

有2種方法從My-Cool-SMS接收傳送報告.

功能: getDeliveryReport

回傳一個單一簡訊的傳送報告(以sendSms發送)或是一個組群郵件名單的傳送報告(以sendMailings發送). 如果組群郵件名單的傳送報告因為groupkey參數的設定選項為true而被要求的話, 回傳的物件可能包含一個總覽(default)或是每位收訊人的個別傳送報告(藉由將自選參數mailingdetails設定成true)

POST/GET 範例

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

指令參數

參數 說明 種類
id Reference ID. Either an sms id (as returned by sendSms) or a mailing group key (as returned by sendMailing).
If a group key is used, the optional parameter groupkey must be set to true.
string

自選參數

參數 說明 種類
groupkey 設定成"true",如果ID參數有提供groupkey且您需要一個郵件名單發送紀錄的傳送報告(不是單一簡訊)回傳的話. Default 為 false string
mailingdetails 設定成"true", 如果您要一個郵件名單中每位收訊者個別的傳送報告做為另外的摘要. Default 為 false string

成功回報範例: groupkey=false (系統默認值)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

成功回報值: groupkey=false (系統默認值)

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
smsid 與傳送報告一起的sms id string
status 顯示此則簡訊的狀態 string
注意事項: 由此查閱 here 更多的狀態代碼說明

成功回報範例: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}
注意事項: 由此查閱 here 更多的狀態代碼說明

成功回報範例: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}
注意事項: 由此查閱 here 更多的狀態代碼說明

功能特定的API錯誤

錯誤代碼 錯誤說明
223 未知的簡訊ID
224 未知的GroupKey
注意事項: 另外也查看一般性錯誤章節

功能: getDeliveryReports

Returns delivery reports for a list of messages.

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

指令參數

參數 說明 種類
ids An array of sms ids to perform the delivery status lookup for. array[]

成功回報範例:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

成功回報值:

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
注意事項: 由此查閱 here 更多的狀態代碼說明

功能特定的API錯誤

錯誤代碼 錯誤說明
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
注意事項: 另外也查看一般性錯誤章節

功能: getRecentReports

回傳一個JSON物件包含最近最常發送的訊息的傳送報告

POST/GET 範例

username=xxx&password=yyyy&function=getRecentReports&limit=10

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

指令參數

參數 說明 種類
limit 顯示應回傳的報告份數 integer

成功回報範例

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
number 目的地電話號碼 string
senderid 與訊息一併發送的發訊者ID string
body Unicode 的簡訊內文 string
bodyucs2 UCS2 位元組碼標記法的簡訊內文 string
bodygsm7 GSM7 位元組碼標記法的簡訊內文 (或是NULL, 如果簡訊以 Unicode 發送) string
unicode 顯示簡訊是否以 Unicode 或 GSM 發送 boolean
timesent 簡訊發送的時間 timestamp with time zone
status 顯示此則簡訊的狀態 string
注意事項: 由此查閱 here 更多的狀態代碼說明

功能特定的API錯誤

錯誤代碼 錯誤說明
225 無效的限制參數
注意事項: 另外也查看一般性錯誤章節

回調: pushDeliveryReport

My-Cool-SMS automatically pushes a delivery report to your server if the callbackurl parameter is set when sending via the sendSms function. The callback is sent as raw data JSON request.

回調範例

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}
注意事項: 由此觀看 here 更多如何處理 JSON 回調的資訊.

回調值

關鍵 說明 種類
smsid 簡訊的唯一識別碼和參考. 在sendSms功能上smsid成功回應的被回傳 string(32)
status 顯示此則簡訊的狀態 string

狀態參考

Status 說明
SMS_STATUS_QUEUED 等候發送中 - 此則簡訊目前正在等候發送中
SMS_STATUS_AT_CARRIER 電信業者處理中 - 此則簡訊以傳送至電信業者且一旦簡訊傳送至指定手機後便會顯示成'已傳送'.
請注意有些例外的時候,業者不會提供傳送報告,此時,即便簡訊已成功傳送,報告仍然會顯示'電信業者處理中'
SMS_STATUS_DELIVERY_DELAYED 傳送延遲 - 訊息傳送延後
SMS_STATUS_DELIVERED 已傳送 - 訊息發送成功至指定號碼
SMS_STATUS_BOUNCED 電信業者無法傳送 - 簡訊彈回.可能的原因為輸入錯誤的電話號碼或發訊者ID,指定電話長時間處於收訊外或是電信業者網路擁塞
SMS_STATUS_EXPIRED 過時中止傳送 - 此則簡訊已超過期限,無法發送.
此問題通常發生在對方手機關機或是長時間內處於無法收訊的狀態
SMS_STATUS_ERROR 傳送失敗 - 傳送失敗(此則簡訊不計費).
可能原因為My-Cool-SMS無法辨識電話號碼的電信網路(請聯絡客服如果您確定電話號碼是正確的)或是暫時性的網路錯誤

功能: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

POST/GET 範例

username=xxx&password=yyy&function=getOutboundSms

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"getOutboundSms"
}

指令參數

參數 說明 種類

自選參數

參數 說明 種類
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

成功回報範例

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
total The total number of SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

功能特定的API錯誤

錯誤代碼 錯誤說明
234 The provided thresholdid is invalid
235 無效的限制參數
236 Invalid order parameter
注意事項: 另外也查看一般性錯誤章節

郵件名單API

功能: sendMailing

發送一則簡訊至整個郵件名單. 小秘訣: 您可以在My-Cool-SMS網站介面建立和管理郵件名單 .
Returns a JSON object confirming the request (or stating an error).

POST/GET 範例

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

指令參數

參數 說明 種類
uniqueid 郵件名單的唯一識別碼. 您可以在郵件名單管理介面中找到唯一識別碼 string
message 簡訊內文. My-Cool-SMS 自動偵測所輸入的編碼,並照著此編碼處理簡訊為 GSM 或 Unicode.
您可使用自選Unicode參數強制建立一個特定的編碼, 如果 Unicode 的設定是 true, 簡訊將會以 Unicode 發送並且必須以 Unicode UCS2 標記法來提供訊息參數. 如果 Unicode 的設定是 false, 簡訊將會以 GSM 發送並且訊息參數必須包含只有 GSM7 字母的字元.
長簡訊會自動串連成一封來寄送. GSM 簡訊可容納長達765個字元或是 Unicode 長達335個字元.
請記住當您送出 GET 請求時, 務必要使用 unicode 參數
string
注意事項: 尋找更多關於 GSM, UnicodeUCS2.

自選參數

參數 說明 種類
unicode 在簡訊上強制建立特定的 Unicode 或 GSM 編碼. 如果設定為 true, 訊息參數必須以 UCS2 標記法發送. 如果設定為 false, 則訊息參數必須包含只有 GSM7 字母的字元.
如果沒有設定或是設定為 NULL, My-Cool-SMS 將會自動偵測輸入的編碼
boolean
senderid 國際形式的手機號碼, 例如: +44123456789或是一個11字元內字母與數字組合的發訊者ID, 例如: Company string
scheduletime 在特定的時間發送簡訊. 使用ATOM格式和時區, 例如: "2011-04-17T17:59:36.67+08" 或 "2011-04-17 17:59:36-02" timestamp with time zone
注意事項: 尋找更多關於 傳送報告回調.

成功回報範例

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
groupkey 此郵件的關係鍵, 建議將其妥善保存並做為傳送報告的參考 string(32)
body Unicode 的簡訊內文 string
bodyucs2 UCS2 位元組碼標記法的簡訊內文 string
bodygsm7 GSM7 位元組碼標記法的簡訊內文 (或是NULL, 如果簡訊以 Unicode 發送) string || NULL
uniqueid string(7)
senderid 顯示目的地號碼是否支援動態發訊者ID boolean
unicode 顯示簡訊是否以 Unicode 或 GSM 發送 boolean
numchars 顯示簡訊中包含幾個字元 integer
escapenumchars 顯示幾個字元必須被移除 integer
smscount 顯示簡訊是否已串連成一封長簡訊並提供已使用的則數 integer
subscribers 接收此則簡訊的用戶人數 integer
charge 顯示此則簡訊從帳戶中扣除多少金額 float
balance 帳戶餘額 float

功能特定的API錯誤

錯誤代碼 錯誤說明
220 唯一識別碼和任何的郵件名單沒有關聯
注意事項: 另外也查看一般性錯誤章節

功能: addSubscriber

加入一個新的用戶至郵件名單中. 自動更新訂閱者若是訂閱的號碼已存在於現有的郵件名單中.
Returns a JSON object confirming the request (or stating an error).

POST/GET 範例

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

指令參數

參數 說明 種類
number 用戶電話號碼的國際形式. 例如: 49123456789 或是 +49123456789 或是 0049123456789 string
uniqueid 郵件名單的唯一識別碼. 您可以在郵件名單管理介面中找到唯一識別碼 string

自選參數

參數 說明 種類
title 用戶稱號 varchar(16)
firstname 用戶名字 varchar(32)
lastname 用戶姓氏 varchar(32)
company 用戶公司 varchar(64)

成功回報範例

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
number 新用戶的標準化電話號碼 string
title 新用戶的稱號 string
firstname 新用戶的名字 string
lastname 新用戶的姓氏 string
company 新用戶的公司 string
subscribercost 此用戶每則簡訊花費 float
senderidenabled 顯示用戶是否支援發訊者ID boolean
maxcharsgsm 顯示GSM訊息中用戶支援多少字元 integer
maxcharsunicode 顯示Unicode訊息中用戶支援多少字元 integer
countrycode 用戶國碼 (2個字母的ISO標準格式) string(2)
mailinglistcost 發送至此郵件名單的新增花費總額 float
mailinglistsubscribers 此郵件名單用戶的新電話號碼 integer

功能特定的API錯誤

錯誤代碼 錯誤說明
221 輸入的 {field} 過長
注意事項: 另外也查看一般性錯誤章節

功能: updateSubscriber

請參閱 功能: 新增用戶

功能: deleteSubscriber

從郵件名單中刪除用戶(利用電話號碼當參考).
回傳一個確認請求的JSON物件(或是錯誤說明)

POST/GET 範例

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

指令參數

參數 說明 種類
uniqueid 郵件名單的唯一識別碼. 您可以在郵件名單管理介面中找到唯一識別碼 string
number 要從此郵件名單中刪除的用戶人數 string

成功回報範例

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
number 已被刪除用戶的標準化電話號碼 string
mailinglistcost 發送至此郵件名單的新增花費總額 float
mailinglistsubscribers 此郵件名單用戶的新電話號碼 integer

功能特定的API錯誤

錯誤代碼 錯誤說明
220 唯一識別碼和任何的郵件名單沒有關聯
222 此郵件名單中沒有這個電話號碼的用戶
注意事項: 另外也查看一般性錯誤章節

Utils API

功能: doHlrLookup

執行一個本地位置記錄器(HLR)查詢和還傳該號碼的MSC, MCC, MNC, INSI 及網路名稱上的資訊包括該號碼目前是否為漫遊狀態還有它是否以連接至另一個網路
注意事項: 查詢更多關於 HLR, IMSI, MCC, MNCMSC.

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

指令參數

參數 說明 種類
number 欲執行HLR查詢的號碼的國際標準形式. 例如49123456789 或 +49123456789 或 0049123456789 string

成功回報範例

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
status 顯示查詢的統計資料. 詳細內容請參閱HLR統計資料參考表 string
number 執行HLR查詢的號碼 string
imsi 國際行動用戶辨識碼(IMSI). 與該目標號碼有關的唯一識別 string
mcc 行動電話國碼(MCC) string
mnc 行動電話網路碼(MNC), 是一組二位數代碼(北美標準式)或一組三位數代碼(歐洲標準式) string
msin 網路客戶群中的行動訂閱辨識碼(MSIN) string
servingmsc 負責按路線發送簡訊的行動交換中心(MSC) string
servinghlr 與該目標號碼有關的本地位置記錄器(HLR) string
originalnetworkname 屬於此號碼的行動電話網路(或是原本屬於的, 如果這是一個可攜式號碼) string
originalnetworkprefix 屬於此號碼的行動電話網路字首(或是原本屬於的, 如果這是一個可攜式號碼) string
originalcountryname 屬於此號碼的國家 string
originalcountrycode 屬於此號碼的二字元ISO國碼 string
originalcountryprefix 屬於此號碼的國家字首 string
roamingcountryname 此號碼目前正處於漫遊狀態的國家 string
roamingcountrycode 此號碼目前正處於漫遊狀態的國家其二字元的ISO國碼 string
roamingcountryprefix 此號碼目前正處於漫遊狀態的國家字首 string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported 顯示此號碼是否為一個可攜式號碼 boolean
iscorrect 顯示此號碼是否有效 boolean
isroaming 顯示此號碼目前是否為漫遊狀態(在另一個國家) boolean
charge HLR 查詢的費用(0.01 歐元) numeric
注意事項: 查詢更多關於 HLR, IMSI, MCC, MNCMSC.

功能特定的API錯誤

錯誤代碼 錯誤說明
210 電話號碼不正確
226 HLR查詢失敗. 不收取費用
注意事項: 另外也查看一般性錯誤章節

HLR 狀態參考

Status 說明
HLR_STATUS_UNKNOWN_NUMBER 此號碼不存在或是無法安置在任何HLR中. 簡訊將無法抵達
HLR_STATUS_OK 此號碼存在並且HLR查詢成功. 簡訊將會抵達
HLR_STATUS_NOT_OK 此號碼有一段很長的時間處於網路之外或是被網路提供業者停用. 簡訊將無法抵達
HLR_STATUS_FAILED HLR 查詢失敗. 不收取費用
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

功能: toUCS2

UCS2可以編碼一個特定的Unicode字串
重要: 至UCS2 需要一個JSON請求

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

指令參數

參數 說明 種類
number 欲執行HLR查詢的號碼的國際標準形式. 例如49123456789 或 +49123456789 或 0049123456789 string

自選參數

參數 說明 種類

成功回報範例

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
ucs2 所發送字串的UCS2標記法 string

功能特定的API錯誤

注意事項: 另外也查看一般性錯誤章節

功能: fromUCS2

解碼一個特定的UCS2字串

POST/GET 範例

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

指令參數

參數 說明 種類
str 要解碼的UCS2字串 string

成功回報範例

{
    "success":true,
    "decoded":"繁体中文"
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
decoded 解碼UCS2的Unicode string

功能特定的API錯誤

錯誤代碼 錯誤說明
201 UCS2 輸入無效
注意事項: 另外也查看一般性錯誤章節

功能: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

POST/GET 範例

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

JSON 範例

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

指令參數

參數 說明 種類
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

成功回報範例

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

成功回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

功能特定的API錯誤

錯誤代碼 錯誤說明
237 The number could not be normalized.

錯誤回報

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

錯誤回報範例

{
    "success":false,
    "errorcode":103,
    "errordescription":"未輸入參數指令: senderid"
}

錯誤回報值

關鍵 說明 種類
success 顯示是否能夠成功地處理請求 boolean
errorcode 一組三位數錯誤代碼 string(3)
errordescription 錯誤說明 string

功能特定的API錯誤

一些功能有特定的API錯誤代碼,是針對某些功能而特有的,其錯誤代碼形式為 2xx. 請參考功能說明查看個別的錯誤代碼

一般性API錯誤

除了功能特定的錯誤之外, 任何對於API的請求都可能導致一般性API錯誤並顯示 1xx 形式的錯誤代碼

一般性錯誤代碼

錯誤代碼 錯誤說明
101 登入失敗. 錯誤的帳號或密碼
102 此帳號尚未啟動
103 未輸入參數指令
104 請求錯誤. 查無GET, POST以及JSON. 如您正嘗試發送JSON, 請檢查是否為適當的編碼
105 未知的功能
106 許可拒絕
107 一般性API錯誤
108 無效的請求架構
109 餘額不足
我們有漏掉些什麼嗎? 您有任何問題嗎? 您有任何建議或是還有其他我們該增加的? 如果有, 請與我們聯繫!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Português
Руccкий