Sending Ordinary Messages in a Group

Last updated: 2020-03-11 17:31:32

PDF

Feature Description

Through this API, the app admin can send common messages in a group.

API Invocation Description

Applicable group types

Group Type Support This RESTful API
Private Yes
Public Yes
ChatRoom Yes
AVChatRoom Yes
BChatRoom Yes

IM provides the preceding five built-in group types. For details, see Group Systems.

Request URL example

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

Request parameters

The following table lists and describes only the parameters to be modified when this API is invoked. For details on other parameters, see RESTful API Overview.

Parameter Description
v4/group_open_http_svc/send_group_msg The request API.
sdkappid The SDKAppID assigned by the IM console when an app is created.
identifier This must be the app admin account. For details, see App Admins.
usersig The signature generated by the app admin account. For details, see Generating UserSig.
random Enter a random 32-bit unsigned integer ranging from 0 to 4294967295.

Maximum invocation frequency

The maximum invocation frequency is 200 times per second.

Request packet examples

  • Basic form
    The app admin sends common group messages.
    {
      "GroupId": "@TGS#2C5SZEAEF",
      "Random": 8912345, // The random number. If the random numbers of two messages sent within five minutes are the same, both messages are considered to be identical.
      "MsgBody": [ // The message body, which consists of an element array. For details, see field description below.
          {
              "MsgType": "TIMTextElem", // Text
              "MsgContent": {
                  "Text": "red packet"
              }
          },
          {
              "MsgType": "TIMFaceElem", // Emoji
              "MsgContent": {
                  "Index": 6,
                  "Data": "abc\u0000\u0001"
              }
          }
      ],
      "OfflinePushInfo": {
          "PushFlag": 0, // Normal push
          "Desc": "Offline push content",
          "Ext": "This is the passthrough content",
          "AndroidInfo": {
              "Sound": "android.mp3"
          },
          "ApnsInfo": {
              "Sound": "apns.mp3",
              "BadgeMode": 1, // The default 0 value indicates that the message is counted. The 1 value indicates that the message is not counted, that is, the number in the upper-right corner of the icon does not increment.
              "Title":"apns title", // apns title
              "SubTitle":"apns subtitle", // apns subtitle
              "Image":"www.image.com" // image url
          }
      }
    }
  • Specifying the message sender
    The app admin can specify a group member as the message sender in From_Account.
    After receiving the message, other members will find that the message is sent from the group member specified by the app admin.
    {
      "GroupId": "@TGS#2C5SZEAEF",
      "From_Account": "leckie", // The message sender (optional).
      "Random": 8912345, // The random number. If the random numbers of two messages sent within five minutes are the same, both messages are considered to be identical.
      "MsgBody": [ // The message body, which consists of an element array. For details, see field description below.
          {
              "MsgType": "TIMTextElem", // Text
              "MsgContent": {
                  "Text": "red packet"
              }
          },
          {
              "MsgType": "TIMFaceElem", // Emoji
              "MsgContent": {
                  "Index": 6,
                  "Data": "abc\u0000\u0001"
              }
          }
      ]
    }
  • Specifying the message priority
    You can specify the message priority, which defaults to Normal.
    There are four priorities, which are the following in descending order: High, Normal, Low, and Lowest. Note that these priorities are case-sensitive.
    {
      "GroupId": "@TGS#2C5SZEAEF",
      "Random": 8912345, // The random number. If the random numbers of two messages sent within five minutes are the same, both messages are considered to be identical.
      "MsgPriority": "High", // The message priority.
      "MsgBody": [ // The message body, which consists of an element array. For details, see field description below.
          {
              "MsgType": "TIMTextElem", // Text
              "MsgContent": {
                  "Text": "red packet"
              }
          },
          {
              "MsgType": "TIMFaceElem", // Emoji
              "MsgContent": {
                  "Index": 6,
                  "Data": "abc\u0000\u0001"
              }
          }
      ]
    }
  • Forbidding callback for a specified message
    When callback is on, users can specify ForbidCallbackControl to control whether to initiate callback for a single message. By default, callback is on.
    {
      "GroupId": "@TGS#2C5SZEAEF",
      "Random": 8912345, // The random number. If the random numbers of two messages sent within five minutes are the same, both messages are considered to be identical.
      "ForbidCallbackControl":[
              "ForbidBeforeSendMsgCallback",
              "ForbidAfterSendMsgCallback"], // The callback forbidding control option.
      "MsgBody": [ // The message body, which consists of an element array. For details, see field description below.
          {
              "MsgType": "TIMTextElem", // Text
              "MsgContent": {
                  "Text": "red packet"
              }
          },
          {
              "MsgType": "TIMFaceElem", // Emoji
              "MsgContent": {
                  "Index": 6,
                  "Data": "abc\u0000\u0001"
              }
          }
      ]
    }
  • Forbidding offline storage and roaming for a specified message
    If OnlineOnlyFlag in the message body is set to a value greater than 0, the message will only be delivered online but not stored offline or roamed. Note that this feature is unavailable for AVChatRoom and BChatRoom groups.
      {
          "GroupId": "@TGS#2C5SZEAEF",
          "Random": 8912345, // The random number. If the random numbers of two messages sent within five minutes are the same, both messages are considered to be identical.
          "OnlineOnlyFlag": 1, // Indicates that the message is to be delivered online only (only online group members will receive the message) but not stored offline or roamed.
          "MsgBody": [ // The message body, which consists of an element array. For details, see field description below.
              {
                  "MsgType": "TIMTextElem", // Text
                  "MsgContent": {
                      "Text": "red packet"
                  }
              },
              {
                  "MsgType": "TIMFaceElem", // Emoji
                  "MsgContent": {
                      "Index": 6,
                      "Data": "abc\u0000\u0001"
                  }
              }
          ]
      }

