ChatUI是一套对话式界面组件，专注于智能对话领域的设计和技术研发体系，助力消费者可体验的对话式界面搭建。

使用说明

如何引入

脚本引用

<script src="https://g.alicdn.com/ume/chatbot/1.1.9/im-sdk-v2.js"></script>
<script>
  const im = new window.IMSDK({
    config: {
      /**
       * ws/http地址
          ws示例
            wss://**.alimebot.com/alime/im
       */
      url: "wss://xxx.aliyuncs.com/xxx",
      /**
       * IM鉴权参数，接入方自行实现token生成和校验逻辑接入方后端提供token生成接口给前端
       */
      token: "T3ZEcEdWK3hOTXNRNklUejhTaWN6bllsTzVRTEIzSWRSbWJjSGxWTW5VMS9zZ1BKWDEzMEZFbUlMWEY4czhRRE5IcFZGVC9sUURLczlwa2c1ZC9vQ0pBWW9uNzRQRDJoVFFjMjcwTlZwWllsMTJYb0JiWk0wRlhpTzBmdWtyMFJmVEs4MGFJQjVWeWtHY2NCalFqTkthSVVzVlpGalRsQm53VWtiNmxRanBjPQ==",
      /**
       * 应用key
       */
      appKey: "8xx4xxxx",
      /**
       * 获取token的函数，返回Promise对象，resolve token
       */
    	getToken: () => {
        return new Promise((resolve) => {
          resolve("T3ZEcEdWK3hOTXNRNklUejhTaWN6bllsTzVRTEIzSWRSbWJjSGxWTW5VMS9zZ1BKWDEzMEZFbUlMWEY4czhRRE5IcFZGVC9sUURLczlwa2c1ZC9vQ0pBWW9uNzRQRDJoVFFjMjcwTlZwWllsMTJYb0JiWk0wRlhpTzBmdWtyMFJmVEs4MGFJQjVWeWtHY2NCalFqTkthSVVzVlpGalRsQm53VWtiNmxRanBjPQ==");
        });
      },
    },
    handlers: {
      /**
       * 接收到业务消息
       */
      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次依然失败，此时建议提示用户系统出错，手动重试
       *    CHEARTBEAT_TIMEOUT：心跳超时断开，未收到pong消息，此时sdk会自动重连，接入方无特殊需求则不用处理
       *    CSERVER_CONNECTION_CLOSED：服务器正在重启引起的连接断开，此时sdk会自动重连，接入方无特殊需求则不用处理
       *    CCONNECTION_TIMEOUT：会话超时连接断开，用户超过一定时长未说话，用户再次发消息会自动重连
       */
      onClose: (err: string) => {
        console.error(err);
      }
    }
  });

	// 开始建联
  im.start();

	/**
   * @method 设置消息通用参数 [可选]
   * @parma {CommonParamsProps} params 发消息者参数
   * @returns
   */
  im.setCommonParams({
    senderId: userId,
    senderNick: nick,
    senderRole: 1,
  });
</script>

初始化

接口

im建联数据获取

后端通过pop接口调用，获取im建联需要参数数据：

字段名	字段类型	是否必填	默认值	说明
ImDomain	String	是	-	ws地址
Token	String	是	-	IM鉴权参数，接入方自行实现token生成和校验逻辑接入方后端提供token生成接口给前端详情
AppKey	String	是	-	应用key

接口详情

方法名：InitIMConnect
请求方式：GET POST
请求参数：

名称	类型	必填	描述	示例值
FROM	String	是	用户昵称	XSDDAG
UserAccessToken	String	否	用户token，通过调用pop接口生成	wewadwdassdas23123
AgentKey	String	否	业务空间key,不设置则访问默认业务空间，key值在主账号业务管理页面获取

maven版本

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-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泄露，威胁您账号下所有资源的安全。
         *  调用接口前请先配置身份认证，具体操作请参见https://help.aliyun.com/document_detail/378659.html。
         *  本示例使用了阿里云Credentials工具托管AccessKey，来实现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()
                        // 配置云产品服务接入地址（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);

    }
}

接口返回数据：

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

配置

初始化时需要传入一个config和handlers对象；

config

字段名	字段类型	是否必填	默认值	说明
type	String	否	ws	IM连接类型 ws：websocket http：http请求
url	String	是	-	ws/http地址
token	String	是	-	IM鉴权参数，接入方自行实现token生成和校验逻辑接入方后端提供token生成接口给前端详情
appKey	String	是	-	应用key
uid	String	否	-	用户id
tid	String	否	-	租户id
sid	String	否	-	会话标识
getToken	Function	是	-	获取token的函数，返回Promise对象，resolve token

handlers

请查看《事件》章节

建立连接

im.start();

设置IM消息通用参数

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

通用参数列表，请查看 setCommonParams(params)

API

getIM()

用途

获取IM实例

参数

无

IM实例

setCommonParams(params)

用途

设置消息通用参数

使用场景

比如获取地理位置信息是异步的，那么可以在拿到lbs信息之后再设置这个通用参数，这样后续消息发送都会带上

参数

params里的参数列表如下

字段名	字段类型	是否必填	默认值	说明
senderId	Number	是	-	发消息者的id
senderNick	String	是	-	发消息者nick
senderRole	Number	是	-	消息发送者，1表示会员
device	String	否	-	设备信息
lbs	Object	否	-	地理位置信息 province city district longitude latitude

无

示例

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

connect(sync)

用途

建立IM连接

参数

字段名	字段类型	是否必填	默认值	说明
sync	Boolean	否	false	是否同步离线消息

无

readyState()

用途

获取IM的状态，状态

参数

无

类型：number

枚举值：

0：CONNECTING，表示正在连接
1：OPEN，表示连接成功，可以通信了
2：CLOSING，表示连接正在关闭
3：CLOSED，表示连接已经关闭，或者打开连接失败

sendMessage(msg, ghost)

用途

发送消息

参数

msg为对象，具体字段如下

字段名	字段类型	是否必填	默认值	说明
msgType	String	是	-	消息类型
content	Object	是	-	消息体
context	Object	否	-	消息上下文
extraInfo	Object	否	-	消息额外信息

字段名	字段类型	是否必填	默认值	说明
ghost	Boolean	否	false	是否存储发送的这条消息

无

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

close()

用途

关闭IM连接

参数

无

reconnect(code)

用途

重新建立连接

参数

字段名	字段类型	是否必填	默认值	说明
code	String	是	-	重连原因

无

事件

onAck

接收到心跳

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

onMessage

接收到业务消息

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

onOpen

websocket连接建立成功

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

onConnect

IM建立连接成功，和open有区别，connect是和IM系统建立连接成功的事件

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

onClose

IM连接关闭

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

code为关闭原因

CONNECTION_KICK_OUT：重复登录，此时建议提示用户有重复登录
CONNECTION_CLOSED：重连5次依然失败，此时建议提示用户系统出错，手动重试
HEARTBEAT_TIMEOUT：心跳超时断开，未收到pong消息，此时sdk会自动重连，接入方无特殊需求则不用处理
SERVER_CONNECTION_CLOSED：服务器正在重启引起的连接断开，此时sdk会自动重连，接入方无特殊需求则不用处理
CONNECTION_TIMEOUT：会话超时连接断开，用户超过一定时长未说话，用户再次发消息会自动重连

onError

IM连接出错

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

onReconnect

IM正在重连

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

代码示例

搭配ChatUI实现的对话界面

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: '联系人工服务',
    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: 'ws://im-daily.taobao.net/alime/im',
        token: '4890',
        appKey: 'QA97fCuA',
        getToken: () => {
          return new Promise(resolve => {
            resolve('4890');
          });
        },
      },
      handler: {
        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);
  }, []);
  // 发送回调
  function handleSend(type, val) {
    if (type === 'text' && val.trim()) {
      im.sendMessage({
        msgType: 'text',
        content: {
          text: val,
        },
      });
      appendMsg({
        type: 'text',
        content: { text: val },
        position: 'right',
      });
    }
  }
  // 快捷短语回调，可根据 item 数据做出不同的操作，这里以发送文本消息为例
  function handleQuickReplyClick(item) {
    handleSend('text', item.name);
  }
  function renderMessageContent(msg) {
    const { type, content } = msg;
    // 根据消息类型来渲染
    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'));