Send Messages
Update time: 2022/12/09 16:34:21
Server APIs allows you to send or receive one-on-one or group messages, such as text, image, audio, video, location, files, alert, and custom messages. For more information about types of messages and features, see Overview.
This document describes how to send a one-on-one or group message, and send multiple messages at a time by sending API requests with examples of different types of messages.
Send a message
Send a message to a user or a group.
Rate limit
- Apps can call the API by 100 times per second. If app users call the API exceeding the limit, the app will be blocked for 10 seconds before the API become available again.
URL
POST https://api.netease.im/nimserver/msg/sendMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
Request parameters
-
For information about the header of a POST request, see API methods.
-
The settings of the body in a POST request:
Parameter | Type | Required | Description |
---|---|---|---|
from | String | Yes | IM account (accid) of the sender. Up to 32 characters are allowed. |
ope | int | Yes | Only 0 or 1 are valid. 0: One-on-one message, 1: group message (advanced group). An error will be thrown if other values are specified (status code: 414) |
to | String | Yes | The recipient. If msgtype=0, you must specify the CommsEase IM account (accid) of the recipient receiving messages. If msgtype=1, you must specify the ID (tid) of the group receiving messages. A maximum of 32 characters are allowed. |
type | int | Yes |
|
body | String | Yes |
A maximum of 5,000 characters are allowed. The body must be in JSON format. For more information, see Message format |
msgDesc | String | No | Message description for messages other than text messages and alert messages. A maximum of 500 characters are allowed. The description can be used for keyword search for message history stored in the cloud |
antispam | boolean | No |
Specify whether the message (antispamCustom) must be moderated by the content moderation service for apps that have enabled the content moderation service. true or false. The default value is false. The parameter is applied only for custom messages (message type: 100). |
antispamCustom | String | No |
The parameter is valid only if the antispam parameter is set to true. Custom content for moderation in JSON format, the length limit is the same as the body field, and cannot exceed 5,000 characters. The format of antispamCustom: {"type":1,"data":"custom content"} Fields: 1. type: 1: text; 2: image; 3: video 2. data: Text or image URL |
option | String | No |
Special options for sending a message in JSON format, such as roaming, cloud history storage, sender multi-device sync, push notification, and data sync. If the option field is unspecified, the default value is applied.
option example: {"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true} Fields:
|
pushcontent | String | No | Body of a push notification | Up to 500 characters. The payload of a push notification can be configured only after the push field is set to true in the option. For more information about push notifications, see Configure parameters for the push notification service. |
payload | String | No | The payload of a push notification must be in JSON format cannot exceed 2,000 characters. For more information about push notifications, see Configure parameters for the push notification service. |
ext | String | No | Extension field must be in JSON format and contain up to 1,024 characters |
forcepushall | boolean | No | When sending a group message, whether the list of users to receive push notifications (@ mention operation) contains all valid members in the group except the sender. The default value is false. |
forcepushlist | String | No |
A list of users to receive push notifications (@ mention operation) when sending group messages in JSONArray, such as ["accid1","accid2"]. If forcepushall is set to true, the forcepushlist contains all valid group members except the sender. |
forcepushcontent | String | No | When sending a group message, the content that is force pushed for the users in the forcepushlist, A maximum of 500 characters are allowed. |
useYidun | int | No |
Whether a message (including custom messages) uses Content Moderator provided by GuardEase. Only 0 is valid. Other values are equal to an empty value. 0: (Content Moderator activated) does not use Content Moderator, use Generic Moderation for content review If unspecified, by default, use Content Moderator provided by GuardEase to check the content if the application has enabled the Content Moderator service. |
bid | String | No | ID of the Content Moderator service. You can specify the current message to be moderated by Content Moderation of a certain configuration. If unspecified, the original configuration will be used. |
yidunAntiCheating | String | No |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase exclusive fields) |
yidunAntiSpamExt | String | No |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension field) |
markRead | int | No | Whether read receipt is required for group messages, 0: No, 1: Yes |
async | boolean | No | Whether async call is enabled. The default value is false. |
checkFriend | boolean | No |
Whether the message is sent to only friends. The default value is falseView the detailed configuration
|
subType | int | No | Custom message type, greater than 0 |
msgSenderNoSense | int | No | Whether the message is recorded for the sender. 0: Yes, 1: No The default value is 0. If No, the message will not be recorded in multi-device sync, roaming messages, and message history for the sender. |
msgReceiverNoSense | int | No | Whether the message is recorded for the recipient. 0: Yes, 1: No The default value is 0. If No, the message will not recorded in multi-device sync, roaming messages, and message history for the recipient. |
env | String | No |
The environment name for data sync, consistent with the environment name specified in the CommsEase console for data sync as shown in the figure below. A maximum of 32 characters are allowed.
 |
Response parameters
Parameter | Type | Description |
---|---|---|
data | JSON | message data, see the table below for details |
Member properties of data:
Property | Type | Description |
---|---|---|
msgid | Long | Message ID |
antispam | boolean | Whether the message is intercepted by Content Moderator for review. If not, set the value to false |
timetag | Long | The timestamp when the message is sent |
Example
cURL request example
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&ope=0&to=lisi&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendMsg.action'
Example success response
"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"data":{
"msgid":1200510468189,
"timetag": 1545635366312,//The timestamp when the messages is sent
"antispam":false
}
}
Example error response
"Content-Type": "application/json; charset=utf-8"
{
"code":414
"desc":"check ope" // The ope parameter is not "0" or "1"
}
"Content-Type": "application/json; charset=utf-8"
{
"code":423
"desc":"account 'mute'." // The sender account is banned.
}
Status code
The following status codes are related to the responses to requests sent by calling this API. For more status codes, see Status codes.
Status code | Description | Recommendation |
---|---|---|
200 | Success | - |
811 | The number of users in the forcePushList (@mentions) list exceeds the upper limit 100 | Reduce the number of users in the list. |
416 | Too many requests | Reduce the number of requests. |
414 | Parameter error | Check the format and restrictions of arguments based on the error message. |
423 | The sender account is banned | Check whether the sender is included in the receiver's blocklist |
422 | The sender account is banned | Check whether the account is available |
403 | Possible reasons for a failed request:
|
- |
431 | repeated requests | - |
500 | Internal Server Error | - |
Send a P2P message to multiple users
Send a P2P message to multiple users
Rate limit
- You can send a P2P message to 500 users at a time. If unregistered accounts are included, the sender gets notified.
- Apps can call the API by 120 times per minute. - If the limit is exceeded, an error will be thrown (status code: 416), and requests sent from the app will be blocked for 1 minute before the app can call the API again.
URL
POST https://api.netease.im/nimserver/msg/sendBatchMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
For information about the header in a request, see Overview
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
fromAccid | String | Yes |
IM account (accid) of the sender. Up to 32 characters are allowed. The account must be unique. |
toAccids | String | Yes | IM accounts of the recipients in JSONArray, for example, ["accid1","accid2","accid3"]. If parsing fails, 414 error is thrown. A maximum of 500 recipients are allowed. |
type | int | Yes |
0: text message, 1: image message, 2: audio message, 3: video message, 4: location message, 6: file message, 10: alert message, 100: custom message |
body | String | Yes |
Message body. A maximum of 5,000 characters are allowed. The body must be in JSON format. For more information, see: Message format |
msgDesc | String | No | Message description for messages other than text messages and alert messages. A maximum of 500 characters are allowed. The description can be used for keyword search for message history stored in the cloud |
option | String | No |
Special options for sending a message in JSON format, such as roaming, cloud history, multi-device sync, push, and data sync; If the option field is unspecified, the default value is applied.
option example: {"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true} Fields:
|
pushcontent | String | No | Body of a push notification, up to 500 characters. For more information about push notifications, see Configure parameters for the push notification service. |
payload | String | No | The payload of a push notification in JSON, up to 2,000 characters. For more information, see Configure parameters for the push notification service. |
ext | String | No | Extension field must be in JSON format and contain up to 1,024 characters |
useYidun | int | No |
Whether a message (including custom messages) uses Content Moderator provided by GuardEase. Only 0 is valid. Other values are equal to an empty value. 0: (Content Moderator activated) does not use Content Moderator, use Generic Moderation for content review If unspecified, by default, use Content Moderator provided by GuardEase to check the content if the application has enabled the Content Moderator service. |
bid | String | No | ID of the Content Moderator service. You can specify the current message to be moderated by Content Moderation of a certain configuration. If unspecified, the original configuration will be used. |
yidunAntiCheating | String | No |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase exclusive fields. |
yidunAntiSpamExt | String | No |
The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension fields. |
returnMsgid | Boolean | No |
Whether the message ID is returned. false: does not return the message ID (default value) true: returns the message ID. The number of accounts included in toAccids cannot exceed 100. |
env | String | No | The environment name for data sync, consistent with the environment name specified in the CommsEase console for data sync as shown in the figure below. A maximum of 32 characters are allowed. |
Response parameters
Parameter |
Type |
Description |
---|---|---|
unregister | JSONArray | unregistered users included in the toAccids list. Example: ["123123","111422"] |
timetag | Long | The timestamp when the messages is sent |
msgids | String | A list of message IDs sent to each accid, example: {"12345":1200510468189,"55213":3141251231231}, in this example "12345" and "55213" represent accids, 1200510468189 and 3141251231231 represent message IDs |
Example
cURL request example
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'fromAccid=zhangsan&toAccids=["aaa","bbb"]&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendBatchMsg.action'
Example success response
"Content-Type": "application/json; charset=utf-8"
{
"code":200
"unregister":["123123","111422"] // unregistered users included in the toAccids list
"timetag":123124124124 // The timestamp when the messages is sent
"msgids":{ // list of message IDs sent to each accid,
"12345":1200510468189, // message sent to user 12345 and message id is 1200510468189
"55213":3141251231231 // message sent to user 55213 and the message id is 3141251231231
}
}
Example error response
"Content-Type": "application/json; charset=utf-8"
{
"code":414
"desc":"too many members." // Too many users in toAccids
}
"Content-Type": "application/json; charset=utf-8"
{
"code":423
"desc":"account 'mute'." // The sender account is banned.
}
Status code
The following status codes are related to responses of this API. For more status codes, see Status codes.
Status code | Description | Recommendation |
---|---|---|
200 | Success | - |
414 | Parameter error | Check the format and restrictions of arguments based on the error message. |
403 | Possible reasons for a failed request:
|
- |
422 | The sender account is banned | Check whether the account is available |
423 | The account of a sender is banned | Check the permission of the sender to send messages |
500 | Internal Server Error | - |
Message format example
Text message (type = 0)
{
"msg":"Hi"// Message body
}
Image message (type = 1)
{
"name": "The image was sent at 2015-05-07 13:59", //image name
"md5":"9894907e4ad9de4678091277509361f7", // The MD5 value of an image file, encrypted according to byte stream
"url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e", //Generated URL
"ext":"jpg", //Image extension
"w":6814, //width in pixels
"h":2332, //height in pixels
"size":388245 //Image size in bytes.
}
Audio message (type = 2)
{
"dur":4551, //Audio duration in milliseconds
"md5":"87b94a090dec5c58f242b7132a530a01", // the MD5 value of an audio file, encrypted according to byte stream
"url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9", //Generated URL
"ext":"aac", //audio file extension. Only ACC is allowed.
"size":16420 //Size of the audio file in bytes.
}
Video messages(type = 3)
{
"dur":8003, // Video duration in milliseconds
"md5":"da2cef3e5663ee9c3547ef5d127f7e3e", // the MD5 value of a video file, encrypted according to byte stream
"url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412", //Generated URL
"w":360, //width in pixels
"h":480, //height in pixels
"ext":"mp4", //Video file extension
"size":16420 //Size of the video file in bytes.
}
Location message (type = 4)
{
"title": "No. 599, Wangshang Road, Hangzhou, Zhejiang, China", //location title
"lng":120.1908686708565, // Longitude
"lat":30.18704515647036 // Latitude
}
File message (type = 6)
{
"name":"BlizzardReg.ttf", //File name
"md5":"79d62a35fa3d34c367b20c66afc2a500", // The MD5 value of a file, encrypted according to byte stream
"url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //File URL
"ext":"ttf", //File extension
"size":91680 //Size of the file in bytes.
}
Alert message (type = 10)
{
"msg":"You have received a gift"
}
Custom message (type = 100)
//User-defined body in JSON format
{
"myKey":myValue
}