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

httpPOST 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:

The account name must be unique. ​ ​ ​

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	0: Text message 1: image message 2: audio message 3: video message 4: location message< /li> 6: file message 10: alert message 100: custom message, if the content moderation service is not activated, the custom message will not be reviewed.
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: roam: Whether the message is roamed. The default value is true (roaming must be activated) history: Whether the message is stored in the cloud. The default value is true. sendersync: Whether the message is synced on multiple devices. The default value is true push: Whether the message is sent using APNs or an Android push service. The default value is true route: Whether the message is synced to the specified application server. The default value is true (Data sync must be endabled); badge: Whether the message is counted as unread. The default value is true; needPushNick: Whether the payload of a push notification adds a nickname. If unspecified, the default value true is applied. persistent: Whether the message is stored for offline devices. If unspecified, the default value true is applied. Offline messages are the messages sent from others when a user is offline. If messages are stored for offline devices, offline messages are temporarily stored on the IM server during the offline period and automatically delivered to the client SDK when users log in. For P2P chats, the most recent 5,000 offline messages in the last 30 days are stored, Each session can contain up to 100 recent offline messages. For group chats, the offline messages in the most recent 30 days are stored. Each group chat session can contain up to 100 recent offline messages. sessionUpdate: Whether to update this message to the last message (lastmsg) of this conversation. The default value is true
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. Up to 100 users. If the value exceeds the upper limit, an error will be thrown(status code: 811).
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)The email, phone number, token, and extension parameters are included in yidunAntiCheating. Additional data is included in yidunAntiSpamExt.
yidunAntiSpamExt	String	No	The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension field）The email, phone number, token, and extension parameters are included in yidunAntiCheating. Additional data are sent to yidunAntiSpamExt.
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 false If only friends can receive messages, you must complete the following configuration in the CommsEase console. View the detailed configuration Select your project and go the the detailed page. In the IM Free/Pro section, selectPreferences > P2P Messaging, set Non-friend messaging to No.
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

curlcurl -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

json"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

json"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"check ope"  // The ope parameter is not "0" or "1"
}

json"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: Authentication failed App does not have the permission to send messages The sender and recipient are not friends.	-
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

httpPOST 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: roam: Whether the message is roamed. The default value is true (roaming must be activated) history: Whether the message is stored in the cloud. The default value is true. sendersync: Whether the message is synced on multiple devices. The default value is true push: Whether the message is sent using APNs or an Android push service. The default value is true route: Whether the message is synced to the specified application server. The default value is true (Data sync must be enabled); badge: Whether the message is counted as unread. The default value is true; needPushNick: Whether the payload of a push notification adds a nickname. If unspecified, the default value true is applied. persistent: Whether the message is stored for offline devices. If unspecified, the default value true is applied. sessionUpdate: Whether to update this message to the last message (lastmsg) of this conversation. The default value is true
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. The email, phone number, token, and extension parameters are included in yidunAntiCheating. Additional data is included in yidunAntiSpamExt.
yidunAntiSpamExt	String	No	The data sent for moderation in JSON that contains up to 1024 characters. For more information, see GuardEase extension fields. The email, phone, token, and extension parameters are included in yidunAntiCheating. Additional data is included in yidunAntiSpamExt.
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

curlcurl -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

json"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

json"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"too many members."  // Too many users in toAccids
}

json"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: Authentication failed App does not have the permission to send messages	-
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)

json{
  "msg":"Hi"// Message body
}

Image message (type = 1)

json{
  "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)

json{
  "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)

json{
  "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)

json{
  "title": "No. 599, Wangshang Road, Hangzhou, Zhejiang, China", //location title
  "lng":120.1908686708565, // Longitude
  "lat":30.18704515647036 // Latitude
}

File message (type = 6)

json{
  "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)

json{
  "msg":"You have received a gift"
}

Custom message (type = 100)

json//User-defined body in JSON format
{
  "myKey":myValue
}