推送模板

大约 9 分钟

推送模板

功能说明

推送模板用于在默认离线推送内容不满足业务需求时，自定义推送通知的标题和内容。例如，服务器提供的默认设置为中文和英文的推送标题和内容，你若需要使用韩语或日语的推送标题和内容，则可以设置对应语言的推送模板。

你可以通过环信控制台或 服务端 REST API 配置推送模板，并在发送消息时通过消息扩展字段指定模板名称和模板参数。

推送模板包括默认模板 default、detail 和自定义模板。默认模板适用于通用推送场景；自定义模板适用于需要按业务场景、语言或接收对象展示不同推送内容的场景。

推送模板具有以下特点：

  1. 推送模板的优先级高于 调用 API 设置通知栏的推送内容。
  2. 支持通过环信控制台或 服务端 REST API 自定义服务端默认推送内容。
  3. 对于群组消息，你可以使用定向模板向某些用户推送与其他用户不同的离线通知。定向模板的数据结构详见 推送扩展字段。
  4. 接收方可配置推送模板：若发送方在发送消息时使用了推送模板，则推送通知栏中的显示内容以发送方的推送模板为准。
  5. 推送模板使用优先级：
    • 自定义模板的优先级高于默认模板。
    • 发送方在消息扩展字段中指定推送模板时，接收方即使设置了推送模板，收到推送通知后也按照发送方设置的推送模板显示。

开通功能

推送模板 是推送的高级功能。使用前，你需要在 环信控制台open in new window 免费开通。激活后，如需关闭推送高级功能，必须联系商务，因为该操作会删除高级功能相关的所有配置。

  1. 登录 环信控制台open in new window。
  2. 选择页面上方的 应用管理。在弹出的应用列表页面，单击测试版 App Key 或正式版 App Key。
  3. 选择 即时通讯 > 推送配置 > 离线推送配置。
  4. 点击 免费开通。

开通后，你可以 设置推送模板。

image

设置推送模板

你可以通过以下两种方式设置离线推送模板：

推送模板相关的数据结构，详见 推送扩展字段。下面为在环信控制台设置离线推送模板。

编辑默认推送模板

离线推送模板开通后，离线推送配置 页面默认添加两个模板，default 和 detail。若未配置自定义推送模板，消息推送时自动使用默认模板，创建消息时无需传入模板名称。

  • default：默认情况下，推送标题为 您有一条新消息，推送内容为 请点击查看。若调用了 updatePushDisplayStyle 方法将 EMPushDisplayStyle 设置为 EMPushDisplayStyleSimpleBanner，则默认推送模板为 default。
  • detail：默认情况下，推送标题为 您有一条新消息，推送内容为消息内容。若调用了 updatePushDisplayStyle 方法将 EMPushDisplayStyle 设置为 EMPushDisplayStyleMessageSummary，则默认推送模板为 detail。

img

你可以在 操作 栏中选择 更多 > 编辑，修改默认推送模板的推送标题和推送内容，模板名称不能编辑。

img

参数类型描述
标题/内容Array参数的设置方式如下：
- 输入固定内容，例如，标题为 您好，内容为 您有一条新消息。
- 内置参数填充：1. {$dynamicFrom}：按优先级从高到底的顺序填充好友备注、群昵称（仅限群消息）和推送昵称。2. {$fromNickname}：推送昵称。 3. {$msg}：消息内容。
- 自定义参数填充：模板输入数组索引占位符，格式为: {0} {1} {2} ... {n}

对于推送标题和内容，固定内容和内置参数无需传入参数数组；索引占位符需要通过扩展字段传入对应参数数组。标题使用 title_args，内容使用 content_args，分别按需传入。

推送模板参数在消息扩展 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"
            }
        }
  }

添加自定义推送模板

即时通讯 IM 支持添加自定义推送模板。除了 调用 RESTful 接口 创建自定义推送模板，你还可以在 环信控制台open in new window 添加自定义推送模板。自定义推送模板的级别比默认模板高。

在 离线推送配置 页面，点击 添加推送模板 创建自定义推送模板。

参数类型描述
模板名称String推送模板名称，最多可包含 64 个字符，支持以下字符集：
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
标题/内容Array详见 默认推送模板中的配置。

