SaaS API文档

群发接口

创建群发

注意

  • 若使用unionId方式创建群发，需确认秒回端客户已完成union ID打通，可通过回调或者通过接口获取到chatId进行打通确认
  • 创建群发接口需要说明最大传入的wxid或者unionId的总长度为1000，如果需要群发超过1000人，则需要重复调用接口来传入数据。 创建群发任务，当人数过多时需要分页。通过hasMore字段传入true, 会将多组成员数据组合在一起。
  • 多次调用接口创建群发时，非第一次调用接口时，需要带着id的参数，否则会创建出多个独立的群发。
  • 多次调用接口创建任务时，后传入的messages字段会覆盖之前传入的值。当接收到hasMore为false或不存在时，为结束标志。
  • 当群发任务全部成功时，会自动归档。当群发任务有失败的对象时，不会自动归档，需调用取消api接口或者在群发界面点击取消按钮。
  • 每一次接收到messages，都会在公司话术的"api群发"组中新建一个素材，便于界面显示以及后续对于群发详细信息进行复核。
  • 分页创建群发时需要在10分钟内完成。
  • isAtAll标识需要放在第一个文本素材里面。如果该文本素材是第一个素材，那么atAll会随着该文本素材一起发送。其他情况，群发的时候会首先单独发出一条atAll消息。
  • isAnnouncement标识需要放在第一个文本素材里面，群发会将该素材中第一个文本素材设置为群公告。

POST https://ex-api.botorange.com/broadcast/create

发送POST请求，请求数据为json格式，如下

{
    "id": "5c69d33cac3d075a57657ed6",
    "token": "abcd",
    "messages": [{
      "type": 0, // MessageType, check below
      "payload": {
        "text": "你好啊，我是商务", // message content
        "mention": ["wxid_rr9ej1o8xv9h21"], // mention list, when send message to room, can set mention list, nullable
      },
      "isAnnouncement": false,
      "isAtAll": false,
    }],
    "scheduledTimestamp": 1597903969925,
    "members": [{
      "botUserId": "5d0c86971150c017984cee66",
      "wxids": ["788748399949943"],
      "unionIds": ["ozynqsulJFCZ2z1aYeS8h-nuasdAAA"],
      "externalUserIds": ["wmrRhyBgAAdGSL2peFY7R91imak0gTmg"],
    }],
    "hasMore": false,
    "type": 5
}
名称类型是否必须备注
idstring否群发id，分页后续必传
titlestring否自定义群发名称
tokenstring是调用接口凭证, 获取方式
typestring是5私聊 6群聊
hasMoreboolean否当分页时为true，最后一个是false或者不传
scheduledTimestampnumber否（毫秒）当定时任务时必传，否则不传
messagesarray否当hseMore不传或者为false时，必须存在一组messages,多存在多组时,后面会覆盖前面的messages
messages.typenumber是参考发送消息的messageType
messages.payloadobject是参考发送消息的payload
messages.isAnnouncementboolean否表示该条消息是群公告（需保证一次群发只允许有一条群公告消息），只在type是群聊且机器人为群主时生效
messages.isAtAllboolean否表示该条消息是@所有人（需保证一次群发只允许有一条群公告消息），只在type是群聊且机器人为群主时生效
membersarray是发送对象
members.botUserIdstring是机器人的userId, 详见wxUserId
members.wxidsarray否(和unionIds、externalUserIds三选一)该机器人发送对象的wxid列表,多组时会整合去重. 当wxids存在时, unionId无效, 详见contactWxid
members.unionIdsarray否(和wxids、externalUserIds三选一)该机器人发送对象的unionId列表,多组时会整合去重. 当wxids存在时, unionId无效, 详见unionId
members.externalUserIdsarray否(和wxids、unionIds三选一)该机器人发送对象的externalUserId列表,多组时会整合去重.详见externalUserId

返回格式如下

{
    "code": 0,
    "data": {
      "id": "5c69d33cac3d075a57657ed6",
      "memberNumber": 1,
      "scheduledTimestamp": 1597903969925,
      "isCreated": false,
      "messageNumber": 1,
      "failedMembers": [{
        "botUserId": "5d0c86971150c017984cee66",
        "wxids": ["788748399949943"],
        "unionIds": ["ozynqsulJFCZ2z1aYeS8h-nuasdAAA"],
        "externalUserIds": ["wmrRhyBgAAdGSL2peFY7R91imak0gTmg"],
      }],
      "failedMemberCount": 0
    }
}
名称类型是否必须备注
idstring否群发id
memberNumbernumber是群发对象人数
scheduledTimestampnumber否（毫秒）定时任务时存在
isCreatedboolean否该群发是否创建成功
messageNumbernumber是发送消息数
failedMembersarray否未创建成功的成员,参数参照请求的members字段
failedMemberCountnumber否未创建成功的成员数量

错误码说明：

