服務圈機器人API

ChatBot機制

M+呼叫企業提供的 URL將用戶於服務圈聊天室發送的訊息帶入。企業於 Http response 中回覆欲傳送給用戶的訊息。

▲M+ ChatBot機制圖

企業提供的URL

企業提供的URL範例：https://hostname/example/messagerobot

其中https為 通訊協定，hostname為主機名稱（網域名稱），/example/messagerobot為要呼叫的API路徑（網頁路徑）。

當用戶於服務圈輸入訊息時，M+會呼叫企業提供的URL並將用戶輸入的訊息及相關資訊帶入；企業可在API中進一步判斷用戶輸入的內容回傳適當的回應內容給M+，M+再將其內容顯示於服務圈回應用戶。

M+呼叫企業提供的API時會傳入用戶輸入的訊息類型及內容，範例：
https://hostname/example/messagerobot?type=”0”&content=”input_content”&cuserid=”cccccccc”&auserid=”aaaaaaaa”&anickname=”nnnnn”&msgid=”12345”

範例中 ? 前面為企業提供的URL；後面為可傳入的參數種類，可以參考Input Parameter列表。

Input Parameter

Name Type Max Length Mandatory Description
type String 2 Yes 0 : 純文字
1 : sticker
2 : 座標
3 : 圖片
4：檔案
content String 300 Yes 粉絲傳送的訊息內容
須urlencode
type=0, content=文字內容
type=1, content=sticker 代表文字
type=2, content=緯度,經度. 例如:25.0392, 121.525
type=3, content=圖片URL
cuserid String 10   服務圈帳號userid
auserid String 10   經過AES加密的用戶userid, 須urlencodeKey=1N3A5T7U9R1A3L56
anickname String     用戶的nickname，需urlencode
msgid String   Yes 訊息ID

Output Parameter

Name Type Max Length Mandatory Description
cause String 4 Yes Return code of the API
00: success
20:參數錯誤
90:系統錯誤
type String 2 No 0:純文字
1:info-push
2:圖貼
3:圖片
5:多筆回傳
6:問卷訊息
無此tag 或無值, 則不會回傳DS message 給粉絲
content String   No 當type=0, content:要傳給粉絲的訊息內容
當type=1, content:要傳給粉絲的Info-Push標題內容
當type=2,content: sticker 代表文字
當type=3,content:圖片URL
當type=5,多筆回傳
當type=6,content表示問卷訊息的標題
headlinex       第2則以上(含)的Info-Push標題內容, x 表示第幾則 x>=2
iconUrl String   N 第一則Info-push 圖片URL
Mandatory when type=1
iconUrlx String   N 第2則以上(含)的圖片URL, x 表示第幾則 x>=2
infoUrl String   N 第一則Info-push內文連結URL
Mandatory when type=1
infoUrlx String   N 第2則以上(含)的內文連結URL, x 表示第幾則 x>=2
infonum String   N Infopush總則數(超過1則infopush時, 須指定infonum)
layout String   N Info-push 版型
1: 版型1:內嵌中繼頁(webview), 點選中繼頁內的網址再另開網頁
2: 版型2:另開網頁
3: 版型3:內嵌中繼頁(webview),點選中繼頁內的網址在webview開啟
Mandatorywhen type=1
replyOpt String     毎個選項需URLEncode, 並以+號隔開

Example

Input http://hostname/example messagerobot?type=0&content= 粉絲傳送的訊息內容
&cuserid=cccccccc&auserid= anickname=nnnnn msgid=
Output //type= 0 (純文字)
<robotmessage>
<cause>00</cause>
<type>0</type>
<content>
hello
hello
hello
</content>
</robotmessage>

//type=1(InfoPush)
<robotmessage>
<cause>00</cause>
<type>1</type>
<content>headline1</content>
<layout>1</layout>
<iconUrl http://iconserver.com.tw/1.jpg iconUrl>
<infoUrl http://infoserver.com.tw/1.html infoUrl>
<headline2>headline2</headline2>
<iconUrl 2> http://iconserver.com.tw/1.jpg <iconUrl 2>
<infoUrl 2> http://infoserver.com.tw/1.html infoUrl 2>
<headline 3 >headline2</headline 3>
<iconUrl 3> http://iconserver.com.tw/1.jpg iconUrl 3>
<infoUrl3> http://infoserver.com.tw/1.html infoUrl 3>
<infonum >3</infonum>
</robotmessage>

//type=2 (Sticker)
<robotmessage>
<cause>00</cause>
<type>2</type>
<content>(1111B1)</content>
</robotmessage>

//type=3 圖片
<robotmessage>
<cause>00</cause>
<type>3</type>
<content> xxx/photo.jpg </content>
</robotmessage>

