Batch Sending One-to-One Messages

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.

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

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

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:

API Debugging Tool

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

References

• Sending a one-to-one message (v4/openim/sendmsg)
• Sending common messages in a group (v4/group_open_http_svc/send_group_msg)
• Sending system notifications in a group (v4/group_open_http_svc/send_group_system_notification)
• Message Format Description