错误码说明
-1群发任务不存在
-2群发任务已开始
-3wxid或者unionId长度超过限制
-4未找到发送的消息
-5未找到发送的对象
-6指定群公告的消息数量超过1条
-7指定群公告的消息消息类型不是文本

重发群发

该接口只允许对api创建且发送完成，未归档但是有失败的群发任务进行群发。

POST https://ex-api.botorange.com/broadcast/resend

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}
名称类型是否必须备注
idstring是群发id
tokenstring是调用接口凭证, 获取方式

返回格式如下

{
  "code": 0
}

错误码说明：

错误码说明
-1群发任务不存在
-2群发任务的状态不可以重发

取消群发

该接口只允许取消发送中的群发，会自动取消群发并归档，如未发送的定时群发，请调用删除群发接口。

POST https://ex-api.botorange.com/broadcast/cancel

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}
名称类型是否必须备注
idstring否群发id
tokenstring是调用接口凭证, 获取方式

返回格式如下

{
  "code": 0
}

错误码说明：

错误码说明
-1群发任务不存在
-2群发任务的状态不可以取消

删除群发

删除未发送的定时任务。

POST https://ex-api.botorange.com/broadcast/delete

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "token": "abcd"
}
名称类型是否必须备注
idstring否群发id
tokenstring是调用接口凭证, 获取方式

返回格式如下

{
  "code": 0
}

错误码说明：

错误码说明
-1群发任务不存在
-2群发任务的不可以删除

群发回调

群发结果通知，在群发任务结束时进行回调。 会进行重试5次，间隔分别是1s, 5s, 30s, 1min

POST ***/broadcast/result

发送POST请求，请求数据为json格式，如下

{
  "id": "5c69d33cac3d075a57657ed6",
  "successTotal": 10,
  "failedTotal": 10,
  "startTimestamp": 1597903969925,
  "endTimestamp": 1597903969925,
  "scheduleTimestamp": 1597903969925
}
名称类型是否必须备注
idstring是群发id
successTotalnumber是群发成功对象数
failedTotalnumber是群发失败对象数
startTimestampnumber是（毫秒）群发开始时间
endTimestampnumber是（毫秒）群发结束时间
scheduleTimestampnumber否（毫秒）群发定时时间，定时任务存在

返回格式如下

{
  "code": 0
}

获取群发任务的失败列表

获取群发失败列表接口，可以获取到群发任务的发送失败的对象信息。

GET https://ex-api.botorange.com/broadcast/failedList?id=5c69d33cac3d075a57657ed6&current=1&pageSize=10&token=abcd

名称类型是否必须备注
idstring否群发id
tokenstring是调用接口凭证, 获取方式
currentstring是页数从1开始
pageSizestring是每页个数，最大不超过500

返回格式如下

{
  "code": 0,
  "data": [
    {
      "botUserId": "5d0c86971150c017984cee66",
      "wxid": "788748399949943",
      "unionId": "ozynqsulJFCZ2z1aYeS8h-nuasdAAA",
      "errorMsg": "",
      "errorCode": 0
    }
  ]
}
名称类型是否必须备注
botUserIdstring否机器人的userId
wxidstring是群发对象的wxid, 详见contactWxid
unionIdstring否群发对象的unionId, 详见unionId
errorCodenumber是错误码，详情参见
errorMsgstring是错误描述，详情参见

错误码说明：

错误码说明
-1群发任务不存在
-2每页长度超过限制

获取群发任务的进度

获取群发任务的进度数据

GET https://ex-api.botorange.com/broadcast/get_job_progress?id=5c69d33cac3d075a57657ed6&token=abcd

名称类型是否必须备注
idstring否群发id
tokenstring是调用接口凭证, 获取方式

返回格式如下

{
    "code": 0,
    "data": {
        "id": "63e8e08f576e1a84cbc90a58",
        "successTotal": 42,
        "failedTotal": 0,
        "unsentTotal": 43,
        "sendingTotal": 0
    }
}
名称类型是否必须备注
idstring是群发的id
successTotalnumber是成功数量
failedTotalnumber否失败数量
unsentTotalnumber是未发送的数量
sendingTotalnumber是正在发送中的数量

获取群发任务的未发送列表

获取群发任务还未发送的任务列表

GET https://ex-api.botorange.com/broadcast/list_unsent_tasks?id=5c69d33cac3d075a57657ed6&current=1&pageSize=10&token=abcd

名称类型是否必须备注
idstring否群发id
tokenstring是调用接口凭证, 获取方式
currentstring是页数从1开始
pageSizestring是每页个数，最大不超过500

返回格式如下

{
    "code": 0,
    "data": [
        {
            "botUserId": "Ling",
            "wxid": "R:10896971879606630"
        }
    ]
}
名称类型是否必须备注
botUserIdstring否机器人的userId
wxidstring是群发对象的wxid, 详见contactWxid或者roomWxid
最近更新:
Contributors: hamlin.li, windmemory, wangjingbo