开通配置环信即时通讯 IM 服务

大约 24 分钟

开通配置环信即时通讯 IM 服务

前提条件

配置环信即时通讯 IM 服务前，请确保已经具备以下条件：

创建一个环信开发者账号。

创建应用

参照以下步骤在环信即时通讯云控制台创建应用和购买即时通讯 IM 服务。

登录环信即时通讯云控制台open in new window，在首页的应用列表区域点击 添加应用 按钮，创建即时通讯 IM 应用。

在 创建应用 对话框中，输入新应用的相关信息，点击创建按钮创建应用。新建应用的服务版本默认为免费版。

提示

appname：你设置的应用名称，用于生成 App Key。该参数的值只能包含小写字母、数字和连字符，不能超过 32 个字符。
Appkey：即时通讯服务分配给每个应用的唯一标识，由 orgname 和 appname 参数的值组成，生成后无法修改。
数据中心：设置后无法修改。

购买服务

创建应用后，在 应用列表 中点击所创建应用的操作栏中的查看按钮，进入 应用详情 页面。

开通或升级版本。

你可以通过以下方法开通或升级版本。

在页面左侧的导航栏，选择 即时通讯 > 功能配置 > 版本开通，查看各种套餐的详情，选择需要的版本，点击 立即开通。

在页面左侧的导航栏，选择 即时通讯 > 服务概览，在 服务版本 区域中单击 升级版本，进入即时通讯 IM 服务版本购买页面。

在页面左侧的导航栏，选择 即时通讯 > 功能配置 > 功能配置总览，点击各功能的操作一栏中的升级或 增值服务。

在 即时通讯IM 服务版本 页面，根据业务实际需求选择所需的服务版本和可选增值服务。该页面的配置参数说明如下表所示：

参数项	描述
选择要开通服务的 Appkey	请确认 App Key 是否选择正确，购买后无法修改。
请选择服务版本	服务版本的选择如下： - 当 App Key 为免费版时，可购买专业版或旗舰版，不可单独购买增值服务。 - 当 App Key 为专业版时，可购买旗舰版或单独购买增值服务。
可选增值服务	请根据实际需求选择增值功能： - 单个群成员数上限和单个用户可加入群组数上限：不支持叠加购买；以单个群成员数上限举例说明，如果旗舰版购买了 8000 人/群的增值服务，则表示单个群成员上限配置提升至 8000 人/群。 - 消息云存储时长和 REST API 接口调用频率上限：支持可叠加购买，即支持多倍购买；以消息云存储时长举例说明，如购买时选择了 10 份，则表示消息云存储时长延长 300 天（30 天*10）。

提示

服务购买页显示的预估费用仅用于做参考，预估费用仅包含基础费用，具体费用以每月账单为准。

勾选 我已阅读并同意《环信云服务购买协议》。
核对所选服务信息，单击 立即购买 即生成订单。

购买成功后即刻生效，当天开始计费，每月 1 号自动扣除上月总消耗费用。

获取环信即时通讯 IM 的信息

在环信即时通讯云控制台，你可以查看你的环信即时通讯 IM 服务的如下信息：

应用信息	描述	如何查看
`Orgname`	环信即时通讯 IM 为每个公司（组织）分配的唯一标识。该参数是 `APPKEY` 的一部分。	在环信即时通讯云控制台open in new window的应用详情页面查看。
`Appname`	你在环信即时通讯云控制台open in new window创建应用时填入的应用名称。该参数是 `AppKey` 的一部分。	在环信即时通讯云控制台open in new window的应用详情页面查看。
`APPKEY`	应用的唯一标识，由 `Orgname` 和 `Appname` 组成，生成后不允许修改。	在环信即时通讯云控制台open in new window的应用详情页面查看。
服务器域名（`host`）	RESTful API 请求域名。环信为应用提供的 REST API 和 WebSocket 的请求域名。	在环信即时通讯云控制台open in new window的服务概览页面查看。
数据中心	环信 IM 提供的分布在全球的多个数据中心： - 国内数据中心：北京 1 区和北京 Vip6 区 - 海外数据中心：新加坡 1 区、法兰克福（法国）和弗吉尼亚（美国）	在环信即时通讯云控制台open in new window的服务概览页面查看。

