服务端
API 参考
在线调试

注册云信 IM 账号

更新时间: 2024/05/20 11:06:09

本文介绍如何通过云信服务端 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 服务端 : 注册信息同步给业务服务器
您的 App 服务端 ->> 网易云信 IM 服务器: 向云信服务器发起注册请求
网易云信 IM 服务器 ->> 您的 App 服务端: 返回注册结果
您的 App 服务端 ->>您的应用客户端 : 将注册结果返回客户端
Note left of 网易云信 IM SDK: 登录流程
网易云信 IM SDK -->> 网易云信 IM 服务器 : SDK 发起登录请求
网易云信 IM 服务器 -->> 网易云信 IM SDK: 返回登录结果
  • 通过服务端 API 创建的账号不会在控制台显示,因此注册成功后,请务必记录云信将返回的账号信息,在开发者自身的应用服务器上维护储存。
  • 通过服务端 API 创建账号时,云信服务端会对 account_id 参数做小写转换,请注意以 API 返回的 account_id 为准,以免登录失败。

调用频率

单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。

请求

URL

POST https://open.yunxinapi.com/im/v2/accounts

请求 Header 的参数说明请参考 请求 Header

请求体参数

参数名称 类型 是否必选 说明 默认值
account_id String 必选 云信账号,请确保唯一性。
  • 若涉及字母,传参时请一律小写处理。因此以返回结果中的 account_id 为准。
  • 只允许字母、数字、半角下划线、@、半角点以及半角横线。
  • 长度上限为 32 位字符。
  • token String 可选 云信账号对应的登录密钥 Token。
  • 如果未指定,云信会自动生成 Token,并在创建账号成功后返回。
  • Token 如果没有更新,将永久有效。
  • 长度上限 128 位字符。
  • -
    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 创建的账号在控制台不显示,是为了保护用户的隐私及账号安全,以免出现误操作,例如对用户进行不当的禁用或其他操作。

    注册账号后如何查询/更新姓名等用户信息?

    可以通过调用 用户名片 相关接口进行查询或更新用户信息,包括用户昵称、年龄、性别等信息。

    此文档是否对你有帮助?
    有帮助
    去反馈
    • 功能描述
    • 调用频率
    • 请求
    • URL
    • Header
    • 请求体参数
    • 请求体示例
    • 响应
    • Header
    • 响应体参数
    • 响应体示例
    • 错误码
    • 相关接口
    • 常见问题