服務場景

IMSDK主要服務于渠道部署后的頁面不能滿足業(yè)務需求，需要定制聊天對話界面的場景。當渠道部署頁面能滿足需求時，建議直接使用渠道部署頁面，減少開發(fā)工作。當機器人沒有接入通義模型且不存在人工服務的情況下，也可以直接使用Chat - 會話會話接口進行對接。

集成流程

部署頁面支持人工服務、機器人的回復等非一問一答的業(yè)務場景，會出現(xiàn)一問多答或者多問多答的情況，服務端需要可以直接發(fā)送消息給聊天窗頁面，所以需要使用websocket進行連接。渠道建立websocket連接時，需要后端提供的token以保障服務安全性，整體對接流程如下。

1. im-sdk依賴渠道部署，需要先在智能對話機器人平臺新建機器人、關聯(lián)知識，配置渠道部署并將機器人及關聯(lián)知識發(fā)布到正式環(huán)境，使用渠道部署后的鏈接驗證正式環(huán)境的問答功能是否正常。

2. 后端通過InitIMConnect接口，提供獲取token的API給前端。

3. 前端

   1. 對話界面中引入im-sdk-v2.js等依賴的前端資源；

   2. 調(diào)用后端提供的獲取token的api，拿到AppKey、Token和ImDomain等參數(shù)信息；

   3. 初始化im實例：使用new window.IMSDK方法初始化實例，傳入token等參數(shù)；

   4. 調(diào)用im實例的start方法建立連接；

   5. 當用戶輸入文字后，調(diào)用im實例的sendMessage方法將消息內(nèi)容發(fā)送給后端；

   6. 當服務端發(fā)送消息時，會調(diào)用初始化im實例的參數(shù)中的onMessage方法，通過onMessage拿到消息后將消息展示到頁面上；

   7. 使用ChatUI或者ChatUI-pro展示服務端發(fā)送的消息和控制用戶輸入后發(fā)送消息給服務器。

后端

• im建聯(lián)數(shù)據(jù)獲取

后端通過pop接口調(diào)用，獲取im建聯(lián)需要參數(shù)數(shù)據(jù)：

• 接口詳情

  • 方法名：InitIMConnect

  • 請求方式：GET/POST

  • 請求參數(shù)：

• maven版本

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>chatbot20220408</artifactId>
  <version>1.0.5</version>
</dependency>

示例代碼

import com.aliyun.chatbot20220408.models.InitIMConnectResponse;

public class Sample {

    public static void main(String[] args) throws Exception {

        /*
         *  阿里云賬號AccessKey擁有所有API的訪問權限，建議您使用RAM用戶進行API訪問或日常運維。
         *  強烈建議不要把AccessKey ID和AccessKey Secret保存到工程代碼里，否則可能導致AccessKey泄露，威脅您賬號下所有資源的安全。
         *  調(diào)用接口前請先配置身份認證，具體操作請參見http://bestwisewords.com/document_detail/378659.html。
         *  本示例使用了阿里云Credentials工具托管AccessKey，來實現(xiàn)API訪問的身份驗證。
         */
        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
        /*
         * 初始化client
         */
        com.aliyun.chatbot20220408.Client client = new com.aliyun.chatbot20220408.Client(
                new com.aliyun.teaopenapi.models.Config()
                        // 配置云產(chǎn)品服務接入地址（endpoint）。
                        .setEndpoint("chatbot.cn-shanghai.aliyuncs.com")
                        // 使用Credential配置憑證。
                        .setCredential(credentialClient)
        );
        /*
         * 構建請求
         */
        com.aliyun.chatbot20220408.models.InitIMConnectRequest initIMConnectRequest = new com.aliyun.chatbot20220408.models.InitIMConnectRequest()
                .setFrom("xxxxx");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // 復制代碼運行請自行打印 API 的返回值
            InitIMConnectResponse response = client.initIMConnectWithOptions(initIMConnectRequest, runtime);
            System.out.println(response.getBody().getData());
        } catch (Exception error) {
            // 如有需要，請打印 error
            error.printStackTrace();

        }//TeaException error = new TeaException(_error.getMessage(), _error);

    }
}

接口返回數(shù)據(jù)：