发送方使用自定义模板时，应在消息扩展字段 em_push_template.name 中传入已创建的模板名称，并按模板内容传入必要的参数数组。具体规则详见 发消息时使用推送模板。

img

发送消息时使用推送模板

创建模板后，你可以在发送消息时选择此推送模板。

你可以在发送消息时选择推送模板，可通过三种方式设置推送模板。

提示

  1. 若使用默认模板 default 或 detail，消息推送时自动使用默认模板，创建消息时无需传入模板名称。
  2. 使用自定义模板时，需通过 em_push_template.name 指定模板名称；标题和内容的参数数组按模板中的索引占位符分别传入。

发送方指定自定义模板时，消息扩展 em_push_template 中的参数规则如下：

模板内容需要传入的字段
固定内容模板名称 name，无需传入 title_args 和 content_args。
内置参数模板名称 name，无需通过参数数组传入内置参数的值。
索引占位符模板名称 name；标题包含索引占位符时传入 title_args，内容包含索引占位符时传入 content_args。

标题和内容分别判断是否需要参数数组，不要求两个数组同时传入。数组中的值及顺序应与对应模板中的索引占位符匹配，无需另行传入完整的标题、内容文本。

使用固定内容的推送模板

使用固定内容的推送模板，通过 ext 扩展字段指定推送模板名称。

这种情况下，创建消息时无需传入 title_args 和 content_args 参数。

//下面以文本消息为例，其他类型的消息设置方法相同。
EMTextMessageBody *body = [[EMTextMessageBody alloc]initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc]initWithConversationID:@"conversationId" from:@"currentUsername" to:@"conversationId" body:body ext:nil];
//设置推送模板。设置前需在环信控制台或调用 REST 接口创建推送模板。
NSDictionary *pushObject = @{
   //设置推送模板名称。
   //若为默认模板 `default` 或 `detail`，无需传入模板名称。若为自定义模板，需传入模板名称。
    @"name":@"templateName",
};
message.ext = @{
    @"em_push_template":pushObject,
};
message.chatType = EMChatTypeChat;
[[EMClient sharedClient].chatManager sendMessage:message progress:nil completion:nil];

使用包含内置参数的推送模板

使用自定义或者默认推送模板，模板中的推送标题和推送内容使用以下内置参数：

  • {$dynamicFrom}：服务器按优先级从高到底的顺序填充备注、群昵称（仅限群消息）和推送昵称。
  • {$fromNickname}：推送昵称。
  • {$msg}：消息内容。

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

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

内置参数的介绍，详见 编辑默认推送模板。

这种方式的示例代码与 使用固定内容的推送模板的相同。

使用包含自定义参数的推送模板

使用自定义推送模板，而且推送标题和推送内容为自定义参数：

例如，推送模板的设置如下图所示：

img

使用下面的示例代码后，通知栏中弹出的推送通知为：

img

//下面以文本消息为例，其他类型的消息设置方法相同。
EMTextMessageBody *body = [[EMTextMessageBody alloc]initWithText:@"test"];
EMChatMessage *message = [[EMChatMessage alloc]initWithConversationID:@"conversationId" from:@"currentUsername" to:@"conversationId" body:body ext:nil];
//设置推送模板。设置前需在环信控制台上创建推送模板。
NSDictionary *pushObject = @{
    //设置推送模板名称。若不指定，设置默认推送模板的信息。
    //设置前需在环信控制台或调用 REST 接口创建推送模板。
    @"name":@"templateName",
    @"title_args":@[@"您",@"消息"],//设置填写模板标题的 value 数组。
    @"content_args":@[@"请",@"查看"]//设置填写模板内容的 value 数组。
};
message.ext = @{
    @"em_push_template":pushObject,
};
message.chatType = EMChatTypeChat;
[[EMClient sharedClient].chatManager sendMessage:message progress:nil completion:nil];

消息接收方使用推送模板

消息接收方可以调用 setPushTemplate 方法传入推送模板名称，选择要使用的模板。

提示

若发送方在发送消息时使用了推送模板，则推送通知栏中的显示内容以发送方的推送模板为准。

[EMClient.sharedClient.pushManager setPushTemplate:@"templateName" completion:^(EMError * _Nullable aError) {

}];
上次编辑于:
环信 IM 文档
© 环信 2026