机器人与连接器开发

开发帮助更新于 2026-08-28 阅读 7

webhook群机器人开发说明###使用场景

蓝信的webhook群机器人是蓝信群能力的高级开放功能，使用webhook群机器人，应用可以向某个指定的群里面发送消息。应用开发者可以在群内添加webhook群机器人，通过webhook消息推送地址向群内发送消息，与群内团队成员进行消息共享，事件提醒等信息交互，实现高效协作。

基本概念###webhook群机器人提供服务的基本形式是什么？

webhook群机器人由用户（群主或助理群主）在蓝信客户端的群管理页创建并获取消息推送的webhook地址，然后通过该webhook地址可以向webhook群机器人所在的群内以webhook群机器人的身份推送消息。

群主或助理群主在蓝信客户端群管理页创建webhook群机器人，设置安全认证机制，获取webhook消息发送地址。
实现消息发送的相关功能，通过步骤1中获取的webhook消息发送地址向webhook群机器人所在的群内推送消息。可以使用的消息类型为目前蓝信开放平台支持的消息类型。

使用webhook群机器人功能时必须是蓝信应用吗？必须拥有在蓝信开发者中心创建的蓝信 AppId和Secret吗？

不需要必须有蓝信的应用身份。蓝信webhook群机器人的消息接口有自己独立的安全认证机制，不依赖于蓝信的应用的接口访问凭证（app_token）。但如果用户的应用已经是一个蓝信的应用，拥有蓝信开发者中心提供的AppId和Secret，为方便用户使用webhook消息接口，用户可以选择webhook群机器人的安全机制为“蓝信应用关联”，将已有的蓝信应用ID关联到对应的webhook群机器人上，这样应用可以使用已有的蓝信应用访问凭证（app_token）来访问webhook群机器人的消息发送接口。

添加webhook群机器人的操作入口在哪里？

webhook群机器人的管理入口在蓝信客户端的群管理页内，目前蓝信的Mac客户端，Windows客户端，Android客户端和iOS客户端都支持在群内添加webhook群机器人。

谁可以添加webhook群机器人？

只有群主和助理群主有权限向群内添加webhook群机器人，并对webhook群机器人进行编辑和删除操作。

群内webhook群机器人的数量限制多少？

webhook机器人和组织内智能机器人的总数量限制为100，超过该数量限制时，群内添加webhook机器人或应用开启智能机器人时会有相应的错误提示。

使用webhook群机器人发送群消息的凭证是什么？

webhook群机器人消息接口的安全机制包括：自定义关键词，加签，IP地址（段），关联应用。用户创建webhook群机器人后可以选择一种或多种安全机制进行设置。当用户选择多个安全机制时，各个机制之间是 “与”的关系，选定的多个安全认证机制必须都符合条件时消息才可以发送到对应的群。

webhook群机器人使用流程

不同客户webhook群机器人管理UI交互略有差异，本说明以蓝信Mac客户端为例。

1. 在群组中添加webhook群机器人

进入群组，打开会话设置，找到群机器人管理，并点击创建机器人。新建机器人默认加入当前群组，机器人所属群组不可修改。

安全认证机制：蓝信webhook群机器人的消息发送接口目前提供了4种安全认证方式，可根据情况选择一种或多种进行设置，至少设置一种。方式一：自定义关键词

最多可以设置10个关键词，单个关键字不超过20个字符。当设置多个关键词时，消息内容中需要包含至少一个设置的关键词消息才能发送成功，否则返回认证错误。

方式二：加签

设置安全认证机制为签名校验时，会从设置页面上展示一个签名密钥，应用需要将签名密钥保存好。应用根据获取的密钥再加上一个当前时间戳，计算一个签名字符串，然后使用这个签名字符串作为webhook消息发送接口的调用凭证。

具体签名算法：timestamp+"@"+secret 作为签名字符串，使用Hmac SHA-256哈希算法计算签名后再进行base64编码。

