Recalling One-to-One Messages

Last updated: 2020-05-14 18:28:55

    Feature Description

    • This API enables admins to recall one-to-one messages.
    • This API can recall all one-to-one messages, including those sent by the client or by the Sending a One-to-one Message and Batch Sending One-to-one Messages RESTful APIs.
    • To recall one-to-one messages sent by the client, you can enable the callback before sending one-to-one messages or callback after sending one-to-one messages. By using the callback API, record the MsgKey of each one-to-one message, and specify it in the MsgKey field of this API to recall messages. You can also use the API for querying one-to-one messages to query the MsgKey of the one-to-one message to be recalled, and then specify it in the MsgKey field of this API to recall the message.
    • To recall messages sent by the Sending a One-to-one Message and Batch Sending One-to-one Messages RESTful APIs, record the MsgKey fields in the API response packets and use them to recall these one-to-one messages.
    • Once a one-to-one message is recalled using this API, it is recalled from offline storage, roaming storage, and the local cache of the sender’s and recipient’s clients.
    • This API can recall one-to-one messages sent at any time. There’s no time limit.

    Exercise caution when using this API. One-to-one messages recalled by this API cannot be restored.

    API Calling Description

    Sample request URL

    Request parameters

    The following is a list of the parameters commonly used when calling this API and their descriptions. For more parameters, see the RESTful API Overview.

    Parameter Description
    v4/openim/admin_msgwithdraw Request API
    sdkappid The SDKAppID is assigned by the IM console when the app is created.
    identifier The value must be the admin account of the app. For more information, see App Admin.
    usersig The signature generated by the app admin account. For details on the operation, see Generating UserSig.
    random A random 32-bit unsigned integer ranging from 0 to 4294967295.

    Maximum calling frequency

    200 times/second

    Sample request packet

        "From_Account": "vinson",
        "To_Account": "dramon",
        "MsgKey": "31906_833502_1572869830"

    Request packet fields

    Field Type Attribute Description
    From_Account String Required UserID of the message sender
    To_Account String Required UserID of the recipient
    MsgKey String Required Unique identifier of the message, which is found in the responses to messages sent by the Sending a One-to-one Message and Batch Sending One-to-one Messages RESTful APIs

    Sample response packets

    • Normal response
        "ActionStatus": "OK", 
        "ErrorInfo": "", 
        "ErrorCode": 0,
    • Exceptional response
        "ActionStatus": "FAIL", 
        "ErrorInfo": "Fail to Parse json data of body, Please check it", 
        "ErrorCode": 0,

    Response packet fields

    Field Type Description
    ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
    ErrorCode Integer The error code. 0: succeeded. Other values: failed.
    ErrorInfo String Error information.

    Error Codes

    Unless a network error (such as error 502) occurs, the HTTP return code for this API is always 200. ErrorCode and ErrorInfo in the response packet represent the actual error code and error information.
    For public error codes (60000 to 79999), see Error Codes.
    The following are error codes specific to this API:

    Error code Description
    20022 The message to be recalled does not exist. Please check the provided information.
    20023 The message has been recalled.
    90001 Failed to parse the JSON format. Check whether the JSON request packet meets JSON specifications.
    90003 The JSON request packet does not contain the To_Account field or To_Account does not exist.
    90008 The JSON request packet does not contain the From_Account field or From_Account does not exist.
    90009 The request requires app admin permissions.
    90054 The MsgKey in the recall request is invalid.
    91000 Internal server error. Please try again.

    API Debugging Tool

    Use the [RESTful API online debugging tool] ( to debug this API.


    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback