Batch Sending One-to-One Messages

Last updated: 2020-05-22 15:16:20

PDF

Feature Description

  • This API can send one-to-one messages to up to 500 users at a time.
  • Compared with the one-to-one message API, this API is more suitable for time-sensitive messages, such as marketing messages and system notifications.
  • When the admin specifies an account to send messages to target accounts in batches, the recipients will see that the sender is not the admin but the account specified by the admin.
  • This API does not trigger callback requests.
  • This API does not check whether the sender and the recipient are friends (nor does it check the blacklist) or whether the recipient is muted.

When the server-end integrated RESTful API is used to send messages in batches, you can determine 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/batchsendmsg?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/batchsendmsg 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.

Admin sends messages to target accounts in batches

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": [ // List of target accounts
        "bonnie",
        "rong"
    ],
    "MsgRandom": 19901224, // Message random number
    "MsgBody": [ // Message
        {
            "MsgType": "TIMTextElem", // Message type. **TIMTextElem** indicates text messages.
            "MsgContent": {
                "Text": "hi, beauty" // Message text
            }
        }
    ]
}

Admin specifies an account to send messages to target accounts in batches and sets offline information push

From_Account is the sender specified by the admin. The recipients will see From_Account instead of the admin account. The following JSON request indicates that dave sends a message to the accounts bonnie and rong. When bonnie and rong receive the message, the message sender they see is dave.

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": 1, // Messages are synchronized to the sender.
    "From_Account": "dave",
    "To_Account": [
        "bonnie",
        "rong"
    ],
    "MsgRandom": 19901224,
    "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
        }
    }
}

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 Sender account specified by the admin for sending messages. (To set From_Account information, this parameter must be specified.)
To_Account Array Required UserID of a message recipient
MsgRandom Integer Required Message random number, which is generated by the random function and used to locate issues at the backend
MsgBody Object Required TIM message. For details, see Message Format Description.
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 TIM message object. For details, see Message Format Description.
OfflinePushInfo Object Optional Offline push information configuration. For details, see Message Format Description.

Sample response packets

  • Successful response packet

    {
      "ErrorInfo": "",
      "ActionStatus": "OK",
      "ErrorCode": 0,
      "MsgKey": "128493_903762_1572870301"
    }
  • Error response packet

    {
      "ActionStatus": "FAIL",
      "ErrorInfo": "",
      "ErrorList": [ // List of target accounts to which messages failed to be sent
          {
              "To_Account": "rong", // Target account
              "ErrorCode":  90011 // Error code
          }
      ]
    }

Response packet fields

Field Type Description
ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
ErrorList Array List of target accounts to which messages failed to be sent. If all messages are sent successfully, ErrorList is null. To determine whether all messages were sent successfully, check whether ErrorList is contained in the response packet.
To_Account String Accounts to which messages failed to be sent
ErrorCode Number Error code for a message sending failure
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
70107 The requested UserID does not exist.
70169 Server timed out. Try again later.
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.
90007 The MsgBody field in the JSON request packet is not of the Array type. Change the type of the MsgBody field to Array.
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.
90010 The JSON request packet does not meet message format requirements. For details, see the definition of TIMMsgElement Object.
90011 The number of target accounts for batch message sending exceeds 500. Please decrease the value of the To_Account field.
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.
90048 The requested UserID does not exist.
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.
91000 Internal server error. Please try again.
93000 The JSON packet exceeds the length limit of 8 KB.

API Debugging Tool

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

References