{
  "RequestId": "48365A93-F0D1-1279-B9C4-5B1AA6B2ED5C",
  "Data": {
    "AppKey": "WDg2VfNv",
    "Token": "amJIWEtUR2xGTW16R01UZWF4TTVGc1hxbDRtaEdTNWVmMklFeVYzT2dOSjFWUUtuN0xDSjcxM3B5aWtFQjJoUUNvV3pZeXlDc28yZE9Yb3lhenJjN2pIeEtmbVh0anlYd242UUw0d2tSN05qVUQwTTJnV2tFN3VwdDZ1YzJzaTFTeWpoSksrb3FTYlptWGtuUkw4dzJYK0txV0c4djR4eUtmK0piSWdVNFFPdnJOc3c4RWhQeUdaTTRtN3E3L1Q5",
    "ImDomain": "alimeim.aliyuncs.com"
  },
  "Success": true
}

前端

• 如何引入

<script src="https://g.alicdn.com/ume/chatbot/6.0.13/im-sdk-v2.js"></script>

• 初始化

初始化時需要傳入一個config對象

例如：

const im = new window.IMSDK({
  url: 'wss://alimeim.aliyuncs.com/alime/im',
  token: 'amJIWEtUR2xGTW16R01UZWF4TTVGc1hxbDRtaEdTNWVmMklFeVYzT2dOSjFWUUtuN0xDSjcxM3B5aWtFQjJoUUNvV3pZeXlDc28yZE9Yb3lhenJjN2pIeEtmbVh0anlYd242UUw0d2tSN05qVUQwTTJnV2tFN3VwdDZ1YzJzaTFTeWpoSksrb3FTYlptWGtuUkw4dzJYK0txV0c4djR4eUtmK0piSWdVNFFPdnJOc3c4RWhQeUdaTTRtN3E3L1Q5',
  appKey: 'WDg2VfNv',
  getToken: () => {
    return new Promise((resolve) => {
      resolve('token');
    });
  }
});

• 建立連接

im.start();

• 設置IM消息通用參數(shù)

im.setCommonParams({
  senderId: 666666,
  senderNick: 'xxx',
});

通用參數(shù)列表可參考本文檔API>setCommonParams(params)部分。

• 示例

<script src="https://g.alicdn.com/ume/chatbot/6.0.13/im-sdk-v2.js"></script>
<script>
  const im = new window.IMSDK({
    config: {
      /**
       * ws地址
       */
      url: "wss://xxxxxx/alime/im",
      /**
       * IM鑒權參數(shù)，接入方自行實現(xiàn)token生成和校驗邏輯接入方后端提供token生成接口給前端
       */
      token: "T3ZEcEdWK3hOTXNRNklUejhTaWN6bllsTzVRTEIzSWRSbWJjSGxWTW5VMS9zZ1BKWDEzMEZFbUlMWEY4czhRRE5IcFZGVC9sUURLczlwa2c1ZC9vQ0pBWW9uNzRQRDJoVFFjMjcwTlZwWllsMTJYb0JiWk0wRlhpTzBmdWtyMFJmVEs4MGFJQjVWeWtHY2NCalFqTkthSVVzVlpGalRsQm53VWtiNmxRanBjPQ==",
      /**
       * 應用key
       */
      appKey: "8xx4xxxx",
      /**
       * 獲取token的函數(shù)，返回Promise對象，注意需要通過接口拿到最新的token
       */
    	getToken: () => {
        return new Promise((resolve) => {
          resolve("newToken-xxxx");
        });
      },
    },
    handlers: {
      /**
       * 接收到業(yè)務消息
       */
      onMessage: (data: ChatItem) => {
        /**
         * data示例： {
              "header": {
                  "localMsgId": "167057154135437653",
                  "msgId": "991965825848146256",
                  "version": "1.3.1"
              },
              "body": {
                  "senderRole": 3,
                  "senderId": "2022033141787377",
                  "ghost": false,
                  "message": [
                      {
                          "content": {
                              "text": "您好，我是xx，很高興為您服務。"
                          },
                          "context": {
                              "msg_non_disturb": "false",
                              "@class": "java.util.HashMap",
                              "sdkType": "SERVER_JAVA_SDK"
                          },
                          "extraInfo": {
                              "traceId": "ac10646b16705715412861986d0082",
                              "@class": "java.util.HashMap",
                              "from": "LMm8SngXnv",
                              "sid": "2022120911WXc_LrRJ000000052345"
                          },
                          "msgType": "text"
                      }
                  ]
              }
          }
         */
        console.log('receive message:', data);
      },
      /**
       * 關閉IM連接
       * code為關閉原因:
       *    CONNECTION_KICK_OUT：重復登錄，此時建議提示用戶有重復登錄
       *    CONNECTION_CLOSED：重連5次依然失敗，此時建議提示用戶系統(tǒng)出錯，手動重試
       *    CHEARTBEAT_TIMEOUT：心跳超時斷開，未收到pong消息，此時SDK會自動重連，接入方無特殊需求則不用處理
       *    CSERVER_CONNECTION_CLOSED：服務器正在重啟引起的連接斷開，此時SDK會自動重連，接入方無特殊需求則不用處理
       *    CCONNECTION_TIMEOUT：會話超時連接斷開，用戶超過一定時長未說話，用戶再次發(fā)消息會自動重連
       */
      onClose: (err: string) => {
        console.error(err);
      }
    }
  });

	// 建立連接
  im.start();

	/**
   * @method 設置消息通用參數(shù) [可選]
   * @parma {CommonParamsProps} params 發(fā)消息者參數(shù)
   * @returns
   */
  im.setCommonParams({
    senderId: userId,
    senderNick: nick,
    senderRole: 1,
  });
