tencent cloud

Feedback

Pushing to All/Tagged Users

Last updated: 2025-01-21 15:20:56
    All-user/Tag Push supports sending specific content, and also allows for the delivery of personalized content to specific user groups based on Tag, attribute, such as Membership Activities, Regional Notifications, etc. It aids in User Acquisition, Conversion, Activation Promotion, and other operational work phases, while also supporting Push Delivery Reports, Self-service Push Troubleshooting Tool. For more details, please see Effect Display.
    Note:
    1. An account must have logged in or been manually imported to receive messages from All-staff/Tag Push.
    2. Universal Push Notification does not support Message Modification.

    Feature Overview

    Supports sending pushes to all users.
    Supports sending pushes based on user attributes.
    Supports sending pushes by user Tag.
    When an administrator pushes a message, the recipient sees the message sender as the administrator.
    When an administrator specifies an account to push messages to other accounts, the recipient sees the sender not as the administrator, but as the account specified by the administrator.
    Supports roaming, with the roaming storage duration consistent with that of regular message storage.
    Due to the large number of accounts that need to be issued for All-user/Tag Push, it takes some time to issue all accounts (depending on the total number of accounts).
    By setting the OnlineOnlyFlag to 1, push notifications can be sent without saving the session, roaming, and unread messages.

    API Calling Description

    Sample request URL

    https://xxxxxx/v4/timpush/push?usersig=xxx&identifier=admin&sdkappid=88888888&random=99999999&contenttype=json

    Request parameters

    Parameter
    Description
    https
    Request protocol: HTTPS
    Request method: POST
    xxxxxx
    The dedicated domain corresponding to the country/region of your SDKAppID.
    China: 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
    v4/timpush/push
    Request API
    usersig
    The Signature generated by the App admin account. For details, see Generating UserSig
    identifier
    You must be an App admin account. For more details, see App Admins
    sdkappid
    SdkAppid assigned by the Chat console when creating an app
    random
    32-bit unsigned integer random number
    contenttype
    Fixed value: json

    Call frequency limit

    This API includes all-user, attribute, and Tag Push. By default, it can be invoked up to 100 times per day, with an interval of more than 1 second between each push.
    Note:
    API Frequency Limit. By default, you can make 100 free calls per day. Each additional call will cost an extra $10 per day. If you need to adjust the API frequency, please go to the IM Console.

    Sample request packets

    Mass Push Example

    Administrator conducts a mass push:
    {
    "From_Account": "admin",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }
    Administrator directs a specific account to conduct a mass push (in the example, the sender's account is xiaoming):
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }
    Note:
    From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
    Only push to online users (Online Push):
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 1, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 1 // 0 means offline push enabled, 1 means offline push disabled
    }
    }
    Note:
    OnlineOnlyFlag set to 1 indicates push operations for both online and offline users, but OfflinePushInfo.PushFlag set to 1 means there will be no offline push. Therefore, the above example signifies that only online users will be pushed to.

    Push by User Tag Example

    The administrator pushes messages to users tagged with both "Stock A" and "Stock B":
    {
    "From_Account": "admin",
    "MsgRandom": 124032,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "Condition": {
    "TagsAnd": ["Stock A","Stock B"]
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }
    Note:
    From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
    The administrator pushes messages to users following either "Stock A" or "Stock B":
    {
    "From_Account": "admin",
    "MsgRandom": 124032,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "Condition": {
    "TagsOr": ["Stock A","Stock B"]
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }

    User Attribute Push

    The administrator sends messages to Super Platinum members in Shenzhen:
    {
    "From_Account": "admin",
    "MsgRandom": 389475,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "Condition": {
    "AttrsAnd": {
    "Membership Level": "Super Platinum Member",
    "city": " Shenzhen "
    }
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }
    Note:
    From_Account is the message sender account, which supports specifying any existing account. If the sender is not specified or does not exist, the API caller account will be used by default.
    The administrator sends messages to Shenzhen users or Super Platinum members:
    {
    "From_Account": "admin",
    "MsgRandom": 389475,
    "OnlineOnlyFlag": 0, // 0 means storing roaming and unread messages with a push concurrency limit of 200 users/second; 1 means not storing roaming and unread messages
    "Condition": {
    "AttrsOr": {
    "Membership Level": "Super Platinum User",
    "city": " Shenzhen "
    }
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0 means offline push enabled, 1 means offline push disabled
    "Title": "Offline Push Title",
    "Desc": "Offline Push Content"
    }
    }

    Request packet fields

    Field
    Type
    Attribute
    Description
    From_Account
    String
    Optional
    Message Sender Account (supports specifying any existing account)
    Note:
    If the sender is not specified or the specified sender does not exist, the account of the API caller is used by default.
    MsgRandom
    Integer
    Required
    Message Random Number (32-bit unsigned integer), used by the backend for deduplication of messages within the same second. Please ensure this field is filled randomly
    OnlineOnlyFlag
    Integer
    Optional
    The default is 0, indicating storing roaming and unread messages with a push concurrency limit of 200 people/second.
    1 indicates not storing history messages and not counting unread messages
    Note:
    If you need to adjust the push concurrency limit, please contact Tencent Cloud customer service or business staff.
    Condition
    Object
    Optional
    Condition has 4 types, which are:
    Attribute's "Or condition" AttrsOr
    Attribute's "And condition" AttrsAnd
    Tag's "Or condition" TagsOr
    Tag's "And condition" TagsAnd
    Note:
    AttrsOr, AttrsAnd, TagsOr, TagsAnd cannot coexist. If there is no Condition, it will be pushed to all users.
    TagsOr
    Array
    Optional
    The union of Tag conditions. A Tag is a string that does not exceed 50 bytes.
    Note:
    Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. The number of Tags in TagsOr condition cannot exceed 10.
    TagsAnd
    Array
    Optional
    The intersection of Tag conditions. A Tag is a string that does not exceed 50 bytes.
    Note:
    Attribute pushing and Tag pushing cannot both be used as push conditions at the same time. The number of Tags in TagsAnd condition cannot exceed 10.
    AttrsOr
    Object
    Optional
    The union of Attribute conditions.
    Note:
    Attribute pushing and Tag pushing cannot both be used as push conditions at the same time.
    AttrsAnd
    Object
    Optional
    The intersection of Attribute conditions.
    Note:
    Attribute pushing and Tag pushing cannot both be used as push conditions at the same time.
    MsgBody
    Array
    Required
    Message content, please refer to MsgBody Message Content Description (a message can include multiple message elements, so MsgBody is of Array type)
    MsgType
    String
    Required
    TIM message object types currently supported include:
    TIMTextElem (Text message)
    TIMLocationElem (Location message)
    TIMFaceElem (Expression message)
    TIMCustomElem(Custom message)
    TIMSoundElem( VMS )
    TIMImageElem(Image message)
    TIMFileElem(File message)
    TIMVideoFileElem(Video message)
    MsgContent
    Object
    Required
    For each MsgType, use different MsgContent formats, please refer to TIMMsgElement object's Definition
    OfflinePushInfo
    Object
    Optional
    Offline Push Notification Configuration. For details, please refer to the OfflinePushInfo Description

    Sample response packets

    {
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "TaskId": "667015d4_537529d8_2000005e80aa873_d03ac87_56f5e750"
    }

    Response packet field description

    Field
    Type
    Description
    ActionStatus
    String
    Processed Request Result:
    OK: Indicates successful processing
    FAIL: Indicates failure
    ErrorCode
    Integer
    Error code
    ErrorInfo
    String
    Error message
    TaskId
    String
    Push task ID

    Error codes

    Unless a network error occurs (e.g., a 502 error), the HTTP status code for this interface will always be 200.The real error codes and messages are indicated in the response body by ErrorCode and ErrorInfo. For common error codes (60000 to 79999), see the Error Code document.
    Private error codes for this API are as follows:
    Error code
    Description
    90001
    Failed to parse the JSON format. Please ensure the request packet conforms to the JSON specification.
    90002
    The MsgBody in the JSON format request packet does not match the message format description, or MsgBody is not of Array type. Please refer to the Definition of TIMMsgElement Object.
    90005
    The JSON format request packet body is missing the MsgRandom field or the MsgRandom field is not of Integer type.
    90007
    The MsgBody type in the JSON format request packet body is not of Array type. Please change it to Array type.
    90009
    The request requires App Administrator permissions.
    90010
    The JSON format request packet does not conform to the message format description. Please refer to the Definition of TIMMsgElement Object.
    90020
    Tag length exceeds the limit (cannot exceed 50 bytes).
    90022
    There are duplicate Tags in the TagsOr and TagsAnd conditions of the push.
    90024
    Pushes are too frequent; the interval between two pushes must be more than 1 second.
    90026
    Error in offline message storage time.
    90032
    The number of tags in the push conditions exceeds 10, or the number of Tags in the add Tag request exceeds 10.
    90033
    Attribute is invalid.
    90039
    Push by Attribute and Push by Tag cannot coexist.
    90040
    One of the tags in the Push Conditions is empty.
    90045
    All-staff/Tag Push feature is not activated.
    90047
    Push Attempts exceed the Daily Limit (default is 100 times).
    90056
    Request body for all-staff push is too large, currently supports a maximum length of 10K.
    91,000
    Internal service error, please try again.

    API Debugging Tool

    Use the RESTful API Online Test tool to debug this interface.

    Reference

    
    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