查看和配置功能

创建应用后，参照以下步骤在环信即时通讯云控制台上查看环信即时通讯 IM 服务的详情以及进行配置。

在环信即时通讯云控制台的首页的 应用列表 中，点击目标应用的操作栏中的查看按钮，在左侧导航栏选择 即时通讯 > 功能配置 > 功能配置总览，您可以查看到当前 App Key 的服务配置并根据实际业务需求管理相关配置，具体操作说明如下：

免费开通：指该功能当前服务版本里已包含，可根据实际业务需求选择是否开通；点击 免费开通，则可立即开通该功能；
设置：指该功能已开通且有需要设置的配置项，点击设置，即可进入对应设置页配置；
升级：功能如果当前服务版本中不包含、或需要提高功能状态中的参数值，则可点击升级，购买升级至符合业务需求的服务版本即可；
增值服务：点击增值服务，进入增值服务购买页面，根据实际需求选择购买。

设置消息撤回（REST & 客户端）

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 功能配置 > 功能配置总览。在 功能配置总览 页面的 基础功能 页签下，搜索找到消息撤回（REST&客户端），单击右侧的设置（已开通状态下）。
在弹出的 消息撤回时间设置 对话框中，设置消息可撤回时长。端消息撤回时长和 REST 消息撤回时长均不能超过 7 天。
单击确定保存配置。

配置推送证书

使用离线推送通知之前，需完成各平台的证书配置。当前支持以下平台：苹果 APNs、谷歌 FCM、华为、小米、OPPO、VIVO 和魅族。

开启环信即时通讯 IM 服务后，按照以下步骤添加消息推送证书：

在环信即时通讯云控制台首页的应用列表中，在目标应用的操作栏中，点击查看。

在左侧导航栏，选择 即时通讯 > 功能配置 > 消息推送 > 证书管理，进入 证书管理 页面。

点击 添加推送证书 按钮，打开 添加推送证书 对话框。

在 添加推送证书 对话框中，填写各厂商平台的相关推送信息，点击保存按钮，完成证书配置。

配置推送模板

若使用推送模板，你首先要在环信即时通讯云控制台选择 即时通讯 > 功能配置 > 功能配置总览 开启离线推送高级功能。

开启后，你可以配置默认推送模板和自定义推送模板。

使用默认推送模板

默认推送模板主要用于服务器提供的默认配置不满足你的需求时，可使你设置全局范围的推送标题和推送内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。

要使用默认模板，你需要在环信即时通讯云控制台或调用 RESTful 接口创建默认推送模板，模板名称为 default。设置完毕，消息推送时自动使用默认模板，创建消息时无需传入模板名称。

按照以下步骤创建默认推送模板：

在环信即时通讯云控制台首页的应用列表中，在目标应用的操作栏中，点击查看。

在左侧导航栏，选择 即时通讯 > 功能配置 > 消息推送 > 模板管理，进入 模板管理 页面。

点击 添加推送模板，在弹出的窗口中配置模板名称、标题和内容。

模板名称：推送模板名称，String 类型，默认模板为 default。该参数必须填写。模板名称最多可包含 64 个字符，支持以下字符集：
- 26 个小写英文字母 a-z；
- 26 个大写英文字母 A-Z；
- 10 个数字 0-9。
标题/内容：推送标题/内容。Array 类型，该参数必须填写。这两个参数的设置方式如下：
- 输入固定的推送标题，例如，标题为 “您好”，内容为“您有一条新消息”。
- 内置参数填充：
  - {$dynamicFrom}：按优先级从高到底的顺序填充好友备注、群昵称（仅限群消息）和推送昵称。
  - {$fromNickname}：推送昵称。
  - {$msg}：消息内容。