</script>

消息協(xié)議

• 消息格式

{
  "header": {
    "localMsgId": "167057154135437653", // 本地消息id
    "msgId": "991965825848146256", // 消息id，如果兩條消息相同，會更新消息
    "version": "1.3.1" // 消息協(xié)議版本
  },
  "body": {
    "senderRole": 3, // //信息來源： 1、用戶 3、客服 4、機器人
    "senderId": "2022033141787377", // 發(fā)送者ID
    "ghost": false, // 是否存儲歷史消息
    "message": [
        {
          "content": { // 內(nèi)容對象
              "text": "您好，我是xx，很高興為您服務。"
          },
          "context": { // 業(yè)務透傳對象，由下行消息傳遞
              "msg_non_disturb": "false",
              "@class": "java.util.HashMap",
              "sdkType": "SERVER_JAVA_SDK"
          },
          "extraInfo": { // 消息擴展字段
              "traceId": "ac10646b16705715412861986d0082",
              "@class": "java.util.HashMap",
              "from": "LMm8SngXnv",
              "sid": "2022120911WXc_LrRJ000000052345"
          },
          "msgType": "text" // 消息類型
        }
    ]
  }
}

• 消息類型枚舉

對于上行消息來說，大部分情況下是文本消息，下行消息里文本消息、卡片消息、富文本消息居多，其他消息相對來說比較少見。文檔為了看起來清晰，content直接以JSON格式列舉，實際收到的為字符串，需要自己解析成json。

