tencent cloud

Feedback

Pushing to All/Tagged Users

Last updated: 2024-07-23 17:57:52
    Pushing to all/tagged users 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. It also supports pushing delivery reports and self-service troubleshooting tools. Refer to Feature Overview for the effect.
    Note:
    The account must have been logged in or manually imported before it can receive push messages.

    Feature Overview

    Supports sending push messages to all users.
    Supports sending push messages based on user attributes.
    Supports sending push messages based on user tags.
    The administrator pushes a message, and the recipient sees that the sender of the message is the administrator.
    The administrator specifies an account to push a message to other accounts, and the recipient sees that the sender is not the administrator, but the account specified by the administrator.
    Supports roaming, with the same storage duration as regular messages.
    Due to the large number of accounts that need to be delivered for pushing to all/tagged users, it takes a certain amount of time (depending on the total number of accounts) to complete the delivery of all accounts.
    By setting OnlineOnlyFlag to 1, push messages can only be sent without saving sessions, roaming, and unread messages.

    API Call Description

    Sample Request URL

    https://xxxxxx/v4/timpush/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
    The dedicated domain name corresponding to the country/region of the 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
    Jakarta: adminapiidn.im.qcloud.com
    v4/timpush/push
    Request API.
    usersig
    The signature generated by the app admin account. For details, see Generating UserSig.
    identifier
    The app admin account.
    sdkappid
    The SDKAppID assigned by the Chat console when an application is created.
    random
    A random 32-bit unsigned integer.
    contenttype
    The value is always json.

    Call Frequency

    This API includes pushing to all users and pushing to users by attribute or tag. By default, it can be called 100 times per day. The interval between two pushes must be greater than 1 second.
    Note:
    By default, the API can be called 100 times per day for free. For each additional call per day, the cost will increase by 10 USD per day. If you need to adjust the frequency of API calls, go to the Chat console to modify it.

    Sample Request Packets

    Pushing Messages to All Users The administrator pushes messages to all users:
    {
    "From_Account": "admin",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }
    The administrator specifies an account for pushing messages to all users. In the example, the sender account is xiaoming:
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }
    Note:
    From_Account is the message sender account and can be specified as any existing account. If no sender is specified or the specified sender does not exist, the API caller account will be taken by default.
    The administrator pushes messages only to online users (online push):
    {
    "From_Account": "xiaoming",
    "MsgRandom": 3674128,
    "OnlineOnlyFlag": 1, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 1, // 0: Enables offline push; 1: Disables offline push.
    }
    }
    Note:
    Setting OnlineOnlyFlag to 1 indicates only push (online push+offline push). Setting OfflinePushInfo.PushFlag to 1 indicates no offline push. Therefore, the above example indicates that messages are pushed only to online users.
    Pushing Messages by User Tag The administrator pushes messages to users tagged with "Stock A" and "Stock B":
    {
    "From_Account": "admin",
    "MsgRandom": 124032,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "Condition": {
    "TagsAnd": ["Stock A","Stock B"]
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }
    The administrator pushes messages to users tagged with "Stock A" or "Stock B":
    {
    "From_Account": "admin",
    "MsgRandom": 124032,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "Condition": {
    "TagsOr": ["Stock A","Stock B"]
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }
    Pushing Messages by User Attribute The administrator pushes messages to Platinum Premier membership in Shenzhen:
    {
    "From_Account": "admin",
    "MsgRandom": 389475,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "Condition": {
    "AttrsAnd": {
    "level": "Platinum Premier Membership",
    "city": "Shenzhen"
    }
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }
    Note:
    From_Account is the message sender account and can be specified as any existing account. If no sender is specified or the specified sender does not exist, the API caller account will be taken by default.
    The administrator pushes messages to Platinum Premier users in Shenzhen:
    {
    "From_Account": "admin",
    "MsgRandom": 389475,
    "OnlineOnlyFlag": 0, // 0: Saves roaming and unread messages. In this case, the push concurrency limit is 200 users/second;
    // 1: Does not save roaming or unread messages. In this case, there is no push concurrency limit.
    "Condition": {
    "AttrsAnd": {
    "level": "Platinum Premier Users",
    "city": "Shenzhen"
    }
    },
    "MsgBody": [
    {
    "MsgType": "TIMTextElem",
    "MsgContent": {
    "Text": "hi, beauty"
    }
    }
    ],
    "OfflinePushInfo": {
    "PushFlag": 0, // 0: Enables offline push; 1: Disables offline push.
    "Title": "offline push title",
    "Desc": "offline push content"
    }
    }

    Request Fields

    Field
    Type
    Required
    Description
    From_Account
    String
    No
    Account of the message sender, which can be specified as any existing account.
    Note: If no sender is specified or the specified sender does not exist, the API caller account will be taken by default.
    MsgRandom
    Integer
    Yes
    A random number (32-bit unsigned integer) of the message. It is used by the backend for message deduplication within the same second. Make sure a random number is entered.
    OnlineOnlyFlag
    Integer
    No
    The default value is 0, which means to save roaming and unread messages. In this case, the push concurrency limit is 200 users/second.
    1 means not to save historical messages and not to count unread messages. In this case, there is no push concurrency limit.
    Condition
    Object
    No
    Valid values:
    The or condition of attributes: AttrsOr
    The and condition of attributes: AttrsAnd
    The or condition of tags: TagsOr
    The and condition of tags: TagsAnd
    Note: AttrsOr, AttrsAnd, TagsOr, and TagsAnd cannot coexist. If no condition is specified, messages are pushed to all users.
    TagsOr
    Array
    No
    The union of tag conditions. A tag is a string of up to 50 bytes.
    Note: Attributes and tags cannot be used as push conditions at the same time. The TagsOr condition can contain up to 10 tags.
    TagsAnd
    Array
    No
    The intersection of tag conditions. A tag is a string of up to 50 bytes.
    Note: Attributes and tags cannot be used as push conditions at the same time. The TagsAnd condition can contain up to 10 tags.
    AttrsOr
    Object
    No
    The union of attribute conditions.
    AttrsAnd
    Object
    No
    The intersection of attribute conditions.
    MsgBody
    Array
    Yes
    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
    Yes
    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
    Yes
    Different message object types (MsgType) have different formats (MsgContent). For more information, see the TIMMsgElement section in Message Formats.
    OfflinePushInfo
    Object
    No
    The information to be pushed offline. For more information, see Message Formats.

    Sample Response Packets

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

    Response Fields

    Field
    Type
    Description
    ActionStatus
    String
    Processing result. OK: succeeded. FAIL: failed.
    ErrorCode
    Integer
    Error code.
    ErrorInfo
    String
    Error information.
    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 packets represent the actual error code and error information. For common 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 request packets meet JSON specifications.
    90002
    The MsgBody field in the JSON request packets does not meet message format requirements or it is not an array. For more information, see the TIMMsgElement section in Message Formats.
    90005
    The MsgRandom field is missing in the JSON request packets or it is not an integer.
    90007
    The MsgBody field in the JSON request packets is not an array. Change it to an array.
    90009
    The request requires app admin permissions.
    90010
    The JSON request packets do not meet message format requirements. For more information, see the 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/tagged 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