Pushing to All Users

Last updated: 2020-08-28 18:41:18

    Feature Description

    • This API can push messages to all users.
    • This API can push messages by user attribute.
    • This API can push messages by user tag.
    • When the admin pushes messages, the message sender displayed to the recipients is the admin.
    • When the admin specifies an account to push messages to other accounts, the sender displayed to the recipients is not the admin but the account specified by the admin.
    • This API supports offline storage of messages, but does not support message roaming.
    • It takes time to push messages to all users. The actually required time depends on the number of accounts. Typically, it is within 1 minute.

    Call Description

    Only users with Ultimate Edition accounts can apply for this feature. You can submit a ticket to apply for this feature. If we determine that this feature suits your needs, we will approve your application.

    Sample request URL

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

    Request parameters

    Parameter Description
    https The request protocol is HTTPS, and the request method is POST.
    console.tim.qq.com The fixed domain name.
    v4/all_member_push/im_push The request API.
    usersig The signature generated by the app admin account. For more information, see Generating UserSig.
    identifier The value must be the app admin account.
    sdkappid The SDKAppID assigned by the IM console when an app is created.
    random A random 32-bit unsigned integer.
    contenttype The value is fixed to json.

    Call frequency

    This API supports message push to all users, by user attribute, and by user tag. By default, it can be called up to 100 times every day, and the interval between pushed messages must be greater than 1 second. If you have special frequency requirements, such as requiring an unlimited number of calls, note your requirements in the ticket.

    Sample request packet

    • Pushing messages to all users
      The admin pushes a message to all users.
      {
        "From_Account": "admin",
        "MsgRandom": 56512,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin specifies an account to push a message to all users. In this example, the sender account is xiaoming.
      {
        "From_Account": "xiaoming",
        "MsgRandom": 3674128,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin specifies an account to push a message to all users and configures offline push information.
      {
        "From_Account": "xiaoming",
        "MsgRandom": 3674128,
        "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 pushes a message to all users and retains the messages offline for 120 seconds.
      {
        "From_Account": "admin",
        "MsgRandom": 21302570,
        "MsgLifeTime": 120,
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
    • Pushing messages by user tag
      The admin pushes a message to users tagged with "A shares" and "B shares".
      {
        "From_Account": "admin",
        "MsgRandom": 214,
        "Condition": {
            "TagsAnd": ["A shares","B shares"]
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin pushe a message to users tagged with "A shares" and "B shares".
      {
        "From_Account": "admin",
        "MsgRandom": 103698523,
        "Condition": {
            "TagsOr": ["A shares","B shares"]
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin pushes a message to users tagged with "A shares" and "B shares" and retains the message offline for 120 seconds.
      {
        "From_Account": "admin",
        "MsgRandom": 124032,
        "MsgLifeTime": 120,
        "Condition": {
            "TagsOr": ["A shares","B shares"]
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
    • Pushing messages by user attribute
      The admin pushes a message to Platinum users in the Shenzhen region.
      {
        "From_Account": "admin",
        "MsgRandom": 389475,
        "Condition": {
            "AttrsAnd": {
                "Membership level": "Platinum",
                "city": "Shenzhen"
            }
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin pushes a message to users in the Shenzhen region or male users.
      {
        "From_Account": "admin",
        "MsgRandom": 9657,
        "Condition": {
            "AttrsOr": {
                "sex": "Male",
                "city": "Shenzhen"
            }
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }
      The admin pushes a message to Platinum users in the Shenzhen region and retains the message offline for 120 seconds.
      {
        "From_Account": "admin",
        "MsgRandom": 9312457,
        "MsgLifeTime": 120,
        "Condition": {
            "AttrsAnd": {
                "Membership level": "Platinum",
                "city": "Shenzhen"
            }
        },
        "MsgBody": [
            {
                "MsgType": "TIMTextElem",
                "MsgContent": {
                    "Text": "hi, beauty"
                }
            }
        ]
      }

    Request packet fields

    Field Type Required Description
    Condition Object No Valid values:
    • AttrsOr
    • AttrsAnd
    • TagsOr
    • TagsAnd
    AttrsOr and AttrsAnd can coexist, and TagsOr and TagsAnd can coexist. However, tag conditions and attribute conditions cannot coexist. If no condition is specified, the message is pushed to all users.
    MsgRandom Integer Yes The message’s random number, which is generated by the random function and used to deduplicate push tasks. Push requests must have unique random numbers within a seven-day period. Otherwise, they are regarded as the same push task. If an error is returned when you call the push API, you can use the same message random number for a retry.
    MsgBody Object Yes The message body. For more information on the message format, see Message Format Description. Note that MsgBody is an array that can contain multiple message elements.
    MsgType String Yes The TIM message object type. Valid values:
    • TIMTextElem (text message)
    • TIMFaceElem (emoji message)
    • TIMLocationElem (location message)
    • TIMCustomElem (custom message)
    MsgContent Object Yes Message types have different MsgContent formats. For more information, see Message Format Description.
    MsgLifeTime Integer No The offline message storage duration in seconds. Maximum value: 604800 seconds (7 days). Default value: 0, which indicates that the message is not stored offline.
    From_Account String No The account of the message sender.
    AttrsOr Object No A set of ORed attribute conditions. Note that attribute conditions and tag conditions cannot be used at the same time.
    AttrsAnd Object No A set of ANDed attribute conditions. Note that attribute conditions and tag conditions cannot be used at the same time.
    TagsOr Object No A set of ORed tag conditions. A tag is a string with a maximum length of 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The number of tags in TagsOr cannot exceed 10.
    TagsAnd Object No A set of ANDed tag conditions. A tag is a string with a maximum length of 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The number of tags in TagsAnd cannot exceed 10.
    OfflinePushInfo Object No The message to be pushed offline. For more information, see Message Format Description.

    Sample response packet

    {
        "ActionStatus":"OK",
        "ErrorInfo":"",
        "ErrorCode": 0,
        "TaskId": "1400123456_144115212910570789_4155518400_15723514"
    }

    Response packet fields

    Field Type Description
    ActionStatus String The request processing result. Valid values: OK for succeeded, and FAIL for failure.
    errorCode Integer The error code.
    ErrorInfo String The error information.
    taskID String The push task ID.

    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, respectively. For public error codes 60000 to 79999, see Error Codes.
    The following table describes the error codes specific to this API.

    Error Code Description
    90001 Failed to parse the JSON request packet. To correct it, ensure that the format of the request is valid.
    90002 The format of the MsgBody field in the JSON request packet was invalid, or MsgBody was not an array. For more information, see Message Format Description.
    90005 The MsgRandom field was missing in the JSON request packet, or MsgRandom was not an integer.
    90007 The MsgBody field in the JSON request packet was not an array.
    90009 The request required app admin permissions.
    90010 The request format is invalid. Fore more information, see Message Format Description.
    90020 The length of the tag exceeded the limit of 50 bytes.
    90022 TagsOr and TagsAnd contained duplicate tags.
    90024 Message push attempts were too frequent. The interval between message push attempts must be greater than 1 second.
    90026 The offline message storage period was invalid. The period cannot exceed 7 days.
    90032 The number of tags in the push condition exceeded 10, or the number of tags in the tag addition request exceeded 10.
    90039 Message push by attribute and message push by tag occurred concurrently. Both push attempts must be mutually exclusive.
    90040 A tag in the push condition was empty.
    90045 Message push to all users was not enabled.
    90047 The number of push attempts exceeded the limit of 100 times per day.
    91000 An internal service error occurred. To correct it, try again.

    Debugging Tool

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

    References

    Was this page helpful?

    Was this page helpful?

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