//1、文本消息
{
    "msgType":"text",     //文本消息
    "content":{
      "text":"Hello world"   //文本具體內(nèi)容
    }
}
//1.1、特殊無答案的情況
{
  "msgType":"text",
  "context":{
    "text":""
  }
}
//2、卡片消息
{
    "msgType":"card",     //卡片消息
    "content":{
        "code":"${code}",      //卡片模版code
        "cardId":"${cardId}",  //卡片id code/cardId二者選一
        "data":{},             //卡片數(shù)據(jù)
        "params":{} //1.5新增，動態(tài)類卡片使用
    }
}
//3、富文本消息
{
    "msgType":"richtext",      //富文本消息
    "content":{
      "contentType":"Html",    //文本格式類型 <Html|Markdown>
      "text":"${text}"         //富文本內(nèi)容
    }
}
//4、圖片消息
{
    "msgType":"image",     //圖片消息
    "content":{
      "picUrl":"https://www.alimebot.com/1.jpg"    //圖片地址
    }
}
//5、表單信息
{
    "msgType":"form",        //表單信息
    "content":{
      "formData":"${formData}",  //表單內(nèi)容
      "text":"${text}"           //業(yè)務文本
    }
}
//6、訂單消息
{
    "msgType":"order",       //訂單消息
    "content":{
      "source":"${source}",
      "parentId":"${parentId}",
      "id":"${id}"
    }
}
//7、商品消息
{
    "msgType":"item",      //商品消息
    "content":{
      "source":"${source}",   //商品來源
      "id":"${id}"            //商品id
    }
}
//8、文件消息
{
    "msgType":"file",        //文件消息
    "content":{
      "fileName":"可對客-e收匯系統(tǒng)指引20200220",     //文件名稱
      //文件地址
      "fileUrl":"http://xspace-img-cn.alicdn.com/consult/1587094983552_H48RpMMec4DBZo9TVo1vkJUv.pdf",
      "fileByteSize":2171616,   //文件大小
      "fileType":"pdf"          //文件類型
   }
}
//9、音頻消息
{
    "msgType":"audio",   //音頻消息
    "content":{
      "url":"${url}",    //音頻地址
      "duration":"${duration}"    //音頻時長
    }
}
//10、視頻消息
{
    "msgType":"video",        //視頻消息
    "content":{
      "url":"${url}",         //視頻地址
      "duration":"${duration}",      //視頻時長
      "cover":"${cover}"         //封面
    }
}
//11、指令消息
{
    "msgType":"cmd",
    "content":{
  	  "code":"AGENT_SESSION_START",//code列表見"指令消息code列表"
  	  "params":{},
      "text":""http://展示文案
    }
}

• 指令消息（cmd消息）code列表

CMD消息，可根據(jù)自己需要過濾有效信息。

AGENT_SESSION_START("進入人工"),
AGENT_SESSION_FAIL("進入人工失敗"),
AGENT_JOIN("人工小二進線"),
AGENT_SERVICE_LEAVE("工作臺主動斷開服務"),
AGENT_LEAVE_NOTICE("人工會話關閉倒計時提醒"),
AGENT_CLIENT_LEAVE("會員主動關閉"),
AGENT_SWITCH("小二轉(zhuǎn)交"),
AGENT_QUEUE("人工進線排隊"),
AGENT_NO_SERVICE("小二未上班"),
AGENT_NOT_WORKTIME("小二未在工作時間"),
CLIENT_QUIT_QUEUE("退出人工進線排隊"),
CLIENT_CANCEL_RESUME("取消重連"),
CLIENT_RESUME("斷線重連"),
CLIENT_LEAVE_SESSION("退出人工"),
CLIENT_JOIN_SESSION("點擊轉(zhuǎn)人工"),
AGENT_ENTRANCE_DISPLAY("轉(zhuǎn)人工入口"),
AGENT_DISCONNECT("客服已經(jīng)斷開"),
SWITCH_ORDER_TIP("切換訂單提示");

API

getIM()

• 用途：獲取IM實例

• 參數(shù)：無

• 返回：IM實例

setCommonParams(params)

• 用途：設置消息通用參數(shù)。

• 使用場景：比如獲取地理位置信息是異步的，那么可以在拿到lbs信息之后再設置這個通用參數(shù)，這樣后續(xù)消息發(fā)送都會帶上。

• 參數(shù)：params里的參數(shù)列表如下

• 返回：無

• 示例：

im.setCommonParams({
  senderId: 'senderId',
  senderNick: "senderNick",
  senderRole: 1,
});

connect(sync)

• 用途：建立IM連接。

• 參數(shù)：

• 返回：無。

readyState()

• 用途：獲取IM的狀態(tài)，狀態(tài)。

• 參數(shù)：無。

• 返回

  • 類型：number

    • 枚舉值：

      • 0：CONNECTING，表示正在連接

      • 1：OPEN，表示連接成功，可以通信了

      • 2：CLOSING，表示連接正在關閉

      • 3：CLOSED，表示連接已經(jīng)關閉，或者打開連接失敗

sendMessage(msg, ghost)

• 用途：發(fā)送消息

• 參數(shù)：msg為對象，具體字段如下

• 返回：無

im.sendMessage({
  msgType: 'text',
  content: {
    text: '我是發(fā)送的消息',
  },
});