timestamp为精确到秒的当前时间戳，蓝信开放平台网关收到webhook消息发送请求时会校验timestamp，如果与收到请求时的时间间隔超过1小时，会返回错误。

签名算法校验数据：timestamp=1626152063, secret = "BEF83B93944FE0094DEF512E711470AD", 计算后的签名值为：sign = qFT9vozVZ9lD6VH74ydb7+Ndb1Zhh7maH7Dg6OGxg7I=

timestamp 为距当前时间不超过 1 小时(3600)的时间戳，精确到秒。
密钥自动生成，可直接从webhook群机器人管理页上复制

Go 语言签名算法示例代码如下：

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/base64"
    "fmt"
    "testing"
    "time"
)

func Test_GenSign(t *testing.T) {
    timestamp := time.Now().Unix()
    secret := "this is secret"

    stringToSign := fmt.Sprintf("%v", timestamp) + "@" + secret
    fmt.Println(stringToSign)

    h := hmac.New(sha256.New, []byte(stringToSign))
    signature := base64.StdEncoding.EncodeToString(h.Sum(nil))

    fmt.Println(signature)
}

Python 语言签名算法示例代码如下：

import hashlib
import base64
import hmac
import time

secret = "this is secret"
timestamp = int(round(time.time()))
print(timestamp)

string_to_sign = '{}@{}'.format(timestamp, secret)
print(string_to_sign)

hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()

sign = base64.b64encode(hmac_code).decode('utf-8')

print(sign)

Java 语言签名算法示例代码如下：

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import org.apache.commons.codec.binary.Base64;

class Example {
    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        Long timestamp = System.currentTimeMillis() / 1000;
        String secret = "this is secret";

        String stringToSign = timestamp + "@" + secret;
        System.out.println(stringToSign);

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(stringToSign.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] signData = mac.doFinal(new byte[]{});
        String sign = new String(Base64.encodeBase64(signData));

        System.out.println(sign);
    }
}

C# 语言签名算法示例代码如下：

using System;
using System.Security.Cryptography;
using System.Text;

public class Program {
    public static void Main() {
        string secret = "this is secret";

        Int32 timestamp = (Int32)(DateTime.Now.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
        Console.WriteLine(timestamp);

        var stringToSign = string.Format("{0}@{1}", timestamp, secret);
        Console.WriteLine(stringToSign);

        var enc = Encoding.UTF8;
        System.Security.Cryptography.HMACSHA256 hasher = new HMACSHA256(enc.GetBytes(stringToSign));
        byte[] baHashedText = hasher.ComputeHash(enc.GetBytes(""));

        Console.WriteLine(Convert.ToBase64String(baHashedText));

    }
}

方式三：IP地址（段）

最多可以设置10个IP地址，支持段输入，如 1.1.1.* 或 1.1.1.1/24。设置完成后，webhook消息推送接口只处理来自所设置的IP地址白名单范围内的请求。对于来源不在白名单范围内的请求，接口会返回认证错误。

注意: 请输入网络出口IP地址

方式四：关联应用

如果webhook群机器人的使用方已经是一个蓝信的应用，拥有蓝信开发者中提供的AppId和Secret，那么可以选择安全认证机制为关联蓝信应用。调用webhook消息发送接口时，只需携带使用蓝信AppId和Secret换出来的app_token作为访问凭证即可。如果用户选择了使用关联蓝信应用的安全认证机制，但携带了不合法的app_token，接口会返回认证错误。关联蓝信应用是我们推荐使用的安全认证方式。

关联应用ID 可在开发者中心 提取，如下图：

2. 通过webhook地址发送群消息

获取到Webhook地址后，用户可以向这个地址发起HTTP POST 请求，即可实现给该蓝信群发送消息。

发起POST请求时，必须将字符集编码设置成UTF-8。
每个机器人每分钟最多发送20条。消息发送太频繁会严重影响群成员的使用体验，大量发消息的场景 (譬如系统监控报警) 可以将这些信息进行整合，通过指定消息以摘要的形式发送到群里。

当前webhook群机器人支持text、document、linkCard、appCard、oaCard, appArticles 消息类型，请根据自己的使用场景选择合适的消息类型，达到最好的展示样式。详情参考：消息类型及数据格式。

curl 'https://apigw-example.domain/v1/bot/hook/messages/create?hook_token=xxxx-xxxxxxxxxxxxx' \
 -H 'Content-Type: application/json' \
 -d '{
    "sign":"l4eh+ddddddddd=",
    "timestamp":"1623915644",
    "msgType":"text",
    "msgData": {
       "text":{
                "content": "webhook群机器人消息测试001"
       }
    }
}'