- 自定义参数填充：模板输入数组索引占位符，格式为: {0} {1} {2} ... {n}

对于推送标题和内容来说，前两种设置方式在创建消息时无需传入该参数，第三种设置方式则需要通过扩展字段传入。

推送模板参数在消息扩展 ext.em_push_template 中。推送模板参数的 JSON 结构如下：

{
    "ext":{
        "em_push_template":{
            "title_args":[
                "环信"
            ],
            "content_args":[
                "欢迎使用im-push",
                "加油"
            ]
        }
    }
}

# title: {0} = "环信"
# content: {0} = "欢迎使用im-push" {1} = "加油"

群昵称即群成员在群组中的昵称，群成员在发送群消息时通过扩展字段设置，JSON 结构如下：

  {
    "ext":{
            "em_push_ext":{
                "group_user_nickname":"Jane"
            }
        }
  }

使用自定义推送模板

自定义推送模板，即名称为 default 之外的推送模板。你可以参考以下步骤使用自定义推送模板：

若使用自定义推送模板，你需要在环信即时通讯云控制台或调用 RESTful 接口创建自定义推送模板。添加推送模板 对话框中参数的描述，详见使用默认推送模板。使用自定义模板时，标题和内容参数无论通过哪种方式设置，创建消息时均需通过扩展字段传入。
创建消息时需通过使用扩展字段传入模板名称、推送标题和推送内容，通知栏中的推送标题和内容分别使用模板中的格式。

配置消息回调

环信即时通讯 IM 提供消息回调服务。旗舰版 IM 服务包含回调服务，而专业版 IM 服务不包含回调服务，需要按以下步骤单独购买。

开通消息回调

在环信即时通讯云控制台首页的应用列表中，在目标应用的操作栏中点击查看。

选择即时通讯 > 功能配置 > 功能配置总览，在基础功能页签的功能列表上，点击回调对应的 增值服务。

在弹出页面的可选增值服务区域，选择回调对应的付费开通，确定购买时长，选择 我已阅读并同意《环信云服务购买协议》，然后点击提交订单。

在支付页面，点击立即支付支付费用后即可使用。

配置回调规则

你可以按照以下步骤添加消息回调规则，最多可以配置 4 条发送前和发送后回调规则。配置回调规则后，环信服务器会自动为该规则生成 secret，向你的 app server 发送数据时会基于该 secret 生成签名（即请求中的 security 参数），作为你的服务器识别环信服务器的依据。若要使用自定义密钥，可以联系环信商务经理。

在左侧导航栏，选择 即时通讯 > 功能配置 > 消息回调，进入 消息回调 页面。

点击 添加回调地址 按钮，打开回调配置对话框，填写回调相关配置信息，点击保存按钮，完成回调配置。

配置发送前回调规则

在发送前回调对话框中配置以下参数：

参数	是否必填	描述
规则名称	是	填写文字，支持中英文，长度限制为 32 字符。每个规则的名称必须唯一。
会话类型	是	会话类型： • 单聊； • 群组； • 聊天室。
消息类型	是	支持发送前回调的消息类型包括文本、图片、视频、位置、语音、文件和自定义消息（“TEXT”，“IMAGE”，“VIDEO”，“LOCATION”，“VOICE” 和 ”FILE”）。
等待响应时间	是	后台判断超时时间，默认 200，单位为毫秒。如果回调超时无应答，消息默认会正常下发，支持修改消息处理逻辑。
调用失败时默认策略	是	当您的服务器返回结果异常或等待时间内未返回结果时，消息放行或不放行。
消息拦截报错时显示	是	当消息被拦截时，是否通知发送者 SDK 消息发送失败： • 报错：通知发送者 SDK 消息发送失败，发送者会感知到消息发送失败； • 不报错：不通知发送者 SDK 消息发送失败，发送者无感知。
启用状态	是	回调规则是否马上生效： • 启用：马上生效； • 不启用：暂不生效。 (建议首次创建配置为“不启用”，等您的服务器配置好验证信息后再修改为“启用”)
回调地址	是	回调 URL，环信 IM 对 HTTP 和 HTTPS 的回调地址均支持。

配置发送后回调规则

在发送后回调对话框中配置以下参数：

参数	是否必填	内容
规则名称	是	唯一的规则名称，只支持字母、数字和下划线，不支持中文字符，且长度不超过 32 字符。
回调地址	是	环信 IM 服务器会将消息推送到指定的 URL 地址，支持针对不同类型的消息配置不同的 HTTP 和 HTTPS 回调地址。
启用状态	是	是否启用该规则。
回调类型	是	回调类型。你可以选择对各种类型的单聊、群聊、和聊天室消息以及各种事件进行回调，详见回调事件。提示对于表情回复 Reaction 和子区 Thread，如要获取回调事件，无需单独配置，只需选择对应的消息类型即可。例如，如果需要单聊文本消息的 Reaction，你需要选中单聊消息 > 文本消息，服务器发送回调事件时即会返回 Reaction 信息。
消息类型	是	需要回调的类型： - 聊天消息：发送成功的消息，包括通过客户端和 REST API 发送的消息。这些消息与通过 REST 导出的聊天记录查询到的消息一致。例如，用户 u1 向用户 u2 发送消息，则会产生一条聊天消息，与接收方是否在线无关。收到的消息中 `from` 为 u1，`to` 为 u2。用户 u1 在群组 g1 中发送消息，则会产生一条聊天消息，收到的消息中 `from` 为 u1，`to` 为 g1，且返回值包含 `group_id` 字段。 - 离线消息：消息发送时接收方为离线的消息。例如：单聊中发送消息，若对端用户不在线，则会产生一条离线消息；在群聊中发送消息，若有几个群成员不在线，则会产生几条离线消息，这些离线消息的 `to` 参数为接收消息用户的 ID，并不是群组 ID。App 可以通过推送服务对这些消息进行个性化推送。
REST 消息是否需要回调	是	通过 REST API 发送的消息是否需要回调： - 是：需要； - 否：不需要。
From ID	否	消息发送方或操作者的用户 ID。每行输入一个用户 ID，一次最多输入 50 条。设置该参数后，环信服务器只针对该用户发送的消息及执行的操作（例如好友、群组或聊天室相关操作）进行回调。若不指定该参数，规则对发送方或操作者不限制。
To ID	否	单聊的消息或事件接收方的用户 ID。每行输入一个用户 ID，一次最多输入 50 条。若不指定该参数，规则对接收方不限制。
群组/聊天室 ID	否	群组或聊天室 ID。每行输入一个群组 ID 或聊天室 ID，一次最多输入 50 条。设置该参数后，环信服务器只针对该群组中的消息或事件进行回调。若不指定该参数，规则对群组和聊天室不限制。
扩展字段中的 Key	否	消息扩展字段中的属性 key。每行输入一个 key，一次最多输入 50 条。设置该参数后，只针对包含该属性 Key 的消息进行回调。若不指定该参数，规则对消息扩展字段不限制。

其中，From ID、To ID、群组/聊天室 ID 和扩展字段中的 Key 为配置发送后回调规则时需指定的高级筛选条件，配置示例如下：

仅对单聊的回调：仅设置 From ID 和 To ID。指定的发送方向接收方发单聊消息或对该好友进行操作（如删除好友）时收到回调消息。例如，From ID 设置为 test 1，To ID 设置为 test 2，test 1 向 test 2 发单聊消息时收到回调。
仅对群组或聊天室的回调：仅设置群组/聊天室 ID 参数。这种情况下，只有在指定的群组或聊天室中发送消息或进行操作时收到回调。例如，群组/聊天室 ID 设置为群组 ID 228978，则仅在该群组中发送消息时收到回调。
仅对群聊中某个用户的回调：仅设置 From ID 和 群组/聊天室 ID。这种情况下，只有群组或聊天室中的指定用户发送消息或执行操作时收到回调。例如，From ID 设置为 test 1，群组/聊天室 ID 设置为群组 ID 228978，仅 test 1 用户在群组中发送消息时收到回调。