close()

• 用途：關閉IM連接

• 參數(shù)：無

• 返回：無

reconnect(code)

• 用途：重新建立連接

• 參數(shù)：

• 返回：無

handlers

onAck

接收到心跳

const im = new window.IMSDK({
  handlers: {
    onAck: data => {
      /**
        data示例：{"localMsgId":"167057253604245697","msgId":"991974171800073352"}
      */
      console.log('ack', data);
    },
  }
});

onMessage

接收到業(yè)務消息

const im = new window.IMSDK({
  handlers: {
    onMessage: data => {
      console.log('message', data);
    },
  }
});

onOpen

websocket連接建立成功

const im = new window.IMSDK({
  handlers: {
    onOpen: () => {
      console.log('open');
    },
  }
});

onConnect

IM建立連接成功，和open有區(qū)別，connect是和IM系統(tǒng)建立連接成功的事件

const im = new window.IMSDK({
  handlers: {
    onConnect: () => {
      console.log('connect');
    },
  }
});

onClose

IM連接關閉

const im = new window.IMSDK({
  handlers: {
    onClose: code => {
      console.log('close', code);
    },
  }
});

code為關閉原因

• CONNECTION_KICK_OUT：重復登錄，此時建議提示用戶有重復登錄

• CONNECTION_CLOSED：重連5次依然失敗，此時建議提示用戶系統(tǒng)出錯，手動重試

• HEARTBEAT_TIMEOUT：心跳超時斷開，未收到pong消息，此時SDK會自動重連，接入方無特殊需求則不用處理

• SERVER_CONNECTION_CLOSED：服務器正在重啟引起的連接斷開，此時SDK會自動重連，接入方無特殊需求則不用處理

• CONNECTION_TIMEOUT：會話超時連接斷開，用戶超過一定時長未說話，用戶再次發(fā)消息會自動重連

onError

IM連接出錯

const im = new window.IMSDK({
  handlers: {
    onError: err => {
      console.log('error', err);
    },
  }
});

onReconnect

IM正在重連

const im = new window.IMSDK({
  handlers: {
    onReconnect: ({ code, err }) => {
      console.log('reconnect', code, err);
    });
  }
});

ChatUI代碼示例

搭配ChatUI實現(xiàn)的對話界面

import React, { useEffect } from 'react';
import { render } from 'react-dom';
import Chat, { Bubble, useMessages } from 'chat-ui';
// 初始消息列表，可選
const initialMessage = [
  {
    type: 'text',
    content: { text: '親，我是IM測試機器人' },
  },
];
// 默認快捷短語，可選
const defaultQuickReplies = [
  {
    icon: 'message',
    name: '聯(lián)系人工服務',
    isNew: true,
    isHighlight: true,
  },
  {
    name: '短語1',
    isNew: true,
  },
  {
    name: '短語2',
    isHighlight: true,
  },
  {
    name: '短語3',
  },
];

function App() {
  // 消息列表
  const { messages, appendMsg } = useMessages(initialMessage);

  useEffect(() => {
    const im = new window.IMSDK({
      config: {
        url: 'wss://alimeim.aliyuncs.com/alime/im',
        token: '4890',
        appKey: 'QA97fCuA',
        getToken: () => {
          return new Promise(resolve => {
            resolve('4890');
          });
        },
      },
      handlers: {
        onOpen: () => {
          console.log('open');
        },
        onClose: err => {
          console.log('close', err);
        },
        onError: err => {
          console.log('error', err);
        },
        onReconnect: ({ code, err }) => {
          console.log('reconnect', code, err);
        },
        onMessage: data => {
          appendMsg({
            type: 'text',
            content: {
              text: JSON.stringify(data),
            },
          });
          console.log('message', data);
        }
      }
  });
  
  im.start();
  
  im.setCommonParams({
    senderId: 123456654321,
    senderNick: 'xx',
  });
  
  console.log(im);
  }, []);
  // 發(fā)送回調(diào)
  function handleSend(type, val) {
    if (type === 'text' && val.trim()) {
      im.sendMessage({
        msgType: 'text',
        content: {
          text: val,
        },
      });
      appendMsg({
        type: 'text',
        content: { text: val },
        position: 'right',
      });
    }
  }
  // 快捷短語回調(diào)，可根據(jù) item 數(shù)據(jù)做出不同的操作，這里以發(fā)送文本消息為例
  function handleQuickReplyClick(item) {
    handleSend('text', item.name);
  }
  function renderMessageContent(msg) {
    const { type, content } = msg;
    // 根據(jù)消息類型來渲染
    switch (type) {
      case 'text':
        return <Bubble content={content.text} />;
      case 'image':
        return (
          <Bubble type="image">
            <img src={content.picUrl} alt="" />
          </Bubble>
        );
      default:
        return null;
    }
  }
  return (
    <Chat
      messages={messages}
      renderMessageContent={renderMessageContent}
      quickReplies={defaultQuickReplies}
      onQuickReplyClick={handleQuickReplyClick}
      onSend={handleSend}
    />
  );
}
render(<App />, document.getElementById('root'));

ChatSDK代碼示例

ChatSDK的示例可通過鏈接`https://chatbot.console.aliyun.com/ChatSDK#/cards/im-sdk`進行查看體驗，其中html和js的代碼如下

<!DOCTYPE html>
<html lang="zh">
  <head>
    <meta charset="UTF-8" />
    <meta charset="utf-8" />
    <meta name="renderer" content="webkit" />
    <meta name="force-rendering" content="webkit" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0, viewport-fit=cover"
    />
    <link
      rel="stylesheet"
      
    />
  </head>
  <body>
    <div id="root"></div>
    <script src="https://g.alicdn.com/code/npm/@ali/chatui-sdk/6.1.9/ChatSDK.js"></script>
    <script src="https://g.alicdn.com/code/npm/@ali/chatui-sdk/6.1.9/isvParser.js"></script>
    <script src="https://g.alicdn.com/chatui/icons/0.2.7/index.js"></script>
    <script src="https://g.alicdn.com/ume/chatbot/6.0.13/im-sdk-v2.js"></script>
    <script src="./demo_im_sdk.js"></script>
  </body>
</html>

// 對話機器人通訊建立
const url = 'wss://alimeim.aliyuncs.com/alime/im';
const token = location.href.match(/token=(\w+)/) ? location.href.match(/token=(\w+)/)[1] : '';
const appKey = location.href.match(/appKey=(\w+)/) ? location.href.match(/appKey=(\w+)/)[1] : '';
window.im = new window.IMSDK({
  config: {
    url: url,
    // 替換為實際生成的token
    token: token,
    // 替換為自己的appKey
    appKey: appKey,
    getToken: () => {
      // 需要替換為請求后端生成的token
      return Promise.resolve('newToken');
    },
  },
  handlers: {
    onOpen: () => {
      console.log('open');
    },
    onClose: err => {
      console.log('close', err);
    },
    onError: err => {
      console.log('error', err);
    },
    onReconnect: ({ code, err }) => {
      console.log('reconnect', code, err);
    },
    // 接收到消息的處理
    onMessage: data => {
      const msg = window.isvParser({ data });
      console.log('onMessage:', data, msg);
      window.bot.getCtx().updateOrAppendMessage(msg[0]);
    },
  },
});
window.im.start();

// 渲染對話頁面
window.bot = new window.ChatSDK({
  root: document.querySelector('#chatbot'),
  config: {
    navbar: {
      title: '智能助理',
    },
    robot: {
      avatar: '//gw.alicdn.com/tfs/TB1U7FBiAT2gK0jSZPcXXcKkpXa-108-108.jpg',
    },
    avatarWhiteList: ['all'],
    messages: [
      {
        type: 'text',
        content: {
          text: '智能助理為您服務，請問有什么可以幫您？',
        },
      },
    ],
  },
  requests: {
    send(msg) {
      window.im.sendMessage({
        msgType: 'text',
        content: {
          text: msg.content.text,
        },
      });
    },
  },
});

window.bot.run();
// 將ctx放到全局，方便外部進行操作調(diào)試
window.ctx = window.bot.getCtx();

Debug

通過瀏覽器調(diào)試窗口可查看websocket通訊的消息內(nèi)容

?