Send a message

Update time: 2023/10/23 08:34:08

Send a message in a chat room. Message types include text, image, audio, video, location, files, alert, and custom messages.

Flow control in chat rooms

The flow control mechanism in chat rooms may drop some messages when participants send a large number of messages in a chat room.

To ensure user experience (such as avoiding server overload), the following flow control mechanism is applied:

  • For normal messages, users in chat room can receive up to 20 messages per second, and the excessive messages will be randomly dropped. To avoid losing important messages (server-side messages), you can set the HighPriority parameter to true to receive server-side messages with high priority and important messages will not be lost.
  • For high-priority messages, at most 10 messages are received per seconds. The excessive messages may be dropped.


Users can send messages in chat rooms, such as text messages, picture messages, voice messages, and location messages.

This API can send or resend messages by setting resendFlag. For details, see the description of this parameter in Request Parameters below.

API rate limit

  • Apps can call the API by 100 times per second. If API calls exceeds the rate limit, requests from the app will be blocked for 10 seconds before the API become available again.

Request URI

httpPOST HTTP/1.1

Request parameters

  • For information about how to set the header in a POST request, see API Call methods.

  • The settings of the body in a POST request:

ParameterType RequiredDescription
roomid Long YesChat room ID
msgId String Yes message ID, using random strings such as uuid, messages with the same msgId will be deduplicated by the client.< /td>
attach String No Message body as the body field in message format example, up to 4,069 characters long.
fromAccid String Yesuser account sending the message, accid
ignoreMute Boolean No Whether to ignore the temporary mute of members, true: ignore; false: do not ignore, the default is false.< /td>
msgType Integer YesMessage type:
0: Text message, 1: Image message, 2: Audio message, 3: Video message, 4: Location message, 6: File message, 10: Alert, 100: Custom messageFor applications that are not integrated to GuardEase moderation service, custom messages will not be forwarded to the moderation service for review
subType IntegerNoCustom message subtype, a value greater than 0.
resendFlag Integer No Flag for resending a message
0: Non-resent message, 1: Resent message. If users resend a message, the deduplication logic will be applied based on `msgId`.
ext String Noextension field for messages, JSON, up to 4,096 characters long.
route IntegerNoWhether the message is synced using webhooks
0: No; 1: Yes (default)< /td>
skipHistory IntegerNoWhether to store message history in the cloud
0: Yes (default); 1: No
abandonRatioIntegerNoThe probability for dropping a message, value range [0-9999];
0: does not drop the message (default), 9999: 99.99% probability of dropping the message
This parameter can be used to flow control messages for specific businessIf this parameter is specified, the following highPriority parameters becomes invalid
highPriority Boolean No true: high-priority message. High-priority messages are delivered first; false: low-priority message (default)
High-priority messages can be set to be resent. For details, see the `needHighPriorityMsgResend` parameterUse this parameter to ensure high-priority messages are delivered first. If you set all messages to high priority, the setting has no effect. A single chat room can handle up to 10 high-priority messages per second, and any excessive messages will be processed as normal messages by default.
needHighPriorityMsgResend Boolean No true: the message will be resent (default), false: the message will not be resent. If you set the value to true, a user will still receive this message during the validity period when the user leaves and rejoins the chat room. The current validity period last 30s by default. If the highPriority value is not specified, `needHighPriorityMsgResend` does not take effect
useYidun Integer No Whether a message (including custom messages) uses GuardEase moderation service. Set the value to 0. Any other value indicates that the value is unspecified.
0: indicates that the message is not audited by the GuardEase moderation service when the moderation service is activated.
If you do not specify this field, the message will be forwarded to GuardEase moderation service for review by default when the service is activated.
yidunAntiCheating String No The parameter for anti-cheating detection transferred in pass-through mode to GuardEase, JSON, with a maximum length of 1024 characters, (For details, please see GuardEase anti-spam exclusive field)
yidunAntiSpamExt String No The parameter for anti-spam enhanced transferred in pass-through mode to GuardEase, JSON, with a maximum length of 1024 characters, (for details, see GuardEase moderation service custom extension field)
bid String No Custom business ID of GuardEase moderation service. Custom moderation allows you to review the content of a single message in addition to the default moderation service. To configure custom moderation rules, contact our technical support using WhatsApp or online support for help.
antispam Boolean No For applications that have activated GuardEase moderation service, whether the message are reviewed by GuardEase (antispamCustom), default value:false
Only valid for custom messages (message type: 100)
notifyTargetTags String No Target tag expression, used to set the delivery targets in the chat room messages, the maximum length is 128 characters. For more information about how to use tags and examples, see Tag expression
antispamCustom StringNo Custom moderation rules. Valid when the `antispam` parameter is set to `true`, JSON, length limit is the same as the body field. The maximum length is 5000 characters, the required antispamCustom format is as follows:
{"type":1,"data":"custom content"}
Field description:
1. type: 1: text; 2: image; 3: video
2. data: Text or image URL
env String NoThe environment name specified in the CommsEase console sync webhooks as shown in the figure below. A maximum of 32 characters are allowed.


