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

大约 24 分钟

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

前提条件

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

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

创建应用

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

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

img

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

提示

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

img

购买服务

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

img

  1. 开通或升级版本。

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

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

img

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

img

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

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

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

提示

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

img

  1. 勾选 我已阅读并同意《环信云服务购买协议》

  2. 核对所选服务信息,单击 立即购买 即生成订单。

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

img

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

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

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

查看和配置功能

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

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

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

img

设置消息撤回(REST & 客户端)

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

img

配置推送证书

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

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

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

img

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

img

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

img

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

img

配置推送模板

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

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

img

使用默认推送模板

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

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

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

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

img

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

img

  1. 点击 添加推送模板,在弹出的窗口中配置模板名称标题内容
  • 模板名称:推送模板名称,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"
            }
        }
  }      

img

使用自定义推送模板

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

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

  2. 创建消息时需通过使用扩展字段传入模板名称、推送标题和推送内容,通知栏中的推送标题和内容分别使用模板中的格式。

配置消息回调

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

开通消息回调

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

img

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

img

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

img

  1. 在支付页面,点击立即支付支付费用后即可使用。

img

配置回调规则

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

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

img

  1. 点击 添加回调地址 按钮,打开回调配置对话框,填写回调相关配置信息,点击 保存 按钮,完成回调配置。
  • 配置发送前回调规则

img

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

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

img

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

参数
是否必填内容
规则名称唯一的规则名称,只支持字母、数字和下划线,不支持中文字符,且长度不超过 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 IDTo ID群组/聊天室 ID扩展字段中的 Key 为配置发送后回调规则时需指定的高级筛选条件,配置示例如下:

  • 仅对单聊的回调:仅设置 From IDTo 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 IDTo ID群组/聊天室 ID 同时设置,发送方向接收方发送单聊、群聊消息时不会收到回调。

消息举报

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

  1. 开通消息举报功能。

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

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

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

提示

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

img

  1. 查看消息举报记录。

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

敏感词设置

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

img

REST-IP 白名单设置

添加 IP 白名单

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

提示

  1. 每次只能输入 1 个 IP 地址,最多可添加 8 个。
  2. 添加 IP 地址成功后 10 分钟后生效。
  3. 若白名单列表为空,则所有 IP 地址均可发 REST 消息。
  1. 单击 保存 完成配置。

img

删除 IP 白名单

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

  1. 在环信即时通讯云的左侧导航栏中,选择 即时通讯 > 功能配置 > 安全配置

  2. IP白名单 列表中,单击目标 IP 右侧的 删除

img

  1. 单击 确认,则删除该 IP 地址。

好友关系检查

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

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

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

创建 IM 用户

  1. 在环信即时通讯云的左侧导航栏中,选择 即时通讯 > 运营服务 > 用户管理

  2. 用户管理 页面,点击 创建IM用户 按钮,在弹出的对话框中填写用户 ID、昵称和密码,然后点击 保存

    各参数的设置要求,详见注册用户 RESTful API

img

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

img

创建聊天室

  1. 在环信即时通讯云的左侧导航栏中,选择 即时通讯 > 运营服务 > 聊天室管理

  2. 聊天室管理 页面,点击 创建聊天室,在弹出的对话框中设置聊天室名称、描述、超级管理员和普通管理员的用户 ID 以及最大成员数,然后点击 保存

    各参数的设置要求,详见创建聊天室 RESTful API

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

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

IM 用户设备日志

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

img

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

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

  • 如果当前用户在线,则会开始上传设备日志,正常情况预计 5s 内可完成上传。

  • 如果当前用户不在线,则需要等用户下次上线时开始上传设备日志,日志保留时间为 7 天。

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

查询用户设备端日志

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

账户中心

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

img

查看订单记录

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

img

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

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

img

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

img

查看账单记录

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

img