服务端
注册云信 IM 账号
更新时间： 2024/03/13 19:01:34
本文介绍如何通过云信服务端 API 创建云信 IM 账号，以及相关的常见问题。
功能描述
该接口用于将当前应用自身账号导入云信 IM 系统，为其创建一个对应的云信系统内部 ID（以下称 account_id ），使得该账号可使用 IM 功能。
创建账号时会自动创建用户资料。
一种典型的账号注册与初次登录的流程如下：
上图中，IM SDK 集成在应用客户端；Your App Server 为您的应用服务器；IM Server 为云信服务器。
- 通过服务端 API 创建的账号不会在控制台显示，因此注册成功后，请务必记录云信将返回的账号信息 ，在开发者自身的应用服务器上维护储存。
- 通过服务端 API 创建账号时，云信服务端会对
account_id参数做小写转换，请注意以 API 返回的account_id为准，以免登录失败。
调用频率
单个应用默认最高调用频率：100 次/秒。如超限，将被屏蔽 10 秒。
请求
URL
POST https://open.yunxinapi.com/im/v2/accounts
Header
请求 Header 的参数说明请参见请求 Header。
请求体参数
| 参数名称 | 类型 | 是否必选 | 描述 | 默认值 |
|---|---|---|---|---|
account_id |
String | 必选 | 云信账号，请确保唯一性。 |
无 |
token |
String | 可选 | 云信账号对应的登录密钥 Token。 |
- |
+
configuration |
Object | 可选 | 云信账号配置项。 | - |
+
user_information |
Object | 可选 | 用户信息。 | - |
请求体示例
json{
"account_id": "zhangsan",
"token": "abcdef",
"configuration": {
"enabled": false,
"p2p_chat_banned": false,
"team_chat_banned": false,
"chatroom_chat_banned": false,
"qchat_chat_banned": false
},
"user_information": {
"name": "zhangsan",
"avatar": "http://xxxx.xx/x.png",
"sign": "Hello World",
"email": "zhangsan@corp.xx.com",
"birthday": "xxxx-xx-xx",
"mobile": "13312345678",
"gender": "2",
"extension": "xxxx",
"antispam_business_id": "{\"textbid\":\"asdfq\"}"
}
}
响应
Header
响应 Header 的参数说明请参见响应 Header。
响应体参数
| 参数名称 | 类型 | 描述 | 是否必返回 |
|---|---|---|---|
code |
Integer | 状态码，200 表示请求成功。 | 是 |
msg |
String | 提示信息。请求失败时返回错误信息，请求成功时返回 "success"。 | 是 |
+
data |
Object | 返回的 JSON 数据对象，请求失败则返回空对象。 | 是 |
响应体示例
json{
"code": 200,
"msg": "success",
"data": {
"account_id": "zhangsan",
"token": "abcdef",
"configuration": {
"enabled": false,
"p2p_chat_banned": false,
"team_chat_banned": false,
"chatroom_chat_banned": false,
"qchat_chat_banned": false,
"push_enabled_when_desktop_online": true
},
"user_information": {
"name": "zhangsan",
"avatar": "http://xxxx.xx/x.png",
"sign": "Hello World",
"email": "zhangsan@corp.xx.com",
"birthday": "xxxx-xx-xx",
"mobile": "13312345678",
"gender": "2",
"extension": "xxxx",
"antispam_business_id": "{\"textbid\":\"asdfq\"}"
}
}
}
错误码
| 错误码 | 错误码描述 | 错误信息示例 |
|---|---|---|
| 200 | 请求成功 | success |
| 414 | 参数错误 | parameter error |
| 102405 | 用户已存在 | account already exists |
| 102434 | 超过最大账号数 | limit of accounts exceeded |
| 102449 | 账号请求需要重试 | account operation need retry |
| 103451 | 用户资料反垃圾 | user profile hit antispam |
| 500 | 服务器内部错误 | internal server error |
相关接口
云信 IM 账号的移动端推送配置（默认 true，即当桌面端在线时，允许移动端推送），只有登录后才能修改，因此无法在注册账号时设置。用户需要先登录 IM，再调用更新移动端推送配置或更新账号属性接口修改移动端推送配置。
常见问题
已有大量用户账号的应用，如何进行账号集成？
对于已经存在大量用户账号的应用，如果需要接入网易云信 IM 服务，我们推荐遵从按需创建的原则。
考虑到存量账号中可能存在相当比例的僵尸用户或非活跃用户，在迁入网易云信时直接全量导入对您是一种不必要的开销。您可以在用户第一次触发使用网易云信的 IM 行为时检查该用户的是否已创建 IM 账号（account_id），如未创建则通过后台自动创建再登录，这种方式会使您的用户只有在必要的时候才创建云信的 IM 账号，同时在云信中创建的用户都是有效的活跃用户。
为什么不能通过客户端 SDK 创建账号，必须要通过服务端创建？
网易云信的账号体系和应用的账号体系是业务绑定的关系，通过应用服务端才能创建云信 IM 账号可以有效控制账号的创建行为，任何应用的客户端都存在被破解的风险，如果直接通过客户端就可以创建云信 IM 账号可能会使您的应用出现被盗刷账号的情况（可能友商提供类似的客户端接口，使您在开发时节省了几行代码，但是为您的应用安全埋下了风险的种子）。
通过云信服务端 API 注册的 IM 账号可否在云信控制台中查看？
通过云信服务端注册的账号不会出现在控制台。
这么做的原因是：
- 控制台提供的用户列表只是部分用户列表，是为了方便您在接入云信 IM 服务的过程中，在没有服务端开发的情况下快速进行客户端集成的调试。您可以在控制台上快速的创建测试账号，并在客户端上登录测试；
- 通过云信服务端 API 创建的账号在控制台不显示，是为了保护用户的隐私及账号安全，以免出现误操作，例如对用户进行不当的禁用或其他操作。
注册账号后如何查询/更新姓名等用户信息？
可以通过调用用户名片相关接口进行查询或更新用户信息，包括用户昵称、年龄、性别等信息。