DingTalk（钉钉）

HMAC-SHA256 署名 URL を使ったDingTalk カスタムグループロボット。Stream Mode（WebSocket）は今後追加予定の拡張機能です。

🟡 カスタムロボットで送信可能、outgoing webhook で受信可能。 最もシンプルなセットアップは、署名 URL を使った DingTalk の「カスタムグループロボット」です。エンタープライズ向け自社製アプリと Stream Mode（新規開発向けに DingTalk が推奨する WebSocket トランスポート）は今後対応予定です。

できること

POST https://oapi.dingtalk.com/robot/send に HMAC-SHA256 URL 署名（タイムスタンプ＋シークレット）を付与してテキストを送信できます。
カスタムロボットのメンションフローに対応する /webhooks/dingtalk エンドポイントでinbound outgoing webhook を受信できます。DingTalk はユーザーのメッセージを新しい timestamp と sign のペアとともに送信します。Minara は送信時と同じ方法で署名を検証します。
テキストのみ対応。 Markdown・actionCard・feedCard メッセージタイプは未対応です。
テキストメッセージ 1 件あたり 5000 文字制限があります。

セットアップ

1. カスタムグループロボットを作成する

デスクトップまたはモバイルでターゲットの DingTalk グループを開く
グループ設定 → 「群机器人」→「添加机器人」→「自定义」を選択
名前とアバターを設定し、「安全设置」では**「加签」**（「自定义关键词」や「IP 地址（段）」ではなく署名 URL オプション）を選択
保存して、次の 2 つの文字列をコピーする：
- Webhook URL（https://oapi.dingtalk.com/robot/send?access_token=... の形式）
- 署名シークレット（SEC で始まる文字列）

2. Minara を設定する

minara auth messaging add
# `dingtalk` を選択し、Webhook URL と SECxxxx シークレットを貼り付ける

または環境変数を直接設定する：

DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=<token>
DINGTALK_WEBHOOK_SECRET=SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. テストする

minara auth messaging test dingtalk

数秒以内にターゲットグループへ「✅ Minara gateway test ping」が届きます。

送信署名の仕組み

DingTalk では、すべての POST リクエストに対して、ミリ秒単位のタイムスタンプとシークレットの HMAC を URL エンコードしてリクエスト URL に付与する必要があります。

sign = base64( HmacSHA256( "<timestamp>\n<secret>", secret ) )
url  = <webhook URL>?timestamp=<ts>&sign=<urlencoded sig>

DingTalk はサーバー時刻から 1 時間以上ずれたタイムスタンプを拒否します。ホストの時刻がずれている場合、「签名错误」（署名エラー）レスポンスが返されます。

Inbound webhook（outgoing メッセージモード）

カスタムロボットの outgoing メッセージフローでは、DingTalk が次のエンドポイントに POST します：

https://<your-host>/webhooks/dingtalk

ボディにはユーザーのメッセージが含まれ、ヘッダーに新しい timestamp と sign のペアが付与されます。Minara は同じ DINGTALK_WEBHOOK_SECRET を使って署名を再計算し、不一致の場合は 401 を返します。

Inbound ペイロードの形式：

{
  "msgtype": "text",
  "text": { "content": "@bot hello world" },
  "senderId": "user-staff-id",
  "senderNick": "Alice",
  "conversationId": "cidxxxx",
  "msgId": "<unique>",
  "createAt": 1700000000000
}

msgtype === "text" のイベントのみが転送されます。それ以外のタイプ（image・audio・markdown・actionCard）は破棄されます。

制限事項と注意点

時刻のずれに注意。 DingTalk は送信側の timestamp に 1 時間のウィンドウを設けています。ホストの時刻がずれると署名が失敗します。
Outgoing webhook はメンション時のみ発火します。 グループロボットはすべてのメッセージを受信するわけではなく、自分へのメンションのみを受信します。これは Minara のフィルタではなく、DingTalk の仕様です。
Stream Mode が今後推奨される方式です。 DingTalk は新規アプリケーションに対して Stream Mode（WebSocket）を公式に推奨しています。Minara はまずレガシーなカスタムロボット方式を提供しており、Stream Mode は後続のリリースで対応予定です。

トラブルシューティング

送信時に「签名错误」（署名エラー）が発生する

サーバーの時刻ずれが原因です。chronyc tracking または timedatectl status を実行し、オフセットが 1 秒未満であることを確認してください。
DINGTALK_WEBHOOK_SECRET の入力ミスです。SECxxxx 文字列は SEC プレフィックスを含む完全なシークレットです。

「Inbound webhook が 401 を返す」

受信した署名が一致しません。最も多い原因は、グループの「安全设置」が「加签」に設定されているにもかかわらず、シークレットがローテーションされ、新しい値が ~/.minara/credentials.json に反映されていないケースです。

「グループ内でメンションしても Bot が反応しない」

ロボット詳細ページで「Outgoing webhook」が有効になっているか確認してください（受信 URL とは別のトグルです）。これが無効の場合、ロボットは送信専用になります。

リファレンス

環境変数：DINGTALK_WEBHOOK_URL、DINGTALK_WEBHOOK_SECRET
送信実装：apps/agent/src/messaging/dingtalk.ts
受信仕様：apps/agent/src/messaging/inbound/specs/dingtalk.ts
DingTalk オープンプラットフォーム：open.dingtalk.com
Stream Mode（今後対応予定）：プロトコルの説明

目次