tencent cloud

Feedback

Pushing to All Users

Last updated: 2024-07-16 10:41:26
    Pushing to all users is an excellent tool for application user operations. It not only supports sending specific content to all users, but also can send personalized content to specific user groups based on tags and attributes, such as member events, and regional notifications. This helps effectively attract, convert, and activate new users.

    Feature Overview

    This API can be used to push messages to all users.
    This API can be used to push messages by user attribute.
    This API can be used to 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 not message roaming.
    It takes time to push messages to all users. The required time depends on the number of accounts. Typically, it is within one minute.
    This API allows you to push messages only to online users by setting the MsgLifeTime parameter to 0.
    Note:
    The "pushing to all users" feature is only available on the IM Ultimate edition. To use it, purchase the Ultimate edition. For more information, see Pricing.

    API Call Description

    The feature of pushing to all users is available only to users with Ultimate edition accounts. See Configuration Change Ticket to apply for this feature. The feature will be enabled 48 hours after your application is approved.

    Sample request URL

    https://xxxxxx/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.
    xxxxxx
    Domain name corresponding to the country/region where your SDKAppID is located.
    Chinese mainland: console.tim.qq.com
    Singapore: adminapisgp.im.qcloud.com
    Seoul: adminapikr.im.qcloud.com
    Frankfurt: adminapiger.im.qcloud.com
    Silicon Valley: adminapiusa.im.qcloud.com
    Jakarta: adminapiidn.im.qcloud.com
    v4/all_member_push/im_push
    Request API
    usersig
    Signature generated in the app admin account. For more information, see Generating UserSig.
    identifier
    The app administration 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 always json.

    Calling frequency

    This API includes pushing to all and by attribute and tag. By default, it can be called 100 times every day. The interval between two pushes must be greater than one second.

    Sample request

    Pushing messages to all users The admin pushes messages to all users and retains the messages offline for 120 seconds.
    {
    "From_Account": "admin",
    "MsgRandom": 56512,
    "MsgLifeTime": 120,
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }
    The admin specifies an account for pushing to all users and retains the messages offline for 120 seconds. In the sample, the sender account is xiaoming:
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "MsgLifeTime": 120,
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }
    The admin specifies an account for pushing to all users, sets offline push information, and retains the messages offline for 120 seconds.
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "MsgLifeTime": 120,
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0,
    "Desc": "Content to push offline",
    "Ext": "Passthrough content",
    "AndroidInfo": {
    "Sound": "android.mp3"
    },
    "ApnsInfo": {
    "Sound": "apns.mp3",
    "BadgeMode": 1, // If this field is left as default or is set to `0`, the message is counted. If this field is set to `1`, the message is not counted, that is, the badge counter in the upper-right corner does not increase.
    "Title":"apns title", // APNs title
    "SubTitle":"apns subtitle", // APNs subtitle
    "Image":"www.image.com" // Image URL
    }
    }
    }
    The admin pushes messages 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 messages to users tagged with "Stock A" and "Stock B" and retains the messages offline for 120 seconds.
    {
    "From_Account": "admin",
    "MsgRandom": 214,
    "MsgLifeTime": 120,
    "Condition":{
    "TagsAnd": ["Stock A","Stock B"]
    },
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }
    The admin pushes messages to users tagged with "Stock A" and "Stock B" and retains the messages offline for 120 seconds.
    {
    "From_Account": "admin",
    "MsgRandom": 124032,
    "MsgLifeTime": 120,
    "Condition":{
    "TagsOr": ["Stock A","Stock B"]
    },
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }
    Pushing messages by user attribute The admin pushes messages to Shenzhen Platinum Premier users and retains the messages offline for 120 seconds.
    {
    "From_Account": "admin",
    "MsgRandom": 389475,
    "MsgLifeTime": 120,
    "Condition":{
    "AttrsAnd": {
    "Membership Level": "Platinum Premier members",
    "city": "Shenzhen"
    }
    },
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }
    The admin pushes messages to Shenzhen Platinum Premier users and retains the messages offline for 120 seconds.
    {
    "From_Account": "admin",
    "MsgRandom": 9312457,
    "MsgLifeTime": 120,
    "Condition":{
    "AttrsAnd": {
    "Membership Level": "Platinum Premier users",
    "city": "Shenzhen"
    }
    },
    "MsgBody":[
    {
    "MsgType": "TIMTextElem",
    "MsgContent":{
    "Text": "hi, beauty"
    }
    }
    ]
    }

    Request fields

    Field
    Type
    Attribute
    Description
    Condition
    Object
    Optional
    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, messages are pushed to all users.
    MsgRandom
    Integer
    Required
    Random number (32-bit unsigned integer) of the message. It is used by the backend for message deduplication within a second. Make sure a random number is entered.
    MsgBody
    Array
    Required
    Message body. For more information on the message format, see Message Formats. Note that MsgBody is an array that can contain multiple message elements.
    MsgType
    String
    Required
    TIM message object type. Valid values:
    TIMTextElem (text message)
    TIMLocationElem (location message)
    TIMFaceElem (emoji message)
    TIMCustomElem (custom message)
    TIMSoundElem (voice message)
    TIMImageElem (image message)
    TIMFileElem (file message)
    TIMVideoFileElem (video message)
    MsgContent
    Object
    Required
    Different message object types (MsgType) have different formats (MsgContent). For more information, see the Message Element TIMMsgElement section in Message Formats.
    MsgLifeTime
    Integer
    Optional
    Offline message storage duration, in seconds. The maximum duration is 604,800 seconds (7 days). The default value is 0, which indicates that messages are not stored offline and will be pushed only to online users.
    From_Account
    String
    Optional
    Account of the message sender
    AttrsOr
    Object
    Optional
    A set of attribute conditions connected by OR. Note that attribute conditions and tag conditions cannot be used at the same time.
    AttrsAnd
    Object
    Optional
    A set of attribute conditions connected by AND. Note that attribute conditions and tag conditions cannot be used at the same time.
    TagsOr
    Array
    Optional
    Union of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The TagsOr condition can contain up to ten tags.
    TagsAnd
    Array
    Optional
    Intersection of tag conditions. A tag is a string of up to 50 bytes. Note that attribute conditions and tag conditions cannot be used at the same time. The TagsAnd condition can contain up to ten tags.
    OfflinePushInfo
    Object
    Optional
    The information to be pushed offline. For more information, see Message Formats.

    Sample response

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

    Response fields

    Field
    Type
    Description
    ActionStatus
    String
    Request result. OK: Successful; FAIL: Failed
    ErrorCode
    Integer
    Error code
    ErrorInfo
    String
    Error message
    TaskId
    String
    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 represent the actual error code and error message. 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 format. Check whether the JSON request meets JSON specifications.
    90002
    The MsgBody field in the JSON request does not meet message format requirements or it is not an array. For more information, see the Message Element TIMMsgElement section in Message Formats.
    90005
    The MsgRandom field is missing in the JSON request or it is not an integer.
    90007
    The MsgBody field in the JSON request is not an array. Change it to an array.
    90009
    The request requires app admin permissions.
    90010
    The JSON request does not meet message format requirements. For more information, see the Message Element TIMMsgElement section in Message Formats.
    90020
    The tag length exceeds the limit (the maximum length allowed is 50 bytes).
    90022
    TagsOr and TagsAnd in the push conditions contain repeated tags.
    90024
    Pushes are too frequent. The interval between two pushes must be greater than 1 second.
    90026
    Incorrect offline message storage period. The value cannot exceed 7 days.
    90032
    The number of tags in the push conditions exceeds 10, or the number of tags in the tag adding request exceeds 10.
    90033
    Invalid attribute.
    90039
    Message push by attribute and message push by tag are mutually exclusive.
    90040
    A tag in the push conditions is null.
    90045
    The feature of pushing to all users is not enabled.
    90047
    The number of pushes exceeds the daily quota (default quota: 100).
    91000
    Internal service error. Try again.

    API Debugging Tool

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

    References

    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support