Request packet fields

Field Type Attribute Description
GroupId String Required The ID of the group to which a message will be sent.
Random Integer Required A 32-bit random number. If the random numbers of two messages sent within five minutes are the same, the later message will be discarded as a repeated message.
MsgPriority String Optional The message priority.
MsgBody Array Required The message body. For details, see Message Format Description.
From_Account String Optional The message source account (optional). If this field is not specified, the message sender is the app admin account that is used to invoke the API by default. Alternatively, apps can specify the message sender in this field to implement certain special features. Note that if this field is specified, you must ensure that the account specified in this field exists.
OfflinePushInfo Object Optional Offline push information. For details, see Message Format Description.
ForbidCallbackControl Array Optional The toggle for forbidding message callback, which is valid only for a single message. ForbidBeforeSendMsgCallback indicates that callback before sending messages is forbidden, and ForbidAfterSendMsgCallback indicates that callback after sending messages is forbidden.
OnlineOnlyFlag Integer Optional 1: the message will be sent to online members only. 0 (default): the message will be sent to all members. AVChatRoom and BChatRoom groups do not support this parameter.

Response packet example

{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "MsgTime": 1497249503,
    "MsgSeq": 1
}

Response packet fields

Field Type Description
ActionStatus String The request processing result. OK: succeeded. FAIL: failed.
ErrorCode Integer The error code. 0: succeeded. Others: failed.
ErrorInfo String Error information.
MsgTime Integer The message sending timestamp corresponding to the backend server time.
MsgSeq Integer The message sequence number for uniquely identifying a message.

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

Error Code Description
10002 An internal server error occurred. In this case, try again.
10004 A parameter is invalid. In this case, check whether request parameters are correct based on the error description.
10007 Operation permissions are insufficient. For example, an ordinary member in a public group attempts to remove a member from the group, but only the app admin has the permission to do so.
10010 The group does not exist or has been dismissed.
10015 The group ID is invalid. In this case, check whether the group ID is correct.
10016 The app backend rejects this operation through a third-party callback.
10017 The message cannot be sent because the sender is muted. In this case, check whether the sender is muted.
10023 The message sending frequency exceeds the limit. In this case, increase the interval between message sending attempts.
80001 The message fails the text security filtering. In this case, check whether message text contains sensitive words.
80002 Message content is too long. Currently, the supported maximum message length is 8,000 bytes. In this case, adjust the message length.

API Commissioning Tool

Use the online commissioning tool for RESTful APIs to commission this API.

References

Callback That May Be Triggered

Callback before delivering group messages