微信城市服务文档

消息通路接入说明

背景说明

“微信城市服务”是政务民生服务在微信上的统一服务平台,向地级市及以上政府或事业单位开放接入服务。为了帮助公众号对已关注、未关注用户均实现闭环服务体验,城市服务提供统一的消息推送接口——“消息通路”。

功能介绍

1.“消息通路”是城市服务为公众号提供的可高效地触达用户的消息推送接口。
2.“消息通路”以模板为单位进行管理,不同模板对应不同内容及推送渠道。
(1)模板内容:标题、字段名称是固定文案,字段内容通过变量提供。
(2)模板类型:完成、失败、进度提醒、待办提醒、绑定、数据展示
(3)推送渠道:包括服务通知、办事记录、结果页、待办提醒、自定义信息页卡。各模板的推送渠道与模板类型及服务场景相匹配,如“预约成功通知”是 完成模板,适合服务通知、结果页、办事记录;“快递路由”是 进度提醒模板,适用办事记录、页卡。
3.公众号获得模板使用权限后,调用一次可同时推送到多个渠道,减少了开发成本。
4.推送渠道功能介绍:
(1)服务通知:可全面覆盖未关注及已关注用户的消息推送能力。已关注通过公众号 模板消息 下发,未关注通过 服务通知 下发。
(2)办事记录:在 城市服务-我的服务 为用户长时间保存业务办理记录。
(3)结果页:城市服务提供的标准化结果页面,并提供服务评价、快速关注功能。
(4)待办提醒:在 城市服务-我的服务 为用户推送待办事件,在 首页 提醒未读待办。
(5)页卡:服务主页内展示的信息页卡,缩短路径、提升体验,内容、样式支持自定义。

示意图:

  • 服务通知:
  • Alt text

  • 办事记录:Alt text

  • 结果页:Alt text

  • 待办提醒:Alt text

  • 页卡:Alt text

    使用规则

    1.“消息通路”对已通过城市服务基础信息审核的认证服务号、主体为政府的认证订阅号开放申请。申请成功后,可在服务正式上线后、或在服务审核期30天内使用。
    2.为了给用户提供闭环体验,所有满足申请条件的服务均需接入“消息通路”,且至少包含一个 模板类型 为 完成 的模板。
    3.每个服务可以申请25个模板。
    4. 每个行业有特定模板库,每项服务均可以申请所在行业、通用行业的模板。比如医院挂号服务可申请 医疗行业、通用行业 模板。
    5.公众号可以在微信开放平台授权第三方开发者代其调用“消息通路”接口。
    6.向未关注公众号的用户使用“消息通路”能力时,需遵循以下规则否则会调用失败:
    (1)30天内用户通过城市服务访问过服务;
    (2)每项服务在一个小时内,对一个用户的下发量不超过5次;
    (3)每项服务在用户通过城市服务访问服务后30天内,对该用户下发的总量不超过10次。
    两个特殊行业:交通违法服务不受(1)限制;医疗服务 30天单用户下发总量为20次。
    7. 禁止下发营销类或与业务无关的消息,一经发现则禁用接口。

    接入流程

    Alt text


    调用方法

    1.接口调用请求

    http请求方式post
    https://api.weixin.qq.com/cityservice/sendmsgdata?access_token=ACCESS_TOKEN
    
    (1)获取 access_token 详见文档1;获取openid 详见文档2
    (2)通过小程序提供服务时,需使用小程序用户 openid ,并使用与小程序关联的、且申请了“消息通路”的公众号的 access_token

    2. 以POST方式传入json格式的参数
    (1)模板申请成功后,将会分配biz_template_id,并根据模板推送渠道不同分别提供样式ID:result_page_style_id、deal_msg_style_id、card_style_id。
    (2)调用接口时,通过POST方式传入json格式的以下参数,所有参数的数据类型均为“字符串”,且字符集默认使用UTF-8。
    字段说明:
    参数 说明 是否必填
    openid 用户唯一标识 必填
    biz_template_id 城市服务分配给公众号的模板id 必填
    result_page_style_id 结果页样式id 含结果页必填
    deal_msg_style_id 办事记录样式id 含办事记录必填
    card_style_id 页卡样式id 含页卡必填
    order_no 订单号,同一订单号的办事记录会合并 必填
    url 跳转链接,用于服务通知、结果页、待办提醒 含结果页必填
    data 模板json数据,其中color字段只对服务通知有效 必填

    参数示例

    {
               "openid":"OPENID",
               "biz_template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
               "result_page_style_id":"cUjfPSEtwasWQFsJ5PXo218PexBaHy5jg_peVDe4WkY",
               "deal_msg_style_id":"cUjfPSEtwasWQFsJ5PXo24LeNjWbwMObXSHPNjVZ0uQ",
               "card_style_id":"cUjfPSEtwasWQFsJ5PXo2z8LSM0Q6FH05DCerWEVkDs",
               "order_no":"ORDER_NO",
               "url":"http://weixin.qq.com/download",
               "data":{
                       "first": {
                           "value":"恭喜你购买成功!",
                           "color":"#173177"
                       },
                       "keynote1":{
                           "value":"巧克力",
                           "color":"#173177"
                       },
                       "keynote2": {
                           "value":"39.8元",
                           "color":"#173177"
                       },
                       "keynote3": {
                           "value":"2014年9月22日",
                           "color":"#173177"
                       },
                       "remark":{
                           "value":"欢迎再次购买!",
                           "color":"#173177"
                       }
               }
    }
    

    注:data为数组时用[ ]括起“data”字段内数据。


    3. 返回码说明
    在调用消息通路接口后,返回JSON数据包:

    返回结果 返回码 说明
    result_page_url 结果页url 需跳转至该url,替代原有的服务结果页面。
    如未传入result_page_style_id,则调用后result_page_url返回为空。
    errcode 48001 api未授权
    errcode 40097 1.参数错误
    2.或openid不来自有“消息通路”api权限的公众号
    errcode 82020 未关注公众号的用户,从未在城市服务访问过服务
    errcode 82021 未关注公众号的用户,未在近30天内通过城市服务访问服务
    errcode 82022 未关注公众号的用户,通过城市服务访问服务后,30天内被下发数超过10次(医疗行业超过20次)
    errcode 82023 未关注公众号的用户,1个小时内被下发次数超过5次
    errcode 82024 order_no异常,例如所有用户的业务订单号都用同一个
    errcode 82025 URL无效
    errcode 82026 1.服务已下线
    2.或服务在审核中且审核期超过了30天

    正常时的返回JSON数据包示例:
    {
    "errcode":0,
    "errmsg":"ok",
    "result_page_url":"https://city.weixin.qq.com/static/resultpagenew.html?openid=ont-9vjAcIdSU-LgB7ubALAVJO9U&biz_template_id=ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY #wechat_redirect"
    }
    
    注:如未传入结果页样式ID(result_page_style_id),则result_page_url结果为空


    4.页面报错提示

    提示信息 说明
    中文显示错误 字符集未用utf8
    参数错误 json参数错误
    非本人,页面打开失败 非本人openid;或登录态获取失败
    请在微信内打开 需在微信内打开页面
    系统错误 其他错误