//type= 6(問卷)
<robotmessage>
<cause>00</cause>
<type>6</type>
<content> 請選擇以下選項 </content>
<replyOpt>Opt>%E7%AD%94%E6%A1%881+%E7%AD%94%E6%A1%882+%E7%AD%94%E6%A1%883</replyOpt>
</robotmessage>

//type=5 (Multi)
<robotmessage>
<cause>00</cause>
<type>5</type>
<list>
<item>
<type>0</type>
<content>純文字</content>
</item>
<item>
<type>1</type>
<content>headline1</content>
<layout>1</layout>
<iconUrl>http://iconserver.com.tw/1.jpg</iconUrl>
<infoUrl>http://infoserver.com.tw/1.html</infoUrl>
<headline2>headline2</headline2>
<iconUrl2>http://iconserver.com.tw/1.jpg</iconUrl2>
<infoUrl2>http://infoserver.com.tw/1.html</infoUrl2>
<headline3>headline3</headline3>
<iconUrl3>http://iconserver.com.tw/1.jpg</iconUrl3>
<infoUrl3>http://infoserver.com.tw/1.html</infoUrl3>
<infonum>3</infonum>
</item>
<item>
<type>2</type>
<content>(1111B1)</content>
</item>
<item>
<type>3</type>
<content>http://iconserver.com.tw/1.jpg</content>
</item>
</list>
</robotmessage>

判斷用戶輸入訊息類型

當用戶輸入訊息時，上面的機制圖中M+ ChatBot平台會判斷用戶輸入的類型（可參考type參數），將用戶此次輸入的訊息資訊帶入企業提供的URL呼叫API；故機制圖中企業提供的API只要解析URL中的參數就可取得用戶輸入的訊息類型以及其他帶入的資訊，企業提供的API取得訊息類型後可以進一步判斷要回應哪種訊息給用戶。

簡易範例程式method如下：

※ 範例程式中的result字串內容並非真正要回傳給M+ ChatBot的格式；result字串詳細內容會在回應用戶訊息中說明；在每種類型的最後皆有「回應字串內容」，此內容即為result字串的格式。

  • 範例程式碼： 
    
            public final static String TYPE_0 = “0”;  //0.純文字
            public final static String TYPE_1 = “1”;  //1.貼圖(sticker)
            public final static String TYPE_2 = “2”;  //2.座標
            public final static String TYPE_3 = “3”;  //3.圖片
            public final static String TYPE_4 = “4”;  //4.檔案

            /**
             *判斷M+ Chatbot傳入的訊息類型後決定要回應給用戶的內容
             *
             *@param type 用戶輸入的訊息類型
             *@return result 欲回應給用戶的內容；類似xml檔內容的字串
             */
            public String returnContent(String type) {
                String result = “”;
                if (StringUtils.isNotBlank(type)) {
                  if (type.equals(TYPE_0)) {
                    result = “若用戶輸入純文字時，欲回應的內容”;
                } else if (type.equals(TYPE_1)) {
                    result = “若用戶輸入貼圖時，欲回應的內容”;
                } else if (type.equals(TYPE_2)) {
                    result = “若用戶輸入座標時，欲回應的內容”;
                } else if (type.equals(TYPE_3)) {
                    result = “若用戶輸入圖片時，欲回應的內容”;
                } else if (type.equals(TYPE_4)) {
                    result = “若用戶輸入檔案時，欲回應的內容”;
                }
            } else {
                //若為空字串或null可另做處理，或throw自定Exception
            }
            return result;
            }

回應用戶訊息

企業提供的API經過判斷後，回應用戶的訊息與xml檔案的格式相似，由不同的tag組合而成（tag name可參考Output Parameter），在tag後方的說明文字在程式中不需寫入，依照回應訊息的類型可分為以下幾種（反黃的部分可以自行替換要回應的內容）：

回應用戶「純文字」

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>0</type>（要回應的訊息類型，0 純文字）
<content>（type=0，則為文字訊息內容）
hello
hello （訊息本文）
hello
</content>
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>0</type><content>hello\nhello\nhello</content></robotmessage>

