tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Chat
    Documentation
    Download PDF

    Pushing to All Users

    Last updated: 2024-02-07 17:11:43
    Download PDF
      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
      India: adminapiind.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

      API for Pushing to All Users
      Setting Application Attribute Names
      Getting Application Attribute Names
      Setting User Attributes
      Deleting User Attributes
      Getting User Attributes
      Adding User Tags
      Getting User Tags
      Deleting User Tags
      Deleting All Tags of a User
      Contact Us

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

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy