服务端

API Host https://api.super-message.com

公共请求参数

在 URL Query Parameter 添加以下参数:

  • accessToken 用于授权访问频道的 access token,可在“开发者后台-频道”中看到并进行管理。

公共响应参数

一般情况下,接口总是响应 200 OK 的状态码,表示接口调用成功,但是业务执行是否成功需要看下面的信息:

{
    "code": int32,     // 必传,错误码,0 表示成功,其它错误请查看 message 字段内容
    "message": string, // 必传,错误信息
    "data": Object     // 可选,此字段值看对应接口文档
}

接口列表

1. 验证请求的合法性,获取用户的 OpenID

HTTP GET /v1/user/verify?token=xxx

当客户端请求您的接口时,会带上一个 request toekn 的字段,将该字段传给此接口以验证您收到的请求的合法性。其中,token 即为 request toekn。
如果 request token 合法,则返回对应用户的 OpenID。

返回数据的结构

{
    "openID": string,          // 必传,用户的 OpenID。同个用户在同个开发者帐号拥有一样的ID
    "channelCreator": boolean, // 可选,当请求的用户是频道创建人自己时,返回 true,否则不返回
    "expiredAt": int64         // 必传,request token 过期时间戳,表示在这个时间之前,您可以将 request toekn 缓存起来直接使用
}

特别注意

请特别注意一下,用户从您的不同频道发起的请求,其 request token 是不一样的,因此如果您用相同的接口来处理不同频道的请求, 那么请务必使用正确的 access token 去请求平台的 API,否则你将得到 10001 之类的错误。


2. 获取频道分享链接

HTTP GET /v1/channel/shareLink?expiration=864000

分享链接是频道的主要入口之一,可以用于生成二维码扫码快速订阅。
expiration 是分享链接的有效期,只有私有频道需要传此参数(86400 ~ 86400*60,即 1 到 60 天),公开频道不需要传此参数。

返回数据的结构

{
    "link": string,    // 必传,完成的分享链接,可以用于生成二维码或直接访问
    "expiredAt": int64 /* 必传,成的分享链接的到期时间 UNIX 时间戳(秒),0 表示永远有效(公开频道是 0,私有频道
                          视乎 expiration 的值,如果值不合理,会被强制设置到一个合理的值,因此链接的有效期请以返
                          回的 expiredAt 作为标准)*/
}

3. 推送简单的文本消息

HTTP POST /v1/messages

推送消息给频道指定成员或全体频道成员。

请求数据的结构

{
    "toAll": bool,               // 可选,当 toAll 为 true,同时 recipients 为空时消息将发送给频道全体成员,其它情况按照 recipients 发送给指定成员
    "recipients": [string, ...], /* 可选,指定接收消息的频道成员 OpenID。如果指定了接收成员,只有这部分成员会收到消
                                    息。每次最多指定 100 个接收人 */
    "title": string,             // 可选,简短的消息标题
    "data": string               // 必传,推送的文本消息
}

4. 推送消息

HTTP POST /v1/messages

推送消息给频道指定成员或全体频道成员。

请求数据的结构

{
    "toAll": bool,               // 可选,当 toAll 为 true,同时 recipients 为空时消息将发送给频道全体成员,其它情况按照 recipients 发送给指定成员
    "recipients": [string, ...], /* 可选,指定接收消息的频道成员 OpenID。如果指定了接收成员,只有这部分成员会收到消
                                    息。每次最多指定 100 个接收人 */
    "templateID": string,        // 必传,模板 ID,您在后台创建的模板
    "templateVersion": int32,    // 必传,模板版本号
    "title": string,             // 可选,简短的消息标题,在操作系统通知栏和频道列表页面显示,大概能让用户一眼知道消息内容最好
    "data": Object                   // 可选
}

返回数据的结构

{
    "id": int64 // 消息的 ID
}

4. 更新消息

HTTP PUT /v1/messages

更新指定的消息内容。

请求数据的结构

{
    "id": int64,
    "templateID": string,        // 必传,模板 ID,您在后台创建的模板
    "templateVersion": int32,    // 必传,模板版本号
    "title": string,             // 必传,简短的消息标题,在操作系统通知栏和频道列表页面显示,大概能让用户一眼知道消息内容最好
    "data": Object               // 可选
}

无返回数据


5. 删除消息

HTTP DELETE /v1/messages?id=1234

删除指定的消息。

无返回数据

消息保留时间限制

服务端保留 7 天离线消息,如果用户超过 7 天未登录客户端,那么从登录时间算起,7 天前新增/更新/删除的消息将不会同步到客户端。