回應用戶「InfoPush」

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>1</type>（要回應的訊息類型，1 InfoPush）
<content>headline1</content>（type=1，則為第一則InfoPush標題）
<layout>1</layout>（InfoPush的版型，type=1時必填）
<iconUrl>http://iconserver.com.tw/1.jpg</iconUrl>（第一則InfoPush圖片URL）
<infoUrl>http://infoserver.com.tw/1.html</infoUrl>（第一則InfoPush內文連結URL）
<headline2>headline2</headline2>（第二則InfoPush標題）
<iconUrl2>http://iconserver.com.tw/2.jpg</iconUrl2>（第二則InfoPush圖片URL）
<infoUrl2>http://infoserver.com.tw/2.html</infoUrl2>（第二則InfoPush內文連結URL）
<headline3>headline3</headline3>（第三則InfoPush標題）
<iconUrl3>http://iconserver.com.tw/3.jpg</iconUrl3>（第三則InfoPush圖片URL）
<infoUrl3>http://infoserver.com.tw/3.html</infoUrl3>（第三則InfoPush內文連結URL）
<infonum>3</infonum>（InfoPush總則數）
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>1</type><content>headline1</content><layout>1</layout><iconUrl>http://iconserver.com.tw/1.jpg</iconUrl><infoUrl>http://infoserver.com.tw/1.html</infoUrl><headline2>headline2</headline2><iconUrl2>http://iconserver.com.tw/2.jpg</iconUrl2><infoUrl2>http://infoserver.com.tw/2.html</infoUrl2><headline3>headline3</headline3><iconUrl3>http://iconserver.com.tw/3.jpg</iconUrl3><infoUrl3>http://infoserver.com.tw/3.html</infoUrl3><infonum>3</infonum></robotmessage>

回應用戶「貼圖（sticker）」

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>2</type>（要回應的訊息類型，2 貼圖(sticker)）
<content>(1111B1)</content>（type=2，則為sticker 代表文字）
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>2</type><content>(1111B1)</content></robotmessage>

回應用戶「圖片」

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>3</type>（要回應的訊息類型，3 圖片）
<content>http://xxx/photo.jpg</content>（type=3，則為圖片URL）
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>3</type><content>http://xxx/photo.jpg</content></robotmessage>

回應用戶多筆不同訊息類型

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>5</type>（要回應的訊息類型，5 多筆類型）
<list>（訊息列，可有多個<item>）
<item>（訊息元素，其中內容可為上述不同種類型）
<type>0</type>（要回應的訊息類型，0 純文字；參考回應用戶「純文字」）
<content>純文字</content>
</item>
<item>
<type>1</type>（要回應的訊息類型，1 InfoPush；參考回應用戶「InfoPush」）
<content>headline1</content>
<layout>1</layout>
<iconUrl>http://iconserver.com.tw/1.jpg</iconUrl>
<infoUrl>http://infoserver.com.tw/1.html</infoUrl>
<headline2>headline2</headline2>
<iconUrl2>http://iconserver.com.tw/2.jpg</iconUrl2>
<infoUrl2>http://infoserver.com.tw/2.html</infoUrl2>
<headline3>headline3</headline3>
<iconUrl3>http://iconserver.com.tw/3.jpg</iconUrl3>
<infoUrl3>http://infoserver.com.tw/3.html</infoUrl3>
<infonum>3</infonum>
</item>
<item>
<type>2</type>（要回應的訊息類型，2 貼圖；參考回應用戶「貼圖」）
<content>(1111B1)</content>
</item>
<item>
<type>3</type>（要回應的訊息類型，3 圖片；參考回應用戶「圖片」）
<content>http://iconserver.com.tw/1.jpg</content>
</item>
</list>
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>5</type><list><item><type>0</type><content>純文字</content></item><item><type>1</type><content>headline1</content><layout>1</layout><iconUrl>http://iconserver.com.tw/1.jpg</iconUrl><infoUrl>http://infoserver.com.tw/1.html</infoUrl><headline2>headline2</headline2><iconUrl2>http://iconserver.com.tw/2.jpg</iconUrl2><infoUrl2>http://infoserver.com.tw/2.html</infoUrl2><headline3>headline3</headline3><iconUrl3>http://iconserver.com.tw/3.jpg</iconUrl3><infoUrl3>http://infoserver.com.tw/3.html</infoUrl3><infonum>3</infonum></item><item><type>2</type><content>(1111B1)</content></item><item><type>3</type><content>http://iconserver.com.tw/1.jpg</content></item></list></robotmessage>

回應用戶「問卷」

<robotmessage>
<cause>00</cause>（請求結果，return API code）
<type>6</type>（要回應的訊息類型，6 問卷）
<content>請選擇以下選項</content>（type=6，則為問卷標題）
<replyOpt>%E7%AD%94%E6%A1%881+%E7%AD%94%E6%A1%882+%E7%AD%94%E6%A1%883</replyOpt>（問卷選項；需URLEncode，每個選項以 + 隔開）
</robotmessage>

  • 回應字串內容： 
    
            <robotmessage><cause>00</cause><type>6</type><content>請選擇以下選項</content><replyOpt>%E7%AD%94%E6%A1%881+%E7%AD%94%E6%A1%882+%E7%AD%94%E6%A1%883</replyOpt></robotmessage>