====== CEC Android SDK API ======

  * [[#消息|消息]]
  * [[#会话|会话]]
  * [[#满意度评价|满意度评价]]
  * [[#留言|留言]]
  * [[#设置当前登录用户的推送昵称|推送昵称]]
  * [[#实时音视频|实时音视频]]
  * [[#欢迎语|欢迎语]]
  * [[#高级功能|高级功能]]
===== 消息 =====

==== 发送文本消息 ====

<code java>
//发送一条文本消息， content 为消息文字内容， toChatUsername为客服设置的IM服务号
Message message = Message.createTxtSendMessage(content, toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 发送语音消息 ====

<code java>
//filePath为语音文件路径， length为录音时间(秒)， toChatUsername为IM服务号
Message message = Message.createVoiceSendMessage(filePath, length, toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送图片消息 ====

<code java>
//filePath为图片路径， false为不发送原图(默认超过100k的图片都会压缩后发给对方)，需要发送原图传true， toChatUsername为IM服务号 
Message message = Message.createImageSendMessage(filePath, false, toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送地理位置 ====

<code java>
//latitude为维度，longitude为经度，locAddress为具体位置内容, toChatUsername为IM服务号
Message message = Message.createLocationSendMessage(latitude, longitude, locAddress, toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送文件消息 ====

<code java>
//filePath为本地文件路径，toChatUsername为IM服务号
Message message = Message.createFileSendMessage(filePath, toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送转接客服消息 ====

<code java>
//toUserName是转接客服消息的Target客服（可以从收到的转接客服按钮消息中提取） ， info是ToCustomServiceInfo的消息实体（收到的转接客服按钮消息内容中提取） 
Message message = Message.createTranferToKefuMessage(toUserName, info);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送透传消息 ====

<code java>
Message message = Message.createSendMessage(Message.Type.CMD);
String action = "action";//具体的action
message.setBody(new EMCmdMessageBody(action));
message.setTo(toChatUsername);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback(){});
</code>

==== 发送扩展消息 ====

任何消息类型，均可发送扩展消息。某些功能是通过扩展消息实现的，例如：指定技能组、指定客服、传递访客的昵称电话等。

<code java>
Message message = Message.createTxtSendMessage(content, toChatUsername);
// 增加自己特定的属性
message.setAttribute("attribute1", "value");
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 发送带访客属性的消息 ====
 
当需要为客服提供访客属性（昵称、电话等）时，需要为消息带上访客属性扩展。发送文本消息示例：

<code java>
VisitorInfo info = ContentFactory.createVisitorInfo(null);
info.nickName("user nick")
    .name("truly name")
    .qq("10000")
    .companyName("环信")
    .description("")
    .email("abc@123.com");
Message message = Message.createTxtSendMessage(content, toChatUsername);
message.addContent(info);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 发送轨迹消息 ====

<code java>
VisitorTrack track = ContentFactory.createVisitorTrack(null);
track.title("test_track1")  //显示标题
    .price("￥235") //显示价格
    .desc("假两件衬衣+V领毛衣上衣") //描述
    .imageUrl("https://o8ugkv090.bkt.clouddn.com/em_three.png")//显示图片
    .itemUrl("https://www.baidu.com"); //点击会跳转到哪
Message message = Message.createTxtSendMessage(content, toChatUsername);
message.addContent(track);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 发送订单消息 ====

<code java>
OrderInfo info = ContentFactory.createOrderInfo(null);
info.title("test_order1")
    .orderTitle("订单号：7890")
    .price("￥128")
    .desc("2015早春新款高腰复古牛仔裙")
    .imageUrl(IMAGE_URL_1)
    .itemUrl("https://www.baidu.com");
Message message = Message.createTxtSendMessage(content, toChatUsername);
message.addContent(info);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 指定客服消息 ====

调度时，指定某个客服。

客服账号为客服的登录邮箱地址。

<code java>
AgentIdentityInfo info = ContentFactory.createAgentIdentityInfo(null);
info.agentName(agentName); //客服账号
Message message = Message.createTxtSendMessage(content, toChatUsername);
message.addContent(info);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>

==== 指定技能组消息 ====

调度时，指定某个技能组。

技能组名称须和客服系统设置的技能组名称完全一致，中英文均可。

<code java>
QueueIdentityInfo info = ContentFactory.createQueueIdentityInfo(null);
info.queueName(queueName); // 技能组名称
Message message = Message.createTxtSendMessage(content, toChatUsername);
message.addContent(info);
ChatClient.getInstance().chatManager().sendMessage(message, new Callback() {});
</code>
==== 接收消息 ====

通过注册消息监听来接收消息。

<code java>
ChatClient.getInstance().chatManager().addMessageListener(new ChatManager.MessageListener() {
    @Override
    public void onMessage(List<Message> list) {
        //收到普通消息
    }

    @Override
    public void onCmdMessage(List<Message> list) {
        //收到命令消息，命令消息不存数据库，一般用来作为系统通知，例如留言评论更新，
        //会话被客服接入，被转接，被关闭提醒
    }

    @Override
    public void onMessageStatusUpdate() {
        //消息的状态修改，一般可以用来刷新列表，显示最新的状态
    }

    @Override
    public void onMessageSent() {
        //发送消息后，会调用，可以在此刷新列表，显示最新的消息
    }
});
        
//不需要的时候移除listener，如在activity的onDestroy()时
ChatClient.getInstance().chatManager().removeMessageListener(msgListener);
</code>

==== 检测消息类型 ====

<code java>
message.getType() == Message.Type.LOCATION  位置消息
message.getType() == Message.Type.FILE   文件消息
message.getType() == Message.Type.IMAGE  图片消息
message.getType() == Message.Type.VOICE  语音消息
message.getType() == Message.Type.CMD    命令消息
message.getType() == Message.Type.TXT    文本消息或文本扩展消息
//当文本消息时，需要其他其他的检测，可能为其他类型的消息
MessageHelper.getMessageExtType(message)可以获取额外的消息类型
enum ExtMsgType {
    EvaluationMsg,  //满意度评价消息
    OrderMsg,       //订单消息
    TrackMsg,       //轨迹消息
    FormMsg,        //表单信息
    RobotMenuMsg,   //机器人菜单信息
    ArticlesMsg,    //图文消息
    ToCustomServiceMsg,    //转接客服按钮消息
    BigExpressionMsg,      //大表情消息
    GeneralMsg      //普通的文本消息
}
</code>

==== 监听消息状态 ====

通过 message 设置消息的成功失败监听。

<code java>
message.setMessageStatusCallback(new Callback(){});
</code>


==== 获取聊天记录 ====

<code java>
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(toChatUsername);
//获取此会话的所有消息
List<Message> messages = conversation.getAllMessages();
//SDK初始化加载的聊天记录为20条，到顶时需要去DB里获取更多
//获取startMsgId之前的pagesize条消息，此方法获取的messages SDK会自动存入到此会话中，APP中无需再次把获取到的messages添加到会话中
List<Message> messages = conversation.loadMessages(startMsgId, pageSize);
</code>

==== 获取未读消息数量 ====

<code java>
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(toChatUsername);
conversation.unreadMessagesCount()
</code>

==== 未读消息数清零 ====

<code java>
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(toChatUsername);
//指定会话消息未读数清零
conversation.markAllMessagesAsRead();
//把一条消息置为已读
conversation.markMessageAsRead(messageId);
//所有未读消息数清零
ChatClient.getInstance().chatManager().markAllConversationsAsRead();
</code>

==== 获取消息总数 ====

<code java>
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(toChatUsername);
//获取此会话在本地的所有的消息数量
conversation.getAllMsgCount()
//如果只是获取当前在内存的消息数量，调用
conversation.getAllMessages().size()
</code>

===== 会话 =====

==== 获取所有会话 ====

<code java>
Map<String, Conversation> conversations = ChatClient.getInstance().chatManager().getAllConversations();
</code>

==== 删除会话及聊天记录 ====

<code java>
//删除和某个user会话，如果需要保留聊天记录，传false
ChatClient.getInstance().chatManager().deleteConversation(username, true);
//删除当前会话的某条聊天记录
Conversation conversation = ChatClient.getInstance().chatManager().getConversation(toChatUsername);
conversation.removeMessage(deleteMsg.msgId);
</code>

===== 满意度评价 =====

==== 判断是否为满意度评价消息 ====

<code>
if(MessageHelper.getEvalRequest(message) != null){
//通过Message获取满意度相关信息存在，则代表此条消息为满意度消息
}
</code>

==== 评价此会话 ====

可对此会话设置评分和标签(后台可修改添加标签)
<code>
 EvaluationInfo evaluationInfo = MessageHelper.getEvalRequest(currentMessage);
 // 此对象含有满意度相关信息，例如：级别、标签列表等。
 
// currentDegree可以从evaluationInfo中选择，具体多少分，selectedTags代表具体的标签，在degree内，需后台设置后才会有。

MessageHelper.sendEvalMessage(currentMessage, "评价备注内容", currentDegree, selectedTags, new Callback());
</code>

详见：商城Demo: com.easemob.helpdeskdemo.ui.SatisfactionActivity

==== 主动发起满意度评价邀请 ====

<code>
 ChatClient.getInstance().chatManager().asyncSendInviteEvaluationMessage(toChatUsername, null);
</code>



===== 留言 =====

==== 获取所有留言 ====

<code java>
/**
 * 获取所有留言
 * @param projectId  留言ProjectId  进入“管理员模式 → 留言”，可以看到这个Project ID
 * @param targetUser    接入环信客服云使用的关联的IM服务号
 * @param page      第几页数据,从0开始
 * @param pageSize  每页显示的条数
 * @param callback
 */
ChatClient.getInstance().leaveMsgManager().getLeaveMsgs(projectId, targetUser, page, pageSize, new ValueCallBack<String>() {});
</code>

==== 获取一条留言 ====

<code java>
/**
 * 获取一条留言
 * @param projectId 留言ProjectId  进入“管理员模式 → 留言”，可以看到这个Project ID
 * @param targetUser 接入环信移动客服系统使用的关联的IM服务号
 * @param ticketId 留言的id TicketEntity的id字段
 * @param callback
 */
ChatClient.getInstance().leaveMsgManager().getLeaveMsgDetail(projectId, targetUser, ticketId, new ValueCallBack<String>() {});
</code>

==== 创建一个新的留言 ====

<code java>
/**
 * 创建一个新的留言
 *
 * @param postContent
 * @param projectId 留言ProjectId  进入“管理员模式 → 留言”，可以看到这个Project ID
 * @param imUser  接入环信移动客服系统使用的关联的IM服务号
 * @param callback
 */
ChatClient.getInstance().leaveMsgManager().createLeaveMsg(postContent, projectId, imUser, new ValueCallBack(){});
</code>

==== 获取一个留言的所有评论 ====

<code java>
/**
 * 获取一个留言的所有评论 分页获取
 *
 * @param projectId 留言ProjectId  进入“管理员模式 → 留言”，可以看到这个Project ID
 * @param ticketId  留言ID
 * @param targetUser  接入环信客服云使用的关联的IM服务号
 * @param callback
 * @param page  第几页，页码从0开始
 * @param size  每页显示多少个
 */
ChatClient.getInstance().leaveMsgManager().getLeaveMsgComments(projectId, ticketId, targetUser, new ValueCallBack(){}, page, size);
</code>

==== 给一个留言添加评论 ====

<code java>
/**
 * 给一个留言添加评论
 *
 * @param projectId         留言ProjectId  进入“管理员模式 → 留言”，可以看到这个Project ID
 * @param ticketId          留言ID
 * @param targetUser        接入环信客服云使用的关联的IM服务号
 * @param newCommentBodyJson
 * @param callback
 */
ChatClient.getInstance().leaveMsgManager().createLeaveMsgComment(projectId, ticketId, targetUser, newCommentBodyByJson, new ValueCallBack(){});
</code>

==== 获取工作状态 ====

<code java>
/**
 * 是否显示留言信息（一般在上班显示联系客服界面，在下班情况下显示留言界面）
 * 返回true 为下班状态, 返回false为上班状态
 */
ChatClient.getInstance().leaveMsgManager().getWorkStatus(new ValueCallBack(){});
</code>

===== 设置当前登录用户的推送昵称 =====

更新当前用户的在苹果 APNS 推送的昵称
**如果个人的昵称被更改，也要去环信服务器更新下 nickname 防止显示差异。**
<code java>
//此方法传入一个字符串String类型的参数，返回成功或失败的一个Boolean类型的返回值
ChatClient.getInstance().setPushNickname(nickname)
</code>

===== 实时音视频 =====
==== 监听呼入通话 ====
通过注册相应 action 的 BroadcastReceiver 来监听呼叫过来的通话，接到广播后开发者可以调起 APP 里的通话 Activity。
<code java>
IntentFilter callFilter = new IntentFilter(ChatClient.getInstance().callManager().getIncomingCallBroadcastAction());
registerReceiver(new CallReceiver(), callFilter);

private class CallReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        // 拨打方username
        String from = intent.getStringExtra("from");
        // call type
        String type = intent.getStringExtra("type");
        //跳转到通话页面
    }
}
</code>
 

==== 接听通话 ====

<code java>
/**
 * 接听通话
 */
ChatClient.getInstance().callManager().acceptCall(new Callback(){});
</code>

==== 拒绝接听 ====

<code java>
/**
 * 拒绝接听
 * 
 */
ChatClient.getInstance().callManager().endCall();
</code>

==== 挂断通话 ====

<code java>
/**
 * 挂断通话
 */
ChatClient.getInstance().callManager().endCall();
</code>

==== 暂停和恢复语音或视频数据传输 ====
  * 暂停语音数据传输：
<code java>
ChatClient.getInstance().callManager().pauseVoice();
</code>
  * 恢复语音数据传输：
<code java>
ChatClient.getInstance().callManager().resumeVoice();
</code>
  * 暂停视频（图像）数据传输：
<code java>
ChatClient.getInstance().callManager().pauseVideo();
</code>
  * 恢复视频（图像）数据传输：
<code java>
ChatClient.getInstance().callManager().resumeVoice();
</code>
==== 切换摄像头 ====

视频通话时如果有前置摄像头，默认使用前置的，提供切换 API 切换到别的摄像头。
<code java>  
ChatClient.getInstance().callManager().switchCamera();
</code>
==== 视频通话设置显示自己和对方图像的 surfaceView ====

<code java>  
// 设置自己的视频图像
ChatClient.getInstance().callManager().setLocalView(localSurfaceView);
// 设置非自己的视频图像
ChatClient.getInstance().callManager().setRemoteView(streamId, remoteSurfaceView);
</code>

==== 视频通话设置显示自己和对方图像的 surfaceView ====

<code java>  
// 设置自己的视频图像
ChatClient.getInstance().callManager().setLocalView(localSurfaceView);
// 设置非自己的视频图像
ChatClient.getInstance().callManager().setRemoteView(streamId, remoteSurfaceView);
</code>

==== 设置视频码率 ====

<code java>  
// 设置最大视频码率
ChatClient.getInstance().callManager().setVideoMaxKbps({int videoMaxKbps});
// 设置最小视频码率
ChatClient.getInstance().callManager().setVideoMinKbps({int videoMinKbps});
// 设置最大音频码率
ChatClient.getInstance().callManager().setAudioMaxKbps({int audioMaxKbps});
</code>

==== 监听视频流的回调 ====

<code java> 
// 添加视频流变化监听，一般在onCreate中调用
ChatClient.getInstance().callManager().addDelegate(this);
// 取消监听视频流变化，一般在onDestroy方法中调用
ChatClient.getInstance().callManager().removeDelegate(this);
  
public interface CallManagerDelegate {
    // 当接收到有视频流加入时
    void onAddStream(MediaStream stream);
    // 当接收到有视频流取消时
    void onRemoveStream(MediaStream stream);
    // 当接收到有视频流更新时
    void onUpdateStream(MediaStream stream);
    // 当接收到视频聊天被挂断时
    void onCallEnd(int reason, String description);
    // 通知事件
    void onNotice(HMediaNoticeCode code, String arg1, String arg2, Object arg3);
    // 通知可能有：HMediaNoticeStats | HMediaNoticeReconn | HMediaNoticeDisconn | HMediaNoticeCustomMsg | HMediaNoticePoorQuality |HMediaNoticeOpenMicFail | HMediaNoticeOpenCameraFail | HMediaNoticeTakeCameraPicture
}
</code>

==== 只需要语音通话，不需要视频通话 ====

 通话界面后，先调用此方法即可

<code>
CallOption callOption = new CallOption()
callOption.isVideoOff = true  //是否不启动摄像头
callOption.isMute = false; //是否静音
callOption.useBackCamera = false; //是否启用后置摄像头
callOption.videoHeight = .. //设置视频高度
callOption.videoWidth = .. // 设置视频宽度
ChatClient.getInstance().callManager.setCallOption(callOption);
</code>

==== 取消视频邀请 ====

<code java>  
// 当访客端主动取消视频的邀请时，可调用此接口
ChatClient.getInstance().chatManager().cancelVideoConferences({im服务号}, null);

</code>


===== 欢迎语 =====

==== 获取企业欢迎语 ====

<code>
ChatClient.getInstance().chatManager().getEnterpriseWelcome(new ValueCallBack<String>() {});
</code>

==== 获取当前会话ID ====
<code>
// toChatUsername 为IM服务号
ChatClient.getInstance().chatManager().getCurrentSessionId(toChatUsername, new ValueCallBack<String>() {});
当返回value为空时，则代表此会话不存在，也就是未咨询或者咨询已结束，下次咨询可先发欢迎语
当返回value不为空时，则返回的当前会话的会话ID，也就是说会话正在咨询中，不需要发送欢迎语
</code>

===== 高级功能 =====

==== 显示排队人数 ====

首先，初始化时，需要调用option.showVisitorWaitCount(),然后添加WaitListener.


<code java>  
ChatClient.getInstance().chatManager().addVisitorWaitListener(new ChatManager.VisitorWaitListener() {
    @Override
    public void waitCount(final int num) {
        if (getActivity() == null){
            return;
        }
        getActivity().runOnUiThread(new Runnable() {
            @Override
            public void run() {
                if (num > 0){
                    tvTipWaitCount.setVisibility(View.VISIBLE);
                    tvTipWaitCount.setText(getString(R.string.current_wait_count, num));
                }else{
                    tvTipWaitCount.setVisibility(View.GONE);
                }
            }
        });
    }
});
</code>

==== 显示坐席输入状态 ====

首先，初始化时，需要调用options.showAgentInputState(),然后添加AgentInputListener.

注：“显示坐席输入状态”功能为标准版增值服务、旗舰版基础功能。如需开通，请提供租户ID并联系环信商务经理。

<code java> 
ChatManager.AgentInputListener agentInputListener = new ChatManager.AgentInputListener() {
    @Override
    public void onInputState(final String input) {
        if (getActivity() == null){
            return;
        }
        getActivity().runOnUiThread(new Runnable() {
            @Override
            public void run() {
                if (input != null) {
                    titleBar.setTitle(input);
                } else {
                    if (!TextUtils.isEmpty(titleName)) {
                        titleBar.setTitle(titleName);
                    } else {
                        titleBar.setTitle(toChatUsername);
                    }
                }
            }
        });
    }
};
// 在onCreate中调用添加监听
ChatClient.getInstance().chatManager().addAgentInputListener(agentInputListener);
// 在onDestroy中调用移除监听    
ChatClient.getInstance().chatManager().removeAgentInputListener(agentInputListener);
</code>