Sending a One-to-One Message

Last updated: 2020-08-03 11:25:37

    Feature Description

    • When the admin sends a message to an account, the recipient will see that the message sender is the admin.
    • When the admin specifies an account to send a message to another account, the recipient will see that the sender is not the admin but the account specified by the admin.
    • This API does not check whether the sender and the recipient are friends (nor does it check the blocklist) or whether the recipient is muted.

    When the server uses this RESTful API to send one-to-one messages, you can choose whether to synchronize the messages to the sender (admin account or account specified by the admin). The synchronization methods include online terminals and the roaming server. The RESTful API provides the SyncOtherMachine parameter to determine whether to synchronize the messages. For details, see “Sample request packet”.

    API Calling Description

    Sample request URL

    https://console.tim.qq.com/v4/openim/sendmsg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

    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/sendmsg 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 packets

    Here, we use sending text messages as an example. To send messages of other types, set MsgBody to the corresponding message type. For details, see Message Format Description.

    The admin sends messages to another account

    If you do not want to synchronize messages to From_Account, set SyncOtherMachine to 2.
    To synchronize messages to From_Account, set SyncOtherMachine to 1.

    {
        "SyncOtherMachine": 2, // Messages are not synchronized to the sender.
        "To_Account": "lumotuwe2",
        "MsgLifeTime":60, // Messages are retained for 60 seconds.
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
    }

    The admin specifies an account to send messages to another account and enables offline information push, without synchronizing the messages to From_Account

    If you do not want to synchronize messages to From_Account, set SyncOtherMachine to 2.

    {
        "SyncOtherMachine": 2,
        "From_Account": "lumotuwe1",
        "To_Account": "lumotuwe2",
        "MsgLifeTime":3600, // Messages are retained for one hour.
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ],
        "OfflinePushInfo": {
            "PushFlag": 0,
            "Desc": "Offline push content",
            "Ext": "This is the passthrough content",
            "AndroidInfo": {
                "Sound": "android.mp3"
            },
            "ApnsInfo": {
                "Sound": "apns.mp3",
                "BadgeMode": 1, // The default value is 0, indicating that a message is counted. The value 1 indicates that the message is not counted, that is, the icon number in the upper right corner does not increase by one.
                "Title":"apns title", // apns title
                "SubTitle":"apns subtitle", // apns subtitle
                "Image":"www.image.com" // image url
            }
        }
    }

    The admin specifies an account to send messages to another account and enables synchronization of the messages to From_Account (the sender’s terminal)

    To synchronize messages to From_Account, set SyncOtherMachine to 1.

    {
        "SyncOtherMachine": 1, // Messages are synchronized to the sender.
        "From_Account": "lumotuwe1",
        "To_Account": "lumotuwe2",
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
    }

    Request packet fields

    Field Type Attribute Description
    SyncOtherMachine Integer Optional 1: messages are synchronized to the From_Account online terminals and roaming server.
    2: messages are not synchronized to From_Account.
    If this parameter is not specified, messages are synchronized to the From_Account roaming server by default.
    From_Account String Optional UserID of the sender (used to specify the sender’s account)
    To_Account String Required UserID of the recipient
    MsgLifeTime Integer Optional The retention period of offline message (in seconds); max period: 7 days (604,800 seconds)
  • If this field is set to 0, messages will only be sent to online users and not retained offline.
  • If this field is set to a period longer than 7 days (604,800 seconds), messages will still be retained for only 7 days.
  • If this field is not set, messages will be retained for 7 days by default.
  • MsgRandom Integer Required The message random number, which is generated by the random function and used to locate issues at the backend
    MsgTimeStamp Integer Optional The message timestamp; UNIX timestamp (in seconds)
    MsgBody Object Required Message body. For details on the format, see Message Format Description (note: a message can contain multiple message elements, with MsgBody being of the Array type).
    MsgType String Required TIM message object type. Supported message objects include TIMTextElem (text messages), TIMFaceElem (emoji messages), TIMLocationElem (location messages), and TIMCustomElem (custom messages).
    MsgContent Object Required Different message types have different MsgContent formats. For details, see Message Format Description.
    OfflinePushInfo Object Optional Offline push information configuration. For details, see Message Format Description.

    Sample response packet

    • Normal response

      {
        "ActionStatus": "OK", 
        "ErrorInfo": "", 
        "ErrorCode": 0, 
        "MsgTime": 1497238162,
        "MsgKey": "89541_2574206_1572870301"
      }
    • Exceptional response

      {
        "ActionStatus": "FAIL", 
        "ErrorInfo": "Fail to Parse json data of body, Please check it", 
        "ErrorCode": 90001
      }

    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.
    MsgTime Integer The message timestamp; UNIX timestamp
    MsgKey String The unique message identifier, which is used to cancel a message. It is a string of up to 50 characters.

    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
    20001 Invalid request packet
    20002 Invalid UserSig or A2
    20003 The UserID of the sender or recipient is invalid or does not exist. Please check whether the UserID has been imported into IM.
    20004 Network exception. Please try again.
    20005 Internal server error. Please try again.
    20006 The callback before sending a one-to-one message is triggered, and the app backend returns a response forbidding the message to be sent.
    90001 Failed to parse the JSON format. Check whether the JSON request packet meets JSON specifications.
    90002 Invalid MsgBody format or MsgBody is not an Array. See TIMMsgElement Object.
    90003 The JSON request packet does not contain the To_Account field or the To_Account field is not of the String type.
    90005 The JSON request packet does not contain the MsgRandom field or the MsgRandom field is not of the Integer type.
    90006 The MsgTimeStamp field in the JSON request packet is not of the Integer type.
    90007 The MsgBody field in the JSON request packet is not of the Array type. Change the type of the MsgBody field to Array.
    90009 The request requires app admin permissions.
    90010 The JSON request packet does not meet message format requirements. For more information, see the definition of TIMMsgElement Objects.
    90012 To_Account is not registered or does not exist. Check whether To_Account has been imported into the IM console or is incorrectly spelled.
    90026 Invalid message offline storage time. Messages cannot be stored offline for more than 7 days.
    90031 The SyncOtherMachine field in the JSON request packet is not of the Integer type.
    90044 The MsgLifeTime field in the JSON request packet is not of the Integer type.
    91000 Internal server error. Please try again.
    90992 Internal server error. Please try again. If this error code is returned for all requests and the app has configured third-party callback, check whether the app server sends the callback result to the IM backend server normally.
    93000 The JSON data packet exceeds the length limit of 8 KB.
    90048 The requested UserID does not exist.

    API Debugging Tool

    Use the RESTful API online debugging tool to debug this API.

    References

    Batch sending one-to-one messages (v4/openim/batchsendmsg)
    Querying one-to-one messages (v4/openim/admin_getroammsg)
    Recalling one-to-one messages (v4/openim/admin_msgwithdraw)

    Callbacks That May Be Triggered

    Was this page helpful?

    Was this page helpful?

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