提示

若 From ID、 To ID 和群组/聊天室 ID 同时设置，发送方向接收方发送单聊、群聊消息时不会收到回调。

消息举报

环信即时通讯 IM 提供消息举报功能。你的用户可以在客户端举报违规消息。当服务器收到举报消息后，会将举报消息存储到数据库，并在环信即时通讯云控制台open in new window展示。你可在环信即时通讯云控制台查看举报记录，并进行相应处理。

开通消息举报功能。

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 功能配置 > 功能配置总览。在 功能配置总览 页面的 基础功能 页签中搜索找到 消息举报，进行开通。

对于专业版，消息举报为增值服务，你需要点击 增值服务 单独付费开通，如下图所示。

对于旗舰版，该功能免费提供，你只需要点击 免费开通，开通即可使用。

提示

消息举报功能与内容审核功能为两个独立的功能，没有任何关联，因此使用该功能无需提前开通内容审核功能。

查看消息举报记录。

消息举报服务开通后，你可以在环信即时通讯云控制台的左侧导航栏中选择 内容审核 > 消息举报 查看消息举报记录。

敏感词设置

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 功能配置 > 功能配置总览。在 功能配置总览 页面的 基础功能 页签中搜索找到敏感词，单击右侧的设置（已开通状态下），打开敏感词配置页面。
在敏感词配置页面，单击 服务设置 旁边的编辑，在弹出的 敏感词服务 对话框中，按需求选择对应设置。
单击确定保存配置。

REST-IP 白名单设置

添加 IP 白名单

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 功能配置 > 功能配置总览。在 功能配置总览 页面的 基础功能 页签中搜索找到 REST-IP 白名单，单击右侧的设置（已开通状态下），打开安全配置页面。
在 安全配置 页面，单击 添加IP，在弹出的 添加 IP 对话框中，输入 IP 地址。

提示

每次只能输入 1 个 IP 地址，最多可添加 8 个。
添加 IP 地址成功后 10 分钟后生效。
若白名单列表为空，则所有 IP 地址均可发 REST 消息。

单击保存完成配置。

删除 IP 白名单

如果你不再允许某个 IP 地址继续发送 REST 消息，可以在 IP 白名单中将其删除。如果你删除了 IP 白名单中所有 IP，即白名单列表为空，则默认所有 IP 地址均可发送 REST 消息。

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 功能配置 > 安全配置。
在 IP白名单 列表中，单击目标 IP 右侧的删除。

单击确认，则删除该 IP 地址。

好友关系检查

环信即时通信 IM 默认支持陌生人之间发送单聊消息，即无需添加好友即可聊天。若仅允许好友之间发送单聊消息，你需要按以下步骤开启好友关系检查。

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 服务概览。
在设置区域，点击 好友关系检查对应的打开，则该功能的状态为已开启。若关闭该功能，点击关闭。

该功能开启后，SDK 会在用户发起单聊时检查好友关系，若用户向陌生人发送单聊消息，SDK 会提示错误码 221。

创建 IM 用户

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 运营服务 > 用户管理。
在 用户管理 页面，点击 创建IM用户 按钮，在弹出的对话框中填写用户 ID、昵称和密码，然后点击保存。
各参数的设置要求，详见注册用户 RESTful API。

创建用户后，你可以点击操作栏中的更多对该用户进行管理，包括修改用户信息和查看好友等。

创建聊天室

