群发接口

创建群发

注意

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

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"],
    }],
    "hasMore": false,
    "type": 5
}
名称类型是否必须备注
idstring群发id,分页后续必传
tokenstring调用接口凭证
typestring5私聊 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
members.wxidsarray否(和unionIds二选一)该机器人发送对象的wxid列表,多组时会整合去重. 当wxids存在时, unionId无效
members.unionIdsarray否(和wxids二选一)该机器人发送对象的unionId列表,多组时会整合去重. 当wxids存在时, unionId无效

返回格式如下

{
    "code": 0,
    "data": {
      "id": "5c69d33cac3d075a57657ed6",
      "memberNumber": 1,
      "scheduledTimestamp": 1597903969925,
      "isCreated": false,
      "messageNumber": 1,
      "failedMembers": [{
        "botUserId": "5d0c86971150c017984cee66",
        "wxids": ["788748399949943"],
        "unionIds": ["ozynqsulJFCZ2z1aYeS8h-nuasdAAA"]
      }],
      "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
unionIdstring群发对象的unionId
errorCodenumber错误码,详情参见
errorMsgstring错误描述,详情参见

错误码说明:

错误码说明
-1群发任务不存在
-2每页长度超过限制
最近更新:
Contributors: windmemory