Sending a One-to-One Message

Last updated: 2020-09-15 19:33:34

    Features

    • 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 batch send a message to target accounts, the sender displayed to the recipients is not the admin, but is the account specified by the admin.
    • This API does not check whether the sender and the recipient are friends or blocked by either party or whether the recipient is muted.

    Note:

    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 the 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 packets”.

    API Call 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 table lists and describes only the parameters to be modified when this API is called. For more parameters, see the RESTful API Overview.

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

    Maximum call frequency

    200 calls per second

    Sample request packet

    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

    Note:

    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, // Do not synchronize messages 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 sends messages to another account and forbids callbacks for the messages

    Note:

    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, // Do not synchronize messages to the sender.
        "To_Account": "lumotuwe2",
        "MsgLifeTime":60, // Messages are retained for 60 seconds.
        "MsgRandom": 1287657,
        "MsgTimeStamp": 1557387418,
        "ForbidCallbackControl":[
            "ForbidBeforeSendMsgCallback",
            "ForbidAfterSendMsgCallback"], // Callback forbidding control options
        "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

    Note:

    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": "The content that is pushed offline",
            "Ext": "The passthrough content",
            "AndroidInfo": {
                "Sound": "android.mp3"
            },
            "ApnsInfo": {
                "Sound": "apns.mp3",
                "BadgeMode": 1, // If this parameter is not specified or is set to 0, the message is counted. If this parameter is set to 1, the message is not counted, that is, the icon number in the upper-right corner does not increase by 1.
                "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)

    Note:

    To synchronize messages to From_Account, set SyncOtherMachine to 1.

    {
        "SyncOtherMachine": 1, // Synchronize messages 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 Message timestamp in UNIX format (unit: second).
    ForbidCallbackControl Array Optional Message callback forbidding switch, valid only for a single message. ForbidBeforeSendMsgCallback forbids the callback before sending message; ForbidAfterSendMsgCallback forbids the callback after sending messages.
    MsgBody Object Required Message body. For more information on the format, see Message Format Description (note: a message can contain multiple message elements, wherein MsgBody is 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 packets

    • Normal response

      {
        "ActionStatus":"OK", 
        "ErrorInfo":"", 
        "ErrorCode": 0, 
        "MsgTime": 1572870301,
        "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 processing result of the request. OK: succeeded. FAIL: failed.
    ErrorCode Integer The error code. 0: succeeded. Other values: failed.
    ErrorInfo String Error information.
    MsgTime Integer Message timestamp in the UNIX format.
    MsgKey String The unique identifier of the message. This parameter is used to recall a message. The value 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 indicate the actual error code and error information, respectively.
    For public error codes (60000 to 79999), see Error Codes.
    The list below contains only 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 the recipient is invalid or does not exist. Check whether the UserID has been imported into the IM console.
    20004 Network exception. Try again later.
    20005 Internal server error. Try again later.
    20006 The callback prior to sending a one-to-one chat message was triggered, and the App backend returned a response to forbid the message.
    90001 Failed to parse the JSON format. Check whether the request packet meets JSON specifications.
    90002 The format of the MsgBody field in the JSON request packet is invalid or MsgBody is not an array. Refer to 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’s format is invalid. Refer to TIMMsgElement Object for more information.
    90012 Accounts in To_Account do not exist or have not been registered. Make sure the accounts are IM accounts and are correct.
    90026 The offline storage time of the message is incorrect. 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 service error. Please try again.
    90992 Internal service error. Please try again. If this error code is returned for all requests and the app has configured a 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 account does not exist.

    API Debugging Tool

    Use the online RESTful API 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)

    Possible Callbacks

    Was this page helpful?

    Was this page helpful?

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