npm package: @meiqia/widget-sdk
Description: widget chat SDK.
Author: fe
Latest version: 1.0.5

# Widget SDK

## 安装

### ES6 模块

```shell
npm install @meiqia/widget-sdk
或
yarn add @meiqia/widget-sdk
```

### 浏览器环境

```html
<script src="widget-sdk.js"></script>
```

## 使用

### ES6 模块

```javascript
import widgetSdk from '@meiqia/widget-sdk';
widgetSdk.init();
```

### 浏览器环境

```html
<script>
  widgetSdk.init();
</script>
```

## 注意事项

SDK 内部使用了 `JSON` , `Array` 等原生对象的原型链方法，如果您的应用有修改原生对象的行为则可能造成未知影响。

## API

### Callback 数据格式

```javascript
widgetSdk.emit('init', data, res => {
  const {
    code: 0,          // 成功返回0，失败返回值 < 0
    data: {},         // 成功返回相应的数据，失败返回 null
    message: 'string' // 成功无该字段，失败返回相应的错误信息
  } = res;
});

通用数据类型：
Agent {
  id: number;
  groupId: number;
  token: string;
  privilege: string;
  avatar: string;
  nickname: string;
  realname: string;
  signature: string;
  cellphone: string;
  telephone: string;
  email: string;
  qq: string;
  weixin: string;
}

Msg {
  id: number;
  agent: Agent;
  convId: number;
  contentType: ReceiveMsgType;
  content: string | unknown[];
  fromType: 'agent' | 'bot' | 'client';
}

```





### 向sdk发送指令执行一些操作 widgetSdk.emit(name, [data], [callback])

#### 初始化

初始化widget

```javascript
widgetSdk.emit('init', data, callbcak);

// widgetSdk.init 是 widgetSdk.emit('init') 的别名

data {
  entId: number;        // 企业ID
  trackId?: string;     // 访客跟踪ID
  title?: string;       // 页面标题
  url?: string;         // 页面URL
  referrerUrl?: string; // 来源URL
}

callback data {
  visitorStatus: number;
  trackId: string;
  visitId: string;
  browserId: string;
  servability: boolean;
  agentOnline: boolean;
  entWelcomeMessage: string;
}
```



#### 分配对话

分配对话，在init成功之后执行

```javascript
widgetSdk.emit('scheduler', data, callback);

data {
  agentToken: string; // 客服Token
  groupToken: string; // 客服组Token
  url: string;        // 页面标题
  title: string;      // 页面URL
}

callback data {
  success: boolean;
  result: string;
  agent?: Agent;
  conv?: {
    id: number;
  };
  historyMsgs?: Msg[];
}
```



#### 消息

访客发送消息

```javascript
widgetSdk.emit('sendMsg', data, callback);

data {
  type: 'text' | 'photo' | 'file'; // 消息类型
  content: string;                 // 消息内容，消息为text类型时传入
  file: File;                      // 文件对象，消息为photo或file类型时传入
}

callback data {
  success: boolean;
  msg?: Msg;
}
```



#### 排队

获取访客排队进度

```javascript
// 没有参数
widgetSdk.emit('getQueuePosition', callback);

callback data {
  inQueue: boolean;
  position: number;
}
```



#### 访客名片

设置访客名片

```javascript
widgetSdk.emit('setAttr', data, callback);

data {
  [your-attr-name]: string | number;
  ...
}

callback data: null
```



#### 工单

获取工单配置

```javascript
widgetSdk.emit('getTicketConfig', callback);

callback data {
  addresser_name: string;
  captcha: Switch;
  category: Switch;
  contactRule: 'single' | 'multi';
  intro: string;
  defaultTemplate: Switch;
  defaultTemplateContent: string;
  email: Switch;
  name: Switch;
  qq: Switch;
  tel: Switch;
  wechat: Switch;
  custom_fields: {
    name: string;
    type: 'string' | 'number' | 'radio' | 'check' | 'date';
    metainfo: string[];
    required: boolean;
    placeholder: string;
  }[];
  content_title: string;
  content_fill_type: 'content' | 'placeholder';
  content_placeholder: string;
}
```

提交工单

```javascript
widgetSdk.emit('sendTicket', data, callback);

data {
  content: string;
  categoryId: number;
}

callback data null
```


#### 询前表单

获取询前表单配置

```javascript
widgetSdk.emit('getPreinquiryConfig', callback);

callback data {
  status: Switch;
  title: string;
  form: {
    captcha: boolean;
    inputs: {
      status: Switch;
      title: string;
      fields: PreInquiryInputField[];
    };
    menus: {
      status: Switch;
      title: string;
      assignments: PreInquiryAssignItem[];
    };
  }
}
```


### 事件监听 widgetSdk.on(name, [callback])

收到新消息

```javascript
widgetSdk.on('newMsg', (msg: Msg) => {});
```

对话结束

```javascript
widgetSdk.on('endConversation', ({ evaluation: boolean }) => {});
```

收到对话邀请

```javascript
widgetSdk.on('invitation', ({ agentToken: string }) => {});
```

客服邀请评价

```javascript
widgetSdk.on('inviteEvaluation', () => {});
```

排队进入对话

```javascript
widgetSdk.on('initConvFromQueue', (agent: Agent) => {});
```