请将上述代码中的 “https://apigw-example.domain/open/v1/bot/hook/messages/create?hook_token=xxxx-xxxxxxxxxxxxx” 更换为真实的webhook 地址

具体webhook群消息发送接口说明请查看：发送webhook消息接口文档

智能机器人开发说明###使用场景

蓝信智能机器人是蓝信应用的高级功能，通过蓝信智能机器人功能，应用可以与自然人进行私聊或群聊的双向沟通，可以实现智能客服等功能。

基本概念###蓝信应用如何开启智能机器人能力？

目前仅蓝信自建应用支持开启智能机器人能力。开发者在蓝信开发者中心创建自建应用后，可开启蓝信智能机器人的能力。

自然人如何和蓝信智能机器人进行私聊和群聊交流？

自然人和机器人发起私聊，打开蓝信客户端（以移动端为例）：通讯录->联系人->智能机器人>机器人名片->发消息

自然人和智能机器人发起群聊，打开蓝信客户端（以移动端为例）：群管理->群机器人管理->添加智能机器人。注：仅群管理员（群主和助理群主）可以添加智能机器人，普通群成员仅可查看群内机器人列表。

应用如何接收自然人通过私聊或群聊发给智能机器人的消息？

开发者需要在应用开发者中心应用回调事件管理页注册一个回调地址，同时打开智能机器人私聊消息回复或机器人群聊消息回复的事件订阅。特别说明，目前机器人群聊消息回复只会把 @机器人的消息通过回调发送给应用回调接口。
开发者需要在应用服务端实现一个用于接收消息回调的接口，蓝信开放平台会通过回调的方式将自然人发给机器人的消息发送到应用。具体回调接口实现方式参照推送回调接口定义。

应用如何通过智能机器人发送私聊消息或群消息？

应用通过开放平台服务端接口以智能机器人身份发送私聊消息或群聊消息。

以智能机器人身份发送私聊消息给自然人智能机器人发送私聊消息。
以智能机器人身份发送群聊消息智能机器人发送群消息。

组织内智能机器人的数量限制多少？

组织内智能机器人和webhook机器人的总数量限制为100，超过该数量限制时，应用开启智能机器人或群内添加webhook机器人时会有相应的错误提示。

新开通组织智能机器人能力如何开启？

新开通的组织需要对机器人能力进行开启授权后才能使用相关功能，目前的开通方法: EMC-->全局设置-->云控设置-->群组设置-->机器人功能设置-->开启。

蓝信应用连接器使用说明

使用场景

蓝信应用连接器是一个强安全、高可用、轻量化的数据交换节点，应用和应用之间可以通过连接器进行安全的数据交换。连接器采用事件发布和订阅的模式帮助应用进行数据交换。数据发布方应用创建连接器并进行事件发布的功能开发，通过开放平台接口进行数据发布。数据接收方应用创建连接器并进行事件接收的功能开发，通过将事件接收连接器与事件发布连接器进行关联绑定，完成事件的订阅。每当事件发布连接器应用进行事件发布时，与之绑定的事件接收连接器应用就可以通过回调接口收到来自事件发布应用的事件数据。