注册云信 IM 账号
更新时间： 2024/07/25 11:50:30
本文介绍如何通过网易云信服务端 API 创建网易云信 IM 账号，以及相关的常见问题。
功能描述
该接口用于将当前应用自身账号导入网易云信 IM 系统，为其创建一个对应的网易云信系统内部 ID（以下称 account_id），使得该账号可使用 IM 功能。
创建账号时会自动创建用户资料。
一种典型的账号注册与初次登录的流程如下：
sequenceDiagram
participant 网易云信 IM SDK
participant 您的应用客户端
participant 您的 App 服务端
participant 网易云信 IM 服务器
您的应用客户端 ->>网易云信 IM SDK : 集成 SDK 到应用
Note left of 网易云信 IM SDK: 注册流程
您的应用客户端 ->>您的 App 服务端 : 注册信息同步<br>给业务服务器
您的 App 服务端 ->> 网易云信 IM 服务器: 向网易云信服<br>务器发起注册请求
网易云信 IM 服务器 ->> 您的 App 服务端: 返回注册结果
您的 App 服务端 ->>您的应用客户端 : 将注册结果<br>返回客户端
Note left of 网易云信 IM SDK: 登录流程
网易云信 IM SDK -->> 网易云信 IM 服务器 : SDK 发起登录请求
网易云信 IM 服务器 -->> 网易云信 IM SDK: 返回登录结果
- 通过服务端 API 创建的账号不会在 网易云信控制台 显示，因此注册成功后，请务必记录网易云信将返回的账号信息，在开发者自身的应用服务器上维护储存。
- 通过服务端 API 创建账号时，网易云信服务端会对
account_id参数做小写转换，请注意以 API 返回的account_id为准，以免登录失败。
调用频率
单个应用默认最高调用频率请参考 频控说明。
请求
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\"}"
}
}
}
错误码
| 错误码 | 错误码描述 | 错误信息示例 |
|---|---|---|
| 102405 | 用户已存在 | account already exists |
| 102434 | 超过最大账号数 | limit of accounts exceeded |
| 102449 | 账号请求需要重试 | account operation need retry |
| 103451 | 用户资料反垃圾 | user profile hit antispam |
| 200 | 请求成功 | success |
| 403 | 鉴权失败 | authentication failed |
| 414 | 参数错误 | parameter error |
| 500 | 服务器内部错误 | internal server error |
相关接口
网易云信 IM 账号的移动端推送配置（默认 true，即当桌面端在线时，允许移动端推送），只有登录后才能修改，因此无法在注册账号时设置。用户需要先登录 IM，再调用 更新移动端推送配置 或 更新账号属性 接口修改移动端推送配置。
常见问题
已有大量用户账号的应用，如何进行账号集成？
对于已经存在大量用户账号的应用，如果需要接入网易云信 IM 服务，网易云信推荐遵从 按需创建 的原则。
考虑到存量账号中可能存在相当比例的僵尸用户或非活跃用户，在迁入网易云信时直接全量导入对您是一种不必要的开销。您可以在用户第一次触发使用网易云信的 IM 行为时检查该用户的是否已创建 IM 账号（account_id），如未创建则通过后台自动创建再登录，这种方式会使您的用户只有在必要的时候才创建网易云信的 IM 账号，同时在网易云信中创建的用户都是有效的活跃用户。
为什么不能通过客户端 SDK 创建账号，必须要通过服务端创建？
网易云信的账号体系和应用的账号体系是业务绑定的关系，通过应用服务端才能创建网易云信 IM 账号可以有效控制账号的创建行为，任何应用的客户端都存在被破解的风险，如果直接通过客户端就可以创建网易云信 IM 账号可能会使您的应用出现被盗刷账号的情况（可能友商提供类似的客户端接口，使您在开发时节省了几行代码，但是为您的应用安全埋下了风险的种子）。
通过网易云信服务端 API 注册的 IM 账号可否在网易云信控制台中查看？
通过网易云信服务端注册的账号不会出现在 网易云信控制台。
这么做的原因是：
- 控制台提供的用户列表只是部分用户列表，是为了方便您在接入网易云信 IM 服务的过程中，在没有服务端开发的情况下快速进行客户端集成的调试。您可以在 网易云信控制台 上快速的创建测试账号，并在客户端上登录测试。
- 通过网易云信服务端 API 创建的账号在 网易云信控制台 不显示，是为了保护用户的隐私及账号安全，以免出现误操作，例如对用户进行不当的禁用或其他操作。
注册账号后如何查询/更新姓名等用户信息？
可以通过调用 用户名片 相关接口进行查询或更新用户信息，包括用户昵称、年龄、性别等信息。