chatMsgPriority Integer No The priority of messages sent through the CDN channel, optional values: 0 (default), 1, 2, 3
forbiddenIfHighPriorityMsgFreq IntegerNo If high-priority messages are degraded as normal messages, return 403 error code
0: downgrade to normal message (default), 1: return 403 error code
locX Double No Spatial coordinate X, used to send spatial messages within a specified range in scenarios. Client SDK v8.11.0 and later support.
locY Double No Spatial coordinate Y, used to send spatial messages within a specified range. Client SDK v8.11.0 and later support.
locZ Double No Spatial coordinate Z, used to send spatial messages within a specified range. Client SDK v8.11.0 and later support.

Response fields

code IntegerResponse status code
desc StringDetailed description of the sent message.

desc representation

time LongTimestamp of a sent message in milliseconds.
fromAvatorString Avatar of the message sender.
msgid_clientLongClient message ID
fromClientTypeStringType of the client sending a message.
roomId LongChat room ID
fromAccount String User account sending a message. accid
fromNick String Nickname of the sender.
attach StringMessage body
type Integer Message type
ext StringExtension field
highPriorityFlag IntegerHigh priority message flag. Normal messages have no such flag.
msgAbandonFlagIntegerThe message drop flag. This flag will be returned only when the abandonRatio parameter is passed. If this flag is not returned, a message is not dropped.


Example request (cURL)

curlcurl -X POST -H "CheckSum: 51eb13ea***1c65c7866c366" -H "AppKey: f541664***6ad7799" -H "Nonce: 1" -H "CurTime: 1451207708" -H "Content-Type: application/x-www-form-urlencoded" -d 'roomid=36&fromAccid=zhangsan&msgType=0&attach=This+is+test+msg&msgId=c9e6c306-804f-4ec3-b8f0-573778829419' ''

Example success response

json"Content-Type": "application/json; charset=utf-8"
  "time": "1456396333115",
  "msgid_client": "c9e6c306-804f-4ec3-b8f0-573778829419",
  "fromClientType": "REST",
  "attach": "This+is+test+msg",
  "roomId": "36",
  "fromAccount": "zhangsan",
  "fromNick": "Zhangsan",
  "type": "0",
  "ext": "",
  "highPriorityFlag":1, //High priority message flag, a normal message does not have such flag. 
  "msgAbandonFlag":"1" //The dropped message flag. This flag will be returned only when the abandonRatio parameter is passed. If this flag is not returned, the message has not been discarded.

Example error response

json"Content-Type": "application/json; charset=utf-8"
    "desc":"msgContents size exceeded" //Message body exceeded the size limit.

Status codes

The following status codes are related to responses of this API. For the complete error codes, see Status codes.

Code Description Recommendation
200 Success -
414 Parameter error Check the format and restrictions of arguments based on the error message
403 Illegal operation Exceptions, such as invalid chat room name, hit moderation rules or without the chat room permission.
416 API call rate limit. Too many requests within a short period of time Lower the number of requests
419 Limit of chat rooms exceeded. -
500 Internal Server Error -
13009 The scheduled closing of chat rooms is disabled Enable the scheduled closing function for chat rooms in the CommsEase console.
Was this page helpful?
  • Flow control in chat rooms
  • Overview
  • API rate limit
  • Request URI
  • Request parameters
  • Response fields
  • Example
  • Example request (cURL)
  • Example success response
  • Example error response
  • Status codes