在环信即时通讯云的左侧导航栏中，选择 即时通讯 > 运营服务 > 聊天室管理。
在 聊天室管理 页面，点击 创建聊天室，在弹出的对话框中设置聊天室名称、描述、超级管理员和普通管理员的用户 ID 以及最大成员数，然后点击保存。
各参数的设置要求，详见创建聊天室 RESTful API。

创建聊天室后，你可以点击操作栏中的更多对进行聊天室管理，包括修改修改聊天室信息、解散聊天室以及成员管理等。

要添加聊天室成员，选择 查看聊天室成员，在弹出的对话框中，输入用户 ID，点击 添加成员。成员添加后会显示在下方的成员列表中，你可以移除该成员。

IM 用户设备日志

环信即时通讯云控制台支持查询用户设备端的日志，或将设备端的日志上传到环信日志服务器。目前，仅支持使用了高于 3.3.2 的 Android/iOS SDK 的设备。

上传设备日志到环信日志服务器

输入用户 ID 后，点击下发上传log指令，服务端将对指定用户设备下发指令：

如果当前用户在线，则会开始上传设备日志，正常情况预计 5s 内可完成上传。
如果当前用户不在线，则需要等用户下次上线时开始上传设备日志，日志保留时间为 7 天。

上传指令和日志保留时间为 7 天，即如果下发指令后 7 天内用户均未上线，则 7 天后指令失效，不会触发上传日志。

查询用户设备端日志

输入用户 ID 后，点击查询，查询用户设备端的日志。若设备已上传日志，则会查询到；若设备未上传过日志，则查询不到。

账户中心

登录环信即时通讯云控制台，选择 费用中心 > 账户中心，可查看你当前的账户余额和支出明细。

查看订单记录

登录环信即时通讯云控制台，选择 费用中心 > 订单中心，可查看你当前的所有订单记录。

订单中心页面上的订单状态说明如下：

开通中：用户生成订单后，需要 3-5 分钟完成功能配置。此时订单显示为开通中状态，表示购买的服务正在配置；配置完成后，订单变为服务中状态。
服务中：表示当前订单中购买的服务在使用中。同一 App Key 同时仅能有 1 个服务版本的订单状态为服务中。
已完结：表示当前订单中购买的服务已关闭。当客户升级新服务后，原服务版本订单和相关增值服务订单均会自动关闭，变为已完结状态。

点击操作栏中的详情，可查看订单详情。

查看账单记录

登录环信即时通讯云控制台，选择 费用中心 > 消费账单，可查看你当前的已生成的账单记录。

开通配置环信即时通讯 IM 服务

# 开通配置环信即时通讯 IM 服务

# 前提条件

# 创建应用

# 购买服务

# 获取环信即时通讯 IM 的信息

# 查看和配置功能

# 设置消息撤回（REST & 客户端）

# 配置推送证书

# 配置推送模板

# 使用默认推送模板

# 使用自定义推送模板

# 配置消息回调

# 开通消息回调

# 配置回调规则

# 消息举报

# 敏感词设置

# REST-IP 白名单设置

# 添加 IP 白名单

# 删除 IP 白名单

# 好友关系检查

# 创建 IM 用户

# 创建聊天室

# IM 用户设备日志

# 上传设备日志到环信日志服务器

# 查询用户设备端日志

# 账户中心

# 查看订单记录

# 查看账单记录

开通配置环信即时通讯 IM 服务

前提条件

创建应用

购买服务

获取环信即时通讯 IM 的信息

查看和配置功能

设置消息撤回（REST & 客户端）

配置推送证书

配置推送模板

使用默认推送模板

使用自定义推送模板

配置消息回调

开通消息回调

配置回调规则

消息举报

敏感词设置

REST-IP 白名单设置

添加 IP 白名单

删除 IP 白名单

好友关系检查

创建 IM 用户

创建聊天室

IM 用户设备日志

上传设备日志到环信日志服务器

查询用户设备端日志

账户中心

查看订单记录

查看账单记录