English

Teams 通知通道

一次 HTTP 调用，把消息发到公司内部同事的 Teams —— 私聊或群聊。 不用自己碰 Teams / Graph / Bot Framework，不用申请 Azure 权限，不用自己养 bot。

申请 / 管理我的 API Key →
目录

这是什么

公司统一的 Teams 通知出口。消息由 AlertBot 这个机器人发出，收件人看到的是一条来自 AlertBot 的私聊，或群里的一条机器人消息。适合发：发布通知、告警、审批提醒、任务到期提醒这类 「系统主动找人」的场景。

第一步：拿一把 API Key

打开 管理后台，用公司微软账号登录，填一个申请（应用短标识、名字、用途）。 管理员批准后，key 会通过 Teams 私信发给你，也能回后台点「显示 key」自取一次。

key 只能看一次。拿到后立刻存进你的密钥管理（AWS Secrets Manager / CI secret / 环境变量），别硬编码、别提交进 git。丢了不用找人 —— 回后台自己 rotate 一把新的，旧的立即失效。

后台里还能看到：自己名下有哪些接入、审批到哪一步了、key 的前缀是什么、撤回还没批的申请。

发给个人（私聊）

POST /send
Authorization: Bearer <你的 API Key>
Content-Type: application/json

{"to": "someone@lofty.com", "text": "构建 #1234 已发布 ✅"}

curl

curl -sS -X POST "$NOTIFY_URL/send" \
  -H "Authorization: Bearer $NOTIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"someone@lofty.com","text":"构建 #1234 已发布 ✅"}'

Python（标准库，不用装东西）

import json, os, urllib.request

def notify(to, text):
    req = urllib.request.Request(
        os.environ["NOTIFY_URL"] + "/send",
        data=json.dumps({"to": to, "text": text}).encode(),
        headers={"Authorization": "Bearer " + os.environ["NOTIFY_KEY"],
                 "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

成功返回

{"ok": true, "to": "someone@lofty.com", "toKind": "user",
 "displayName": "Someone", "chatId": "19:...@unq.gbl.spaces",
 "messageId": "1699...", "requestId": "21ddaecf-..."}

requestId 留着 —— 出问题把它给平台方，能直接查到那一次调用的审计。

发到群里

群聊走另一个端点，收件人字段是 chat_id：

POST /send/group
Authorization: Bearer <你的 API Key>

{"chat_id": "19:42567b29...c1@thread.v2", "text": "今晚 22:00 发版，注意下"}

群 id 怎么拿

在 Teams 里打开那个群 → 群名右边「⋯」→ 复制链接，得到类似：

https://teams.microsoft.com/l/chat/19:42567b...a1@thread.v2/conversations?...

中间那段 19:…@thread.v2 就是 chat_id。

前提：AlertBot 必须已经在那个群里。 在群里点「⋯ → 添加应用 / Apps」，搜 AlertBot 加进去，一次就好。 没加的话调用会返回 403/404，响应里会带这条提示。

频道（@thread.tacv2）暂不支持，只支持群聊（@thread.v2）。 需要发频道找平台方说一声。

群消息是一条打扰一屋子人。发频率、发什么内容自己把住 —— 所有群消息都记审计，按群能查「这个群被谁发过什么」。

用模板发卡片

不想自己拼 Adaptive Card JSON，就传 template_id + params，服务端渲染。 私聊和群聊都支持。

{"to": "someone@lofty.com",
 "template_id": "release-notice",
 "params": {"service": "payment-api", "version": "v2.3.1",
            "env": "prod", "url": "https://ci.example.com/build/1234"}}
template_id用途必填 params可选 params
release-notice发布通知service, versionenv, notes, url
alert告警title, messageseverity, source, url
approval-request审批请求title, requesterdetails, url

可选参数留空会自动从卡片里清掉（不会留空行、空按钮）。也可以直接传自己的 card（完整 Adaptive Card JSON），跟 text / template_id 三者给一个即可。

错误码

状态含义怎么办
200发出去了—
400参数不对 / 收件人不存在 / 群 id 格式错 / bot 不在群里看 error 和 detail.hint，改完重试
401key 无效或已被吊销到后台确认 key 状态，或 rotate 一把
502上游（Teams / Graph / BF）出错可稍后重试；持续失败带 requestId 找平台方
500通道内部错误带 requestId 找平台方

失败响应统一是 {"ok": false, "error": ..., "detail": ..., "requestId": ...}。

规矩与限制