====== 消息撤回 ======

''本文档已不再维护，新版文档见：[[ccim:android:message2|消息管理–发送和接收消息]]。''

-------
===== 服务设置 =====

  * 默认设置：消息撤回时限默认为2分钟。
  * 是否增值服务：是

===== 服务分类 =====
  * 端消息撤回
  * REST消息撤回


===== 功能介绍 =====

  - 用户可以在消息发出后的撤回时限内从客户端发起消息撤回操作；
  - 被撤回的消息将会从服务器的离线队列中删除，如果应用已开通消息漫游，则所有已登录客户端均撤回或不再接收此消息；
  - 消息撤回时限默认2分钟，可根据开发者需求以AppKey为单位进行单独设置；
  - 端消息撤回由用户在各客户端上主动进行消息撤回操作；
  - REST消息撤回赋予了APP管理员对消息进行撤回的能力，可以对不良消息进行人工的处理;

<WRAP round tip>
**注意：**

消息撤回时限建议短于服务器保存消息的时间（默认7天，若开通[[im:extensions:value:messageroaming|消息漫游]]增值服务可延长至3个月或者6个月），如果消息撤回时限被设置成了超过服务端消息保存的时间，需要撤回的消息在请求撤回之前已经由于过期在服务端被删除，消息撤回请求会失败，无法从已经收到该消息的客户端撤回该消息。
</WRAP>
===== 使用方法 =====

==== Android ====

<code java>
EMClient.getInstance().chatManager().recallMessage(contextMenuMessage);
</code>

==== iOS ====

<code objc>
(void)recallMessage:(EMMessage *)aMessage
           completion:(void (^)(EMMessage *aMessage, EMError *aError))aCompletionBlock;
</code>


==== Web ====
<code javaScript>
 WebIM.conn.recallMessage({
   mid:mid,       //服务端消息ID
   to : username, //接收方ID
   type: 'chat'   // 单聊为'chat',群组为'groupchat'，聊天室为 'chatroom'
})
</code>


==== REST API ====
=== 服务端消息撤回 ===
应用管理员调用接口可以对发送消息进行撤回。允许撤回时间可以在通讯云管理后台进行设置，最大设置时间为7天。
=== HTTP Request ===

^{{:im:server:ready:post.png?nolink&90 |}}^**/{org_name}/{app_name}/messages/recall**^

=== Request Headers ===

^参数^说明^
|Content-Type|application/json|
|Authorization|Bearer ${token}|

=== Request Body ===

^参数^说明^
|msg_id|撤回消息的消息id|
|to|撤回消息的接收方|
|chat_type|撤回消息的消息类型，有单聊chat和群聊group_chat两种类型|

=== Response Body ===
在返回值中查看msgs字段包含的信息
^参数^说明^
|msg_id|需要撤回消息id|
|recalled|返回结果，成功是yes|
|from|消息撤回方，这里是admin表示通过REST接口撤回|
|to|撤回消息送达方，用户名或者群名|
|chattype|消息类型，chat或者groupchat|


=== 请求示例 ===

<code php>
curl -i -X POST -H "Authorization: Bearer YWMtnIF_ZI-GEea1KgfxnnDmKAAAAVjnsTKe0OE4vMOBWCtOcrB-56YcrhOHMho" "https://a1.easemob.com/{org_name}/{app_name}/messages/recall" -d '{"msgs": [{"msg_id": "673296797703079892","to": "99537689575425","chat_type": "groupchat"},{"msg_id": "673296835082717140","to": "yifan1","chat_type": "chat"}]}' 
</code>

=== 可能返回的结果示例 ===

**返回值200，表示撤回成功**

**成功结果：**

**msg_id** :需要撤回消息id 

**recalled** :返回结果，成功是yes

**from** : 消息撤回⽅方，这⾥里里是admin表示通过接⼝口撤回 

**to** : 撤回消息送达⽅方，⽤用户名或者群名

**chattype** : 消息类型， chat或者groupchat 

<code json>
{
    "msgs": 
        [
            { "msg_id":"673296835082717140",
      	      "recalled":"yes", 
      	      "from":"admin",
      	      "to":"yifan1", 
      	      "chattype":"chat" 
      	    }, 
            { "msg_id":"673296797703079892",
      	      "recalled":"yes", 
      	      "from":"admin", 
      	      "to":"99537689575425",
      	      "chattype":"groupchat" 
            } 
        ]
}
</code>
**失败结果：**

**msg_id** :需要撤回消息id 

**recalled** :撤回结果，有以下⼏几种情况 

	1."can't find msg to"，⽆无法找到撤回消息的接收⽅方 
	2."exceed recall time limit" 消息撤回时间超时 
	3."not_found msg",消息已经过期或者已经被撤回 
	4."internal error"，出现后端服务异常 

<code json>
{
	"msgs": 
	[
		{ "msg_id":"673296835082717140",
			"recalled":"not_found msg" 
		}, 
		{
		  "msg_id":"673296797703079892",
		  "recalled":"not_found msg
		} 
	] 
}
</code>
**返回结果:**

消息撤回服务没有开通
<code json>
{
    "error":"forbidden_op",
    "exception":"EasemobForbiddenOpException",
    "timestamp":1644402553845,
    "duration":0,
    "error_description":"message recall service is unopened"
}
</code>

=== 响应码 ===
^状态码^描述^
|200|请求成功。|
|401|鉴权失败（无 token，token 错误或者过期），请重新获取 token 再试。|
|403|撤回失败。|
|429，503 或者其他 5xx|单位时间内请求过多。请稍后重试。|
|500|服务器内部错误。如果问题持续存在，请联系我们的技术支持团队。|

----
<WRAP group>
<WRAP half column>
上一页：[[im:extensions:value:messageroaming|消息漫游]]
</WRAP>

<WRAP half column>
下一页：[[im:extensions:live:intro|产品介绍]]
</WRAP>
</WRAP>