服务端集成概述
您可以在您的应用服务端(App Server)集成即时通讯服务,构建完整和丰富的业务体验。
即时通讯服务端 API 支持从应用自身的服务端(App Server)向即时通讯服务端发送请求,例如将 App 用户接入即时通讯服务(注册用户)、发送消息。部分服务管理类接口,以及高级扩展特性仅在 IM Server API 中提供,例如 系统通知、在线用户广播、创建群组、用户封禁等。关于 API 的完整功能、调试工具、注意事项的详细描述,请参见 API 接口列表。
即时通讯提供多个服务端回调,支持将即时通讯服务中的部分数据和状态同步给指定的应用后端服务,例如用户在线状态变更、聊天室房间状态变更等。支持通过回调响应正文的参数控制消息是否发送给接收者。所有服务端回调均需要在控制台分别配置回调地址并启用。详见服务端回调。
交互关系图
所有 Server API 接口必须通过 App Server 进行调用。切勿通过客户端直接调用 Server API 接口,避免 App Secret 泄漏等问题。
本文将以 注册用户 为例,帮助您快速了解服务端 API 接口的使用方式。
IM Server API 的主要功能之一是注册用户 。您必须从 App 后端必须调用该接口,使用 App 的用户 ID 换取 Token,App 用户才能接入即时通讯服务。
前提条件
在开始调用服务端 API 接口之前,请确保:
- 已在控制台创建应用,并获取了开发环境或者生产环境下有效的 App Key / App Secret。
- 已准备好自己的客户端,搭建相关的业务场景。例如,调用服务端 API 接口注册用户之后,可以使用获取到的 Token 在自己的客户端上建立 IM 连接。
- 推荐您提前了解 IM Server API 的默认行为与配置,以使整体接入体验更为顺畅。
调用方法
在控制台创建应用之后,即可创建 IM Server API 请求。建议使用 HTTPS 协议发出请求,以便对流量进行加密。
每个使用即时通讯业务的用户均需要持有即时通讯服务的身份验证令牌(Token)。以获取 Token 为例,请求如下:
POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: your-own-app-key
Nonce: 14314
Timestamp: 1408710653000
Signature: 30be0bbca9c9b2e27578701e9fda2358a814c88f
Content-Type: application/x-www-form-urlencoded
Content-Length: 78
userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg
在构建 API 请求时,请关注以下内容:
- HTTP 方法:IM Server API 当前版本全部接口为 POST 请求方式
- Host:IM Server API 域名。即时通讯服务为国内应用提供两个域名,建议您自行实现域名切换机制。详见 Server API 域名。
- App-Key:应用的开发环境或生产环境的 App Key,可在控制台创建、管理应用,并获取 App Key。
- Nonce:随机数,不超过 18 个字符。
- Timestamp:时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数。
- Signature:需要通过计算得到。登录控制台,获取与您应用/环境的 App Key(即上方的 App-Key 字段)对应的 App Secret,按顺序拼接
App Secret
+Nonce
+Timestamp
为一个字符串,进行 SHA1 哈希计算。详见 API 请求签名。 - Content-Type:一般均为
application/x-www-form-urlencoded
,有部分接口例外。详见数据格式。
发出请求后,将返回 application/json
格式的响应数据,其中包括:
- 状态码:指示成功或失败的 HTTP 状态码。200 表示请求成功。有关 HTTP 错误代码的详细信息,请参阅状态码。
- 结果数据:您请求的数据或操作的结果。对于某些操作,响应消息可以为空。
数据格式
IM Server API 接口一般使用 application/x-www-form-urlencoded
格式发送数据。
请注意,以下接口使用 application/json
格式发送数据:
- 发送单聊模板消息:
/message/private/publish_template.json
- 发送单个用户系统通知模板消息:
/message/system/publish_template.json
- 发送超级群消息:
/message/ultragroup/publish.json
- 为单个用户设置标签:
/user/tag/set.json
- 为多个用户设置标签:
/user/tag/batch/set.json
- 不落地通知:
/push.json
- 单个用户不落地通知:
/push/user.json
- 推送 Plus:
/push/custom.json