Enhance robot integration with Telegram and improve event handling

- Add Telegram integration support by introducing a dispatcher for handling Telegram events and messages.
- Implement event notifications for robot configuration changes (creation, update, deletion) to facilitate integration with external services.
- Refactor the robot initialization process to load robots into cache and start the dispatcher, improving the overall system setup.
- Update the delivery event structure to include additional metadata for better context during message handling.
- Enhance logging capabilities for better observability during robot execution and event processing.

.gitignore

@@ -69,3 +69,6 @@ sandbox/DESIGN-REMOTE.md
 event/DESIGN.md
 event/TODO.md
 agent/robot/DESIGN-V2.md
+tg-session.json
+tg-login
+tg-send

Makefile

@@ -11,14 +11,14 @@ OS := $(shell uname)
 
 # ROOT_DIR := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
 TESTFOLDER := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*' | awk '!/\/tests\// || /openapi\/tests/')
-# Core tests (exclude AI-related: agent, aigc, openai, KB, and sandbox which requires Docker)
+# Core tests (exclude AI-related: agent, aigc, openai, KB, sandbox, and integrations which require external services)
-TESTFOLDER_CORE := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*|agent|kb|sandbox' | awk '!/\/tests\// || /openapi\/tests/')
+TESTFOLDER_CORE := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*|agent|kb|sandbox|integrations' | awk '!/\/tests\// || /openapi\/tests/')
 # Agent tests (agent, aigc) - exclude agent/search/handlers/web (requires external API keys) and robot packages (tested in robot job)
 TESTFOLDER_AGENT := $(shell $(GO) list ./agent/... ./aigc/... | grep -vE 'agent/search/handlers/web|agent/robot/')
 # KB tests (kb)
 TESTFOLDER_KB := $(shell $(GO) list ./kb/...)
-# Robot tests (all agent/robot/... packages) - runs ALL tests (unit + E2E) with real LLM calls
+# Robot tests (agent/robot/... packages, excluding events/integrations which require Telegram etc.)
-TESTFOLDER_ROBOT := $(shell $(GO) list ./agent/robot/...)
+TESTFOLDER_ROBOT := $(shell $(GO) list ./agent/robot/... | grep -vE 'agent/robot/events')
 # Sandbox tests (requires Docker)
 TESTFOLDER_SANDBOX := $(shell $(GO) list ./sandbox/...)
 TESTTAGS ?= ""

agent/robot/api/lifecycle.go

@@ -1,18 +1,37 @@
 package api
 
 import (
+	"context"
 	"fmt"
 	"sync"
 
+	robotevents "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/agent/robot/events/integrations"
+	"github.com/yaoapp/yao/agent/robot/events/integrations/telegram"
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/manager"
+	"github.com/yaoapp/yao/agent/robot/types"
 )
 
+var log = logger.New("robot")
+
+func init() {
+	robotevents.RegisterTriggerFunc(func(ctx *types.Context, memberID string, triggerType types.TriggerType, data interface{}) (string, bool, error) {
+		result, err := TriggerManual(ctx, memberID, triggerType, data)
+		if err != nil {
+			return "", false, err
+		}
+		return result.ExecutionID, result.Accepted, nil
+	})
+}
+
 // ==================== Lifecycle API ====================
 // These functions manage the robot agent system lifecycle
 
 var (
-	globalManager *manager.Manager
+	globalManager    *manager.Manager
-	managerMu     sync.RWMutex
+	globalDispatcher *integrations.Dispatcher
+	managerMu        sync.RWMutex
 )
 
 // Start starts the robot agent system
@@ -33,7 +52,20 @@ func Start() error {
 		globalManager = manager.New()
 	}
 
-	return globalManager.Start()
+	if err := globalManager.Start(); err != nil {
+		return err
+	}
+
+	// Start integration dispatcher (Telegram polling, webhook subscriptions, etc.)
+	adapters := map[string]integrations.Adapter{
+		"telegram": telegram.NewAdapter(),
+	}
+	globalDispatcher = integrations.NewDispatcher(globalManager.Cache(), adapters)
+	if err := globalDispatcher.Start(context.Background()); err != nil {
+		log.Error("failed to start integration dispatcher: %v", err)
+	}
+
+	return nil
 }
 
 // StartWithConfig starts the robot agent system with custom configuration
@@ -63,12 +95,16 @@ func Stop() error {
 		return nil
 	}
 
+	if globalDispatcher != nil {
+		globalDispatcher.Stop()
+		globalDispatcher = nil
+	}
+
 	err := globalManager.Stop()
 	if err != nil {
 		return err
 	}
 
-	// Reset global manager
 	globalManager = nil
 	return nil
 }

agent/robot/api/robot.go

@@ -8,8 +8,10 @@ import (
 	gonanoid "github.com/matoous/go-nanoid/v2"
 	"github.com/yaoapp/gou/model"
 	"github.com/yaoapp/kun/maps"
+	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	"github.com/yaoapp/yao/agent/robot/store"
 	"github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
 )
 
 // ==================== Robot Query API ====================
@@ -420,6 +422,12 @@ func CreateRobot(ctx *types.Context, req *CreateRobotRequest) (*RobotResponse, e
 		_ = mgr.Cache().Refresh(ctx, req.MemberID)
 	}
 
+	// Notify integrations of new robot config
+	event.Push(context.Background(), robotevents.RobotConfigCreated, robotevents.RobotConfigPayload{
+		MemberID: req.MemberID,
+		TeamID:   req.TeamID,
+	})
+
 	// Return the created robot as response
 	return GetRobotResponse(ctx, req.MemberID)
 }
@@ -532,6 +540,12 @@ func UpdateRobot(ctx *types.Context, memberID string, req *UpdateRobotRequest) (
 		_ = mgr.Cache().Refresh(ctx, memberID) // Ignore error, database is already saved
 	}
 
+	// Notify integrations of updated robot config
+	event.Push(context.Background(), robotevents.RobotConfigUpdated, robotevents.RobotConfigPayload{
+		MemberID: memberID,
+		TeamID:   existing.TeamID,
+	})
+
 	// Return the updated robot as response
 	return GetRobotResponse(ctx, memberID)
 }
@@ -572,6 +586,12 @@ func RemoveRobot(ctx *types.Context, memberID string) error {
 		mgr.Cache().Remove(memberID)
 	}
 
+	// Notify integrations of deleted robot config
+	event.Push(context.Background(), robotevents.RobotConfigDeleted, robotevents.RobotConfigPayload{
+		MemberID: memberID,
+		TeamID:   existing.TeamID,
+	})
+
 	return nil
 }
 

agent/robot/events/delivery.go

@@ -0,0 +1,502 @@
+package events
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/yaoapp/gou/process"
+	"github.com/yaoapp/gou/text"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/attachment"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	"github.com/yaoapp/yao/messenger"
+	messengerTypes "github.com/yaoapp/yao/messenger/types"
+)
+
+// handleDelivery routes delivery content to configured channels (email, webhook, process).
+func (h *robotHandler) handleDelivery(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	var payload DeliveryPayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("delivery handler: invalid payload: %v", err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	log.Info("delivery handler: execution=%s member=%s", payload.ExecutionID, payload.MemberID)
+
+	content := payload.Content
+	prefs := payload.Preferences
+	if content == nil {
+		log.Warn("delivery handler: nil content for execution=%s", payload.ExecutionID)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Data: "no content"}
+		}
+		return
+	}
+	if prefs == nil {
+		if ev.IsCall {
+			resp <- eventtypes.Result{Data: "no preferences, skipped"}
+		}
+		return
+	}
+
+	deliveryCtx := &robottypes.DeliveryContext{
+		MemberID:    payload.MemberID,
+		ExecutionID: payload.ExecutionID,
+		TeamID:      payload.TeamID,
+	}
+
+	var results []robottypes.ChannelResult
+	var lastErr error
+
+	if prefs.Email != nil && prefs.Email.Enabled {
+		for _, target := range prefs.Email.Targets {
+			r := h.sendEmail(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("email delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	if prefs.Webhook != nil && prefs.Webhook.Enabled {
+		for _, target := range prefs.Webhook.Targets {
+			r := h.postWebhook(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("webhook delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	if prefs.Process != nil && prefs.Process.Enabled {
+		for _, target := range prefs.Process.Targets {
+			r := h.callProcess(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("process delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	// Push delivery to integration channels (Telegram, etc.) via ReplyFunc
+	if reply := getReplyFunc(); reply != nil {
+		msg := buildDeliveryMessage(content)
+		if msg != nil {
+			channel, chatID := splitChannelChatID(payload.ChatID)
+			extra := map[string]any{
+				"member_id":    payload.MemberID,
+				"execution_id": payload.ExecutionID,
+			}
+			for k, v := range payload.Extra {
+				extra[k] = v
+			}
+			metadata := &MessageMetadata{
+				Channel: channel,
+				ChatID:  chatID,
+				Extra:   extra,
+			}
+			if err := reply(ctx, msg, metadata); err != nil {
+				log.Error("delivery handler: integration reply failed execution=%s: %v", payload.ExecutionID, err)
+			}
+		}
+	}
+
+	if lastErr != nil {
+		log.Error("delivery handler: partial failure execution=%s: %v", payload.ExecutionID, lastErr)
+	}
+
+	if ev.IsCall {
+		resp <- eventtypes.Result{
+			Data: map[string]interface{}{
+				"execution_id": payload.ExecutionID,
+				"results":      results,
+			},
+			Err: lastErr,
+		}
+	}
+}
+
+// buildDeliveryMessage converts DeliveryContent into a standard assistant Message.
+func buildDeliveryMessage(content *robottypes.DeliveryContent) *agentcontext.Message {
+	if content == nil {
+		return nil
+	}
+
+	var parts []interface{}
+
+	text := content.Body
+	if text == "" {
+		text = content.Summary
+	}
+	if text != "" {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": text,
+		})
+	}
+
+	for _, att := range content.Attachments {
+		if att.File == "" {
+			continue
+		}
+		part := map[string]interface{}{
+			"type": "file",
+			"file": map[string]interface{}{
+				"url":      att.File,
+				"filename": att.Title,
+			},
+		}
+		parts = append(parts, part)
+	}
+
+	if len(parts) == 0 {
+		return nil
+	}
+
+	var msgContent interface{}
+	if len(parts) == 1 {
+		if tp, ok := parts[0].(map[string]interface{}); ok && tp["type"] == "text" {
+			msgContent = tp["text"]
+		} else {
+			msgContent = parts
+		}
+	} else {
+		msgContent = parts
+	}
+
+	return &agentcontext.Message{
+		Role:    agentcontext.RoleAssistant,
+		Content: msgContent,
+	}
+}
+
+// ============================================================================
+// Email
+// ============================================================================
+
+func (h *robotHandler) sendEmail(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.EmailTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	targetID := strings.Join(target.To, ",")
+	if targetID == "" {
+		targetID = "no-recipients"
+	}
+
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryEmail,
+		Target: targetID,
+		SentAt: &now,
+	}
+
+	svc := messenger.Instance
+	if svc == nil {
+		result.Error = "messenger service not available"
+		return result
+	}
+
+	htmlBody, plainBody := buildEmailBody(target.Template, content)
+	msg := &messengerTypes.Message{
+		To:      target.To,
+		Subject: buildEmailSubject(target.Subject, target.Template, content, deliveryCtx),
+		Body:    plainBody,
+		HTML:    htmlBody,
+		Type:    messengerTypes.MessageTypeEmail,
+	}
+
+	attachments := convertAttachments(ctx, content.Attachments)
+	if len(attachments) > 0 {
+		msg.Attachments = attachments
+	}
+
+	channel := robottypes.DefaultEmailChannel()
+	if err := svc.Send(ctx, channel, msg); err != nil {
+		result.Error = err.Error()
+		return result
+	}
+
+	result.Success = true
+	result.Recipients = target.To
+	return result
+}
+
+// ============================================================================
+// Webhook
+// ============================================================================
+
+func (h *robotHandler) postWebhook(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.WebhookTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryWebhook,
+		Target: target.URL,
+		SentAt: &now,
+	}
+
+	payload := map[string]interface{}{
+		"event":        "robot.delivery",
+		"timestamp":    now.Format(time.RFC3339),
+		"execution_id": deliveryCtx.ExecutionID,
+		"member_id":    deliveryCtx.MemberID,
+		"team_id":      deliveryCtx.TeamID,
+		"trigger_type": deliveryCtx.TriggerType,
+		"content": map[string]interface{}{
+			"summary": content.Summary,
+			"body":    content.Body,
+		},
+	}
+
+	if len(content.Attachments) > 0 {
+		info := make([]map[string]interface{}, 0, len(content.Attachments))
+		for _, att := range content.Attachments {
+			info = append(info, map[string]interface{}{
+				"title":       att.Title,
+				"description": att.Description,
+				"task_id":     att.TaskID,
+				"file":        att.File,
+			})
+		}
+		payload["attachments"] = info
+	}
+
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to marshal payload: %v", err)
+		return result
+	}
+
+	method := target.Method
+	if method == "" {
+		method = "POST"
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, target.URL, bytes.NewReader(payloadBytes))
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to create request: %v", err)
+		return result
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	for key, value := range target.Headers {
+		req.Header.Set(key, value)
+	}
+
+	if target.Secret != "" {
+		signature := ComputeHMACSignature(payloadBytes, target.Secret)
+		req.Header.Set("X-Yao-Signature", signature)
+		req.Header.Set("X-Yao-Signature-Algorithm", "HMAC-SHA256")
+	}
+
+	httpResp, err := h.httpClient.Do(req)
+	if err != nil {
+		result.Error = fmt.Sprintf("request failed: %v", err)
+		return result
+	}
+	defer httpResp.Body.Close()
+
+	body, _ := io.ReadAll(httpResp.Body)
+
+	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
+		result.Error = fmt.Sprintf("webhook returned status %d: %s", httpResp.StatusCode, string(body))
+		return result
+	}
+
+	result.Success = true
+	result.Details = map[string]interface{}{
+		"status_code": httpResp.StatusCode,
+		"response":    string(body),
+	}
+	return result
+}
+
+// ============================================================================
+// Process
+// ============================================================================
+
+func (h *robotHandler) callProcess(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.ProcessTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryProcess,
+		Target: target.Process,
+		SentAt: &now,
+	}
+
+	args := make([]interface{}, 0, 1+len(target.Args))
+	args = append(args, map[string]interface{}{
+		"content": map[string]interface{}{
+			"summary":     content.Summary,
+			"body":        content.Body,
+			"attachments": content.Attachments,
+		},
+		"context": map[string]interface{}{
+			"execution_id": deliveryCtx.ExecutionID,
+			"member_id":    deliveryCtx.MemberID,
+			"team_id":      deliveryCtx.TeamID,
+			"trigger_type": deliveryCtx.TriggerType,
+		},
+	})
+	args = append(args, target.Args...)
+
+	proc, err := process.Of(target.Process, args...)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to create process: %v", err)
+		return result
+	}
+	proc.Context = ctx
+
+	if err = proc.Execute(); err != nil {
+		result.Error = err.Error()
+		return result
+	}
+
+	result.Success = true
+	result.Details = toJSONSerializable(proc.Value)
+	return result
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+func toJSONSerializable(v interface{}) interface{} {
+	if v == nil {
+		return nil
+	}
+	if _, err := json.Marshal(v); err != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return v
+}
+
+func buildEmailSubject(subject, template string, content *robottypes.DeliveryContent, ctx *robottypes.DeliveryContext) string {
+	if subject != "" {
+		return subject
+	}
+	if content.Summary != "" {
+		return content.Summary
+	}
+	return fmt.Sprintf("Execution %s Complete", ctx.ExecutionID)
+}
+
+func buildEmailBody(template string, content *robottypes.DeliveryContent) (string, string) {
+	markdown := content.Body
+	if markdown == "" {
+		markdown = content.Summary
+	}
+	html, err := text.MarkdownToHTML(markdown)
+	if err != nil {
+		return markdown, markdown
+	}
+	return html, markdown
+}
+
+func convertAttachments(ctx context.Context, attachments []robottypes.DeliveryAttachment) []messengerTypes.Attachment {
+	if len(attachments) == 0 {
+		return nil
+	}
+
+	result := make([]messengerTypes.Attachment, 0, len(attachments))
+	for _, att := range attachments {
+		uploader, fileID, isWrapper := attachment.Parse(att.File)
+		if !isWrapper {
+			log.Warn("convertAttachments: skipping non-wrapper file value=%q title=%q", att.File, att.Title)
+			continue
+		}
+		manager, ok := attachment.Managers[uploader]
+		if !ok {
+			log.Warn("convertAttachments: manager not found uploader=%q file=%q title=%q (available: %v)",
+				uploader, att.File, att.Title, attachmentManagerKeys())
+			continue
+		}
+		info, err := manager.Info(ctx, fileID)
+		if err != nil {
+			log.Warn("convertAttachments: failed to get file info fileID=%q uploader=%q: %v", fileID, uploader, err)
+			continue
+		}
+		content, err := manager.Read(ctx, fileID)
+		if err != nil {
+			log.Warn("convertAttachments: failed to read file fileID=%q uploader=%q: %v", fileID, uploader, err)
+			continue
+		}
+
+		filename := info.Filename
+		if att.Title != "" {
+			ext := ""
+			if idx := strings.LastIndex(info.Filename, "."); idx >= 0 {
+				ext = info.Filename[idx:]
+			}
+			titleExt := ""
+			if idx := strings.LastIndex(att.Title, "."); idx >= 0 {
+				titleExt = att.Title[idx:]
+			}
+			if titleExt != "" {
+				filename = att.Title
+			} else {
+				filename = att.Title + ext
+			}
+		}
+
+		log.Info("convertAttachments: added attachment filename=%q contentType=%q size=%d", filename, info.ContentType, len(content))
+		result = append(result, messengerTypes.Attachment{
+			Filename:    filename,
+			ContentType: info.ContentType,
+			Content:     content,
+		})
+	}
+	return result
+}
+
+func attachmentManagerKeys() []string {
+	keys := make([]string, 0, len(attachment.Managers))
+	for k := range attachment.Managers {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// ComputeHMACSignature computes HMAC-SHA256 signature for webhook payload.
+func ComputeHMACSignature(payload []byte, secret string) string {
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// VerifyHMACSignature verifies the HMAC-SHA256 signature of a webhook payload.
+func VerifyHMACSignature(payload []byte, secret, signature string) bool {
+	expected := ComputeHMACSignature(payload, secret)
+	return hmac.Equal([]byte(expected), []byte(signature))
+}
+
+// splitChannelChatID splits a composite "channel:chatID" string (e.g. "telegram:8134167376")
+// into its channel and chatID parts. If no colon is present, channel is empty.
+func splitChannelChatID(composite string) (channel, chatID string) {
+	if idx := strings.Index(composite, ":"); idx >= 0 {
+		return composite[:idx], composite[idx+1:]
+	}
+	return "", composite
+}

agent/robot/events/events.go

@@ -1,6 +1,60 @@
 package events
 
-import robottypes "github.com/yaoapp/yao/agent/robot/types"
+import (
+	"context"
+	"strings"
+	"sync"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+)
+
+// TriggerFunc is the callback for triggering a robot execution.
+// Injected by the api package at startup to break the import cycle.
+// Returns (executionID, accepted, error).
+type TriggerFunc func(ctx *robottypes.Context, memberID string, triggerType robottypes.TriggerType, data interface{}) (string, bool, error)
+
+// ReplyFunc is the callback for replying to the originating channel.
+// Injected by the dispatcher at startup. The implementation routes the
+// reply to the correct adapter based on metadata.Channel.
+// msg is the standard assistant message (text, Content Parts, media, etc.).
+type ReplyFunc func(ctx context.Context, msg *agentcontext.Message, metadata *MessageMetadata) error
+
+var (
+	triggerFn   TriggerFunc
+	triggerFnMu sync.RWMutex
+
+	replyFn   ReplyFunc
+	replyFnMu sync.RWMutex
+)
+
+// RegisterTriggerFunc sets the function used by handleMessage to trigger
+// robot execution when a confirmed action is detected.
+func RegisterTriggerFunc(fn TriggerFunc) {
+	triggerFnMu.Lock()
+	defer triggerFnMu.Unlock()
+	triggerFn = fn
+}
+
+func getTriggerFunc() TriggerFunc {
+	triggerFnMu.RLock()
+	defer triggerFnMu.RUnlock()
+	return triggerFn
+}
+
+// RegisterReplyFunc sets the function used by handleMessage to reply
+// to the originating channel after processing.
+func RegisterReplyFunc(fn ReplyFunc) {
+	replyFnMu.Lock()
+	defer replyFnMu.Unlock()
+	replyFn = fn
+}
+
+func getReplyFunc() ReplyFunc {
+	replyFnMu.RLock()
+	defer replyFnMu.RUnlock()
+	return replyFn
+}
 
 // Robot event type constants for event.Push integration.
 // Events are fire-and-forget; handlers are registered via event.Register().
@@ -14,6 +68,14 @@ const (
 	ExecFailed    = "robot.exec.failed"
 	ExecCancelled = "robot.exec.cancelled"
 	Delivery      = "robot.delivery"
+	Message       = "robot.message"
+)
+
+// Robot configuration change events (used by integrations Receiver).
+const (
+	RobotConfigCreated = "robot.config.created"
+	RobotConfigUpdated = "robot.config.updated"
+	RobotConfigDeleted = "robot.config.deleted"
 )
 
 // NeedInputPayload is the event payload for TaskNeedInput / ExecWaiting events.
@@ -54,4 +116,79 @@ type DeliveryPayload struct {
 	ChatID      string                          `json:"chat_id,omitempty"`
 	Content     *robottypes.DeliveryContent     `json:"content,omitempty"`
 	Preferences *robottypes.DeliveryPreferences `json:"preferences,omitempty"`
+	Extra       map[string]any                  `json:"extra,omitempty"`
+}
+
+// MessagePayload is the event payload for Message events (external channel messages).
+type MessagePayload struct {
+	RobotID  string                 `json:"robot_id"`
+	Messages []agentcontext.Message `json:"messages"`
+	Metadata *MessageMetadata       `json:"metadata"`
+}
+
+// MessageMetadata carries channel-specific information for routing and deduplication.
+type MessageMetadata struct {
+	Channel    string         `json:"channel"`
+	MessageID  string         `json:"message_id,omitempty"`
+	AppID      string         `json:"app_id,omitempty"`
+	ChatID     string         `json:"chat_id,omitempty"`
+	SenderID   string         `json:"sender_id,omitempty"`
+	SenderName string         `json:"sender_name,omitempty"`
+	Locale     string         `json:"locale,omitempty"`
+	ReplyTo    string         `json:"reply_to,omitempty"`
+	Extra      map[string]any `json:"extra,omitempty"`
+}
+
+// MessageResult is the result returned from handleMessage via event.Call.
+type MessageResult struct {
+	Message     *agentcontext.Message `json:"message,omitempty"`
+	Action      *ActionResult         `json:"action,omitempty"`
+	ExecutionID string                `json:"execution_id,omitempty"`
+	Metadata    *MessageMetadata      `json:"metadata,omitempty"`
+}
+
+// ActionResult describes a detected action from the Host Agent's Next hook.
+type ActionResult struct {
+	Name    string `json:"name"`
+	Payload any    `json:"payload,omitempty"`
+}
+
+// RobotConfigPayload is the event payload for robot.config.* events.
+type RobotConfigPayload struct {
+	MemberID string `json:"member_id"`
+	TeamID   string `json:"team_id"`
+}
+
+// NormalizeLocale converts various language code formats (IETF BCP 47, etc.)
+// into the lowercase hyphenated form used by agentcontext (e.g. "zh-cn", "en-us").
+//
+// Mapping rules:
+//
+//	"zh-hans", "zh-cn"           → "zh-cn"
+//	"zh-hant", "zh-tw", "zh-hk" → "zh-tw"
+//	"zh"                         → "zh-cn"
+//	"en-us"                      → "en-us"
+//	"en-gb"                      → "en-gb"
+//	"en"                         → "en"
+//	""                           → "en"  (default)
+//	other                        → lowercased as-is
+func NormalizeLocale(raw string) string {
+	code := strings.ToLower(strings.TrimSpace(raw))
+	if code == "" {
+		return "en"
+	}
+
+	// Normalize underscore to hyphen (e.g. zh_CN → zh-cn)
+	code = strings.ReplaceAll(code, "_", "-")
+
+	switch code {
+	case "zh-hans", "zh-cn":
+		return "zh-cn"
+	case "zh-hant", "zh-tw", "zh-hk":
+		return "zh-tw"
+	case "zh":
+		return "zh-cn"
+	default:
+		return code
+	}
 }

agent/robot/events/handlers.go

@@ -1,27 +1,12 @@
 package events
 
 import (
-	"bytes"
 	"context"
-	"crypto/hmac"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"fmt"
-	"io"
 	"net/http"
-	"strings"
 	"time"
 
-	"github.com/yaoapp/gou/process"
-	"github.com/yaoapp/gou/text"
-	"github.com/yaoapp/kun/log"
-	robottypes "github.com/yaoapp/yao/agent/robot/types"
-	"github.com/yaoapp/yao/attachment"
 	"github.com/yaoapp/yao/event"
 	eventtypes "github.com/yaoapp/yao/event/types"
-	"github.com/yaoapp/yao/messenger"
-	messengerTypes "github.com/yaoapp/yao/messenger/types"
 )
 
 func init() {
@@ -40,6 +25,8 @@ func (h *robotHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp ch
 	switch ev.Type {
 	case Delivery:
 		h.handleDelivery(ctx, ev, resp)
+	case Message:
+		h.handleMessage(ctx, ev, resp)
 	default:
 		log.Debug("robot handler: unhandled event type=%s id=%s", ev.Type, ev.ID)
 	}
@@ -49,403 +36,3 @@ func (h *robotHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp ch
 func (h *robotHandler) Shutdown(ctx context.Context) error {
 	return nil
 }
-
-// handleDelivery routes delivery content to configured channels (email, webhook, process).
-func (h *robotHandler) handleDelivery(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
-	var payload DeliveryPayload
-	if err := ev.Should(&payload); err != nil {
-		log.Error("delivery handler: invalid payload: %v", err)
-		if ev.IsCall {
-			resp <- eventtypes.Result{Err: err}
-		}
-		return
-	}
-
-	log.Info("delivery handler: execution=%s member=%s", payload.ExecutionID, payload.MemberID)
-
-	content := payload.Content
-	prefs := payload.Preferences
-	if content == nil {
-		log.Warn("delivery handler: nil content for execution=%s", payload.ExecutionID)
-		if ev.IsCall {
-			resp <- eventtypes.Result{Data: "no content"}
-		}
-		return
-	}
-	if prefs == nil {
-		if ev.IsCall {
-			resp <- eventtypes.Result{Data: "no preferences, skipped"}
-		}
-		return
-	}
-
-	deliveryCtx := &robottypes.DeliveryContext{
-		MemberID:    payload.MemberID,
-		ExecutionID: payload.ExecutionID,
-		TeamID:      payload.TeamID,
-	}
-
-	var results []robottypes.ChannelResult
-	var lastErr error
-
-	if prefs.Email != nil && prefs.Email.Enabled {
-		for _, target := range prefs.Email.Targets {
-			r := h.sendEmail(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("email delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if prefs.Webhook != nil && prefs.Webhook.Enabled {
-		for _, target := range prefs.Webhook.Targets {
-			r := h.postWebhook(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("webhook delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if prefs.Process != nil && prefs.Process.Enabled {
-		for _, target := range prefs.Process.Targets {
-			r := h.callProcess(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("process delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if lastErr != nil {
-		log.Error("delivery handler: partial failure execution=%s: %v", payload.ExecutionID, lastErr)
-	}
-
-	if ev.IsCall {
-		resp <- eventtypes.Result{
-			Data: map[string]interface{}{
-				"execution_id": payload.ExecutionID,
-				"results":      results,
-			},
-			Err: lastErr,
-		}
-	}
-}
-
-// ============================================================================
-// Email
-// ============================================================================
-
-func (h *robotHandler) sendEmail(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.EmailTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	targetID := strings.Join(target.To, ",")
-	if targetID == "" {
-		targetID = "no-recipients"
-	}
-
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryEmail,
-		Target: targetID,
-		SentAt: &now,
-	}
-
-	svc := messenger.Instance
-	if svc == nil {
-		result.Error = "messenger service not available"
-		return result
-	}
-
-	htmlBody, plainBody := buildEmailBody(target.Template, content)
-	msg := &messengerTypes.Message{
-		To:      target.To,
-		Subject: buildEmailSubject(target.Subject, target.Template, content, deliveryCtx),
-		Body:    plainBody,
-		HTML:    htmlBody,
-		Type:    messengerTypes.MessageTypeEmail,
-	}
-
-	attachments := convertAttachments(ctx, content.Attachments)
-	if len(attachments) > 0 {
-		msg.Attachments = attachments
-	}
-
-	channel := robottypes.DefaultEmailChannel()
-	if err := svc.Send(ctx, channel, msg); err != nil {
-		result.Error = err.Error()
-		return result
-	}
-
-	result.Success = true
-	result.Recipients = target.To
-	return result
-}
-
-// ============================================================================
-// Webhook
-// ============================================================================
-
-func (h *robotHandler) postWebhook(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.WebhookTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryWebhook,
-		Target: target.URL,
-		SentAt: &now,
-	}
-
-	payload := map[string]interface{}{
-		"event":        "robot.delivery",
-		"timestamp":    now.Format(time.RFC3339),
-		"execution_id": deliveryCtx.ExecutionID,
-		"member_id":    deliveryCtx.MemberID,
-		"team_id":      deliveryCtx.TeamID,
-		"trigger_type": deliveryCtx.TriggerType,
-		"content": map[string]interface{}{
-			"summary": content.Summary,
-			"body":    content.Body,
-		},
-	}
-
-	if len(content.Attachments) > 0 {
-		info := make([]map[string]interface{}, 0, len(content.Attachments))
-		for _, att := range content.Attachments {
-			info = append(info, map[string]interface{}{
-				"title":       att.Title,
-				"description": att.Description,
-				"task_id":     att.TaskID,
-				"file":        att.File,
-			})
-		}
-		payload["attachments"] = info
-	}
-
-	payloadBytes, err := json.Marshal(payload)
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to marshal payload: %v", err)
-		return result
-	}
-
-	method := target.Method
-	if method == "" {
-		method = "POST"
-	}
-
-	req, err := http.NewRequestWithContext(ctx, method, target.URL, bytes.NewReader(payloadBytes))
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to create request: %v", err)
-		return result
-	}
-
-	req.Header.Set("Content-Type", "application/json")
-	for key, value := range target.Headers {
-		req.Header.Set(key, value)
-	}
-
-	if target.Secret != "" {
-		signature := ComputeHMACSignature(payloadBytes, target.Secret)
-		req.Header.Set("X-Yao-Signature", signature)
-		req.Header.Set("X-Yao-Signature-Algorithm", "HMAC-SHA256")
-	}
-
-	resp, err := h.httpClient.Do(req)
-	if err != nil {
-		result.Error = fmt.Sprintf("request failed: %v", err)
-		return result
-	}
-	defer resp.Body.Close()
-
-	body, _ := io.ReadAll(resp.Body)
-
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		result.Error = fmt.Sprintf("webhook returned status %d: %s", resp.StatusCode, string(body))
-		return result
-	}
-
-	result.Success = true
-	result.Details = map[string]interface{}{
-		"status_code": resp.StatusCode,
-		"response":    string(body),
-	}
-	return result
-}
-
-// ============================================================================
-// Process
-// ============================================================================
-
-func (h *robotHandler) callProcess(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.ProcessTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryProcess,
-		Target: target.Process,
-		SentAt: &now,
-	}
-
-	args := make([]interface{}, 0, 1+len(target.Args))
-	args = append(args, map[string]interface{}{
-		"content": map[string]interface{}{
-			"summary":     content.Summary,
-			"body":        content.Body,
-			"attachments": content.Attachments,
-		},
-		"context": map[string]interface{}{
-			"execution_id": deliveryCtx.ExecutionID,
-			"member_id":    deliveryCtx.MemberID,
-			"team_id":      deliveryCtx.TeamID,
-			"trigger_type": deliveryCtx.TriggerType,
-		},
-	})
-	args = append(args, target.Args...)
-
-	proc, err := process.Of(target.Process, args...)
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to create process: %v", err)
-		return result
-	}
-	proc.Context = ctx
-
-	if err = proc.Execute(); err != nil {
-		result.Error = err.Error()
-		return result
-	}
-
-	result.Success = true
-	result.Details = toJSONSerializable(proc.Value)
-	return result
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-func toJSONSerializable(v interface{}) interface{} {
-	if v == nil {
-		return nil
-	}
-	if _, err := json.Marshal(v); err != nil {
-		return fmt.Sprintf("%v", v)
-	}
-	return v
-}
-
-func buildEmailSubject(subject, template string, content *robottypes.DeliveryContent, ctx *robottypes.DeliveryContext) string {
-	if subject != "" {
-		return subject
-	}
-	if content.Summary != "" {
-		return content.Summary
-	}
-	return fmt.Sprintf("Execution %s Complete", ctx.ExecutionID)
-}
-
-func buildEmailBody(template string, content *robottypes.DeliveryContent) (string, string) {
-	markdown := content.Body
-	if markdown == "" {
-		markdown = content.Summary
-	}
-	html, err := text.MarkdownToHTML(markdown)
-	if err != nil {
-		return markdown, markdown
-	}
-	return html, markdown
-}
-
-func convertAttachments(ctx context.Context, attachments []robottypes.DeliveryAttachment) []messengerTypes.Attachment {
-	if len(attachments) == 0 {
-		return nil
-	}
-
-	result := make([]messengerTypes.Attachment, 0, len(attachments))
-	for _, att := range attachments {
-		uploader, fileID, isWrapper := attachment.Parse(att.File)
-		if !isWrapper {
-			log.Warn("convertAttachments: skipping non-wrapper file value=%q title=%q", att.File, att.Title)
-			continue
-		}
-		manager, ok := attachment.Managers[uploader]
-		if !ok {
-			log.Warn("convertAttachments: manager not found uploader=%q file=%q title=%q (available: %v)",
-				uploader, att.File, att.Title, attachmentManagerKeys())
-			continue
-		}
-		info, err := manager.Info(ctx, fileID)
-		if err != nil {
-			log.Warn("convertAttachments: failed to get file info fileID=%q uploader=%q: %v", fileID, uploader, err)
-			continue
-		}
-		content, err := manager.Read(ctx, fileID)
-		if err != nil {
-			log.Warn("convertAttachments: failed to read file fileID=%q uploader=%q: %v", fileID, uploader, err)
-			continue
-		}
-
-		// Prefer the semantic title from the delivery agent over the raw storage filename.
-		// The storage filename may be an auto-generated zip name (e.g. output_xxx.zip),
-		// while att.Title is the human-readable name set by the delivery agent.
-		filename := info.Filename
-		if att.Title != "" {
-			// Keep the original file extension from storage so the email client
-			// knows how to open it, but use the human-readable title as the base name.
-			ext := ""
-			if idx := strings.LastIndex(info.Filename, "."); idx >= 0 {
-				ext = info.Filename[idx:]
-			}
-			titleExt := ""
-			if idx := strings.LastIndex(att.Title, "."); idx >= 0 {
-				titleExt = att.Title[idx:]
-			}
-			if titleExt != "" {
-				// Title already has an extension — use it as-is.
-				filename = att.Title
-			} else {
-				// Title has no extension — append the storage extension.
-				filename = att.Title + ext
-			}
-		}
-
-		log.Info("convertAttachments: added attachment filename=%q contentType=%q size=%d", filename, info.ContentType, len(content))
-		result = append(result, messengerTypes.Attachment{
-			Filename:    filename,
-			ContentType: info.ContentType,
-			Content:     content,
-		})
-	}
-	return result
-}
-
-// attachmentManagerKeys returns registered attachment manager names for debug logging.
-func attachmentManagerKeys() []string {
-	keys := make([]string, 0, len(attachment.Managers))
-	for k := range attachment.Managers {
-		keys = append(keys, k)
-	}
-	return keys
-}
-
-// ComputeHMACSignature computes HMAC-SHA256 signature for webhook payload.
-func ComputeHMACSignature(payload []byte, secret string) string {
-	mac := hmac.New(sha256.New, []byte(secret))
-	mac.Write(payload)
-	return hex.EncodeToString(mac.Sum(nil))
-}
-
-// VerifyHMACSignature verifies the HMAC-SHA256 signature of a webhook payload.
-func VerifyHMACSignature(payload []byte, secret, signature string) bool {
-	expected := ComputeHMACSignature(payload, secret)
-	return hmac.Equal([]byte(expected), []byte(signature))
-}

agent/robot/events/integrations/dispatcher.go

@@ -0,0 +1,229 @@
+package integrations
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/yaoapp/gou/model"
+	"github.com/yaoapp/kun/maps"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotcache "github.com/yaoapp/yao/agent/robot/cache"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+)
+
+var log = logger.New("dispatcher")
+
+// Adapter is the interface each platform adapter implements.
+type Adapter interface {
+	Apply(ctx context.Context, robot *robottypes.Robot)
+	Remove(ctx context.Context, robotID string)
+	Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error
+}
+
+// Dispatcher distributes Robot integration configs to platform adapters.
+type Dispatcher struct {
+	robotCache *robotcache.Cache
+	adapters   map[string]Adapter // key matches Integrations field: "telegram", "discord", etc.
+	stopCh     chan struct{}
+	subID      string
+}
+
+// NewDispatcher creates a Dispatcher.
+// Each adapter has a fixed key matching the field name in robottypes.Integrations.
+func NewDispatcher(cache *robotcache.Cache, adapters map[string]Adapter) *Dispatcher {
+	return &Dispatcher{
+		robotCache: cache,
+		adapters:   adapters,
+		stopCh:     make(chan struct{}),
+	}
+}
+
+// Start loads all robots and subscribes to config change events.
+func (d *Dispatcher) Start(ctx context.Context) error {
+	d.loadAll(ctx)
+
+	events.RegisterReplyFunc(d.reply)
+
+	ch := make(chan *eventtypes.Event, 64)
+	d.subID = event.Subscribe("robot.config.*", ch)
+	go d.watch(ctx, ch)
+
+	log.Info("integration dispatcher: started with %d adapters", len(d.adapters))
+	return nil
+}
+
+// reply routes a reply to the correct adapter based on channel.
+// When channel is empty (e.g. delivery), broadcasts to all adapters.
+func (d *Dispatcher) reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if metadata == nil {
+		return fmt.Errorf("no metadata in reply")
+	}
+
+	if metadata.Channel != "" {
+		adapter, ok := d.adapters[metadata.Channel]
+		if !ok {
+			return fmt.Errorf("no adapter for channel: %s", metadata.Channel)
+		}
+		return adapter.Reply(ctx, msg, metadata)
+	}
+
+	var lastErr error
+	for name, adapter := range d.adapters {
+		if err := adapter.Reply(ctx, msg, metadata); err != nil {
+			log.Error("dispatcher reply: broadcast to %s failed: %v", name, err)
+			lastErr = err
+		}
+	}
+	return lastErr
+}
+
+// Stop unsubscribes from events.
+func (d *Dispatcher) Stop() {
+	close(d.stopCh)
+	if d.subID != "" {
+		event.Unsubscribe(d.subID)
+	}
+	log.Info("integration dispatcher: stopped")
+}
+
+func (d *Dispatcher) loadAll(ctx context.Context) {
+	robots := d.loadIntegrationRobots()
+	for _, robot := range robots {
+		d.robotCache.Add(robot)
+		d.apply(ctx, robot)
+	}
+	log.Info("integration dispatcher: initial load complete, %d robots with integrations", len(robots))
+}
+
+// loadIntegrationRobots queries all active robots that have a non-null
+// robot_config (which may contain integrations). This is independent of
+// autonomous_mode so non-autonomous robots with Telegram etc. are included.
+func (d *Dispatcher) loadIntegrationRobots() []*robottypes.Robot {
+	m := model.Select("__yao.member")
+	fields := []interface{}{
+		"id", "member_id", "team_id", "display_name", "bio",
+		"system_prompt", "robot_status", "autonomous_mode",
+		"robot_config", "robot_email", "agents", "mcp_servers",
+		"manager_id", "language_model",
+	}
+
+	page := 1
+	pageSize := 100
+	var result []*robottypes.Robot
+
+	for {
+		res, err := m.Paginate(model.QueryParam{
+			Select: fields,
+			Wheres: []model.QueryWhere{
+				{Column: "member_type", Value: "robot"},
+				{Column: "status", Value: "active"},
+			},
+		}, page, pageSize)
+		if err != nil {
+			log.Error("loadIntegrationRobots: query failed page=%d: %v", page, err)
+			break
+		}
+
+		data, ok := res.Get("data").([]maps.MapStr)
+		if !ok || len(data) == 0 {
+			break
+		}
+
+		for _, record := range data {
+			robot, err := robottypes.NewRobotFromMap(map[string]interface{}(record))
+			if err != nil {
+				continue
+			}
+			if robot.Config != nil && robot.Config.Integrations != nil && len(parseIntegrations(robot.Config.Integrations)) > 0 {
+				result = append(result, robot)
+			}
+		}
+
+		total, _ := res.Get("total").(int)
+		if page*pageSize >= total {
+			break
+		}
+		page++
+	}
+
+	return result
+}
+
+// apply parses which integrations the robot has configured,
+// and calls the matching adapter for each one.
+func (d *Dispatcher) apply(ctx context.Context, robot *robottypes.Robot) {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return
+	}
+	for _, key := range parseIntegrations(robot.Config.Integrations) {
+		if adapter, ok := d.adapters[key]; ok {
+			adapter.Apply(ctx, robot)
+		}
+	}
+}
+
+func (d *Dispatcher) remove(ctx context.Context, robotID string) {
+	for _, adapter := range d.adapters {
+		adapter.Remove(ctx, robotID)
+	}
+}
+
+// parseIntegrations returns the keys of integrations present in the config.
+func parseIntegrations(intg *robottypes.Integrations) []string {
+	var keys []string
+	if intg.Telegram != nil {
+		keys = append(keys, "telegram")
+	}
+	// if intg.Discord != nil { keys = append(keys, "discord") }
+	// if intg.DingTalk != nil { keys = append(keys, "dingtalk") }
+	// if intg.Lark != nil { keys = append(keys, "lark") }
+	return keys
+}
+
+func (d *Dispatcher) watch(ctx context.Context, ch <-chan *eventtypes.Event) {
+	for {
+		select {
+		case <-d.stopCh:
+			return
+		case <-ctx.Done():
+			return
+		case ev, ok := <-ch:
+			if !ok {
+				return
+			}
+			d.dispatch(ctx, ev)
+		}
+	}
+}
+
+func (d *Dispatcher) dispatch(ctx context.Context, ev *eventtypes.Event) {
+	var payload events.RobotConfigPayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("integration dispatcher: invalid config event: %v", err)
+		return
+	}
+
+	switch ev.Type {
+	case events.RobotConfigCreated, events.RobotConfigUpdated:
+		robot := d.robotCache.Get(payload.MemberID)
+		if robot == nil {
+			rCtx := robottypes.NewContext(ctx, nil)
+			loaded, err := d.robotCache.LoadByID(rCtx, payload.MemberID)
+			if err != nil {
+				log.Warn("integration dispatcher: failed to load robot from DB member=%s: %v", payload.MemberID, err)
+				return
+			}
+			d.robotCache.Add(loaded)
+			robot = loaded
+			log.Info("integration dispatcher: loaded robot from DB member=%s", payload.MemberID)
+		}
+		d.apply(ctx, robot)
+
+	case events.RobotConfigDeleted:
+		d.remove(ctx, payload.MemberID)
+	}
+}

agent/robot/events/integrations/dispatcher_test.go

@@ -0,0 +1,282 @@
+package integrations
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotcache "github.com/yaoapp/yao/agent/robot/cache"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+)
+
+// mockAdapter records Apply/Remove calls for assertions.
+type mockAdapter struct {
+	mu      sync.Mutex
+	applied []*robottypes.Robot
+	removed []string
+}
+
+func (m *mockAdapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.applied = append(m.applied, robot)
+}
+
+func (m *mockAdapter) Remove(ctx context.Context, robotID string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.removed = append(m.removed, robotID)
+}
+
+func (m *mockAdapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	return nil
+}
+
+func (m *mockAdapter) getApplied() []*robottypes.Robot {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := make([]*robottypes.Robot, len(m.applied))
+	copy(cp, m.applied)
+	return cp
+}
+
+func (m *mockAdapter) getRemoved() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := make([]string, len(m.removed))
+	copy(cp, m.removed)
+	return cp
+}
+
+// noopHandler satisfies event.Handler so we can register "robot" prefix for Push/Call.
+type noopHandler struct{}
+
+func (h *noopHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	if ev.IsCall {
+		resp <- eventtypes.Result{}
+	}
+}
+func (h *noopHandler) Shutdown(ctx context.Context) error { return nil }
+
+var eventOnce sync.Once
+
+func setupEventBus(t *testing.T) {
+	t.Helper()
+	eventOnce.Do(func() {
+		event.Register("robot", &noopHandler{})
+	})
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	t.Cleanup(func() { _ = event.Stop(context.Background()) })
+}
+
+func newRobot(memberID, teamID string, intg *robottypes.Integrations) *robottypes.Robot {
+	return &robottypes.Robot{
+		MemberID:       memberID,
+		TeamID:         teamID,
+		AutonomousMode: true,
+		Config: &robottypes.Config{
+			Integrations: intg,
+		},
+	}
+}
+
+func TestLoadAll_OnlyTelegramConfigured(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgRobot := newRobot("r-tg", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	noIntgRobot := newRobot("r-plain", "team1", nil)
+	cache.Add(tgRobot)
+	cache.Add(noIntgRobot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	applied := tgAdapter.getApplied()
+	assert.Len(t, applied, 1)
+	assert.Equal(t, "r-tg", applied[0].MemberID)
+}
+
+func TestLoadAll_NoIntegrations(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	cache.Add(newRobot("r1", "team1", nil))
+	cache.Add(&robottypes.Robot{MemberID: "r2", TeamID: "team1"})
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Empty(t, tgAdapter.getApplied())
+}
+
+func TestLoadAll_MultipleAdapters(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	// Only Telegram configured, no Discord
+	robot := newRobot("r-multi", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	discordAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{
+		"telegram": tgAdapter,
+		"discord":  discordAdapter,
+	})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Len(t, tgAdapter.getApplied(), 1)
+	assert.Empty(t, discordAdapter.getApplied(), "discord adapter should not be called")
+}
+
+func TestConfigCreated_TriggersApply(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Empty(t, tgAdapter.getApplied())
+
+	// Simulate: robot created with Telegram config, added to cache, event pushed
+	robot := newRobot("r-new", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "new-tok"},
+	})
+	cache.Add(robot)
+	event.Push(context.Background(), events.RobotConfigCreated, events.RobotConfigPayload{
+		MemberID: "r-new", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getApplied()) == 1
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "r-new", tgAdapter.getApplied()[0].MemberID)
+}
+
+func TestConfigUpdated_TriggersApply(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	robot := newRobot("r-upd", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "old-tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	// Initial load
+	assert.Len(t, tgAdapter.getApplied(), 1)
+
+	// Update config in cache
+	robot.Config.Integrations.Telegram.BotToken = "new-tok"
+	event.Push(context.Background(), events.RobotConfigUpdated, events.RobotConfigPayload{
+		MemberID: "r-upd", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getApplied()) == 2
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "new-tok", tgAdapter.getApplied()[1].Config.Integrations.Telegram.BotToken)
+}
+
+func TestConfigDeleted_TriggersRemove(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	robot := newRobot("r-del", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Len(t, tgAdapter.getApplied(), 1)
+
+	event.Push(context.Background(), events.RobotConfigDeleted, events.RobotConfigPayload{
+		MemberID: "r-del", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getRemoved()) == 1
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "r-del", tgAdapter.getRemoved()[0])
+}
+
+func TestConfigCreated_RobotNotInCache(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	// Push event but don't add robot to cache
+	event.Push(context.Background(), events.RobotConfigCreated, events.RobotConfigPayload{
+		MemberID: "r-ghost", TeamID: "team1",
+	})
+
+	time.Sleep(200 * time.Millisecond)
+	assert.Empty(t, tgAdapter.getApplied())
+}
+
+func TestParseIntegrations(t *testing.T) {
+	tests := []struct {
+		name     string
+		intg     *robottypes.Integrations
+		expected []string
+	}{
+		{"nil", nil, nil},
+		{"empty", &robottypes.Integrations{}, nil},
+		{"telegram only", &robottypes.Integrations{
+			Telegram: &robottypes.TelegramConfig{Enabled: true},
+		}, []string{"telegram"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.intg == nil {
+				return
+			}
+			result := parseIntegrations(tt.intg)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

agent/robot/events/integrations/telegram/dedup.go

@@ -0,0 +1,48 @@
+package telegram
+
+import (
+	"sync"
+	"time"
+)
+
+const (
+	dedupTTL           = 24 * time.Hour
+	dedupCleanInterval = time.Hour
+)
+
+// dedupStore is a lightweight in-memory deduplication store with TTL.
+// Used for message-level dedup (same update_id won't be processed twice).
+type dedupStore struct {
+	m sync.Map // key -> int64 (unix timestamp)
+}
+
+func newDedupStore() *dedupStore {
+	return &dedupStore{}
+}
+
+// markSeen returns true if this is the first time the key is seen.
+func (d *dedupStore) markSeen(key string) bool {
+	now := time.Now().Unix()
+	_, loaded := d.m.LoadOrStore(key, now)
+	return !loaded
+}
+
+// cleaner periodically removes expired entries. Runs until stopCh is closed.
+func (d *dedupStore) cleaner(stopCh <-chan struct{}) {
+	ticker := time.NewTicker(dedupCleanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-stopCh:
+			return
+		case <-ticker.C:
+			cutoff := time.Now().Add(-dedupTTL).Unix()
+			d.m.Range(func(key, value any) bool {
+				if ts, ok := value.(int64); ok && ts < cutoff {
+					d.m.Delete(key)
+				}
+				return true
+			})
+		}
+	}
+}

agent/robot/events/integrations/telegram/e2e_test.go

@@ -0,0 +1,354 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/yaoapp/gou/model"
+	"github.com/yaoapp/xun/capsule"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/agent/testutils"
+	"github.com/yaoapp/yao/event"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+var (
+	tgBotToken string
+	tgHost     string
+)
+
+func TestMain(m *testing.M) {
+	tgBotToken = os.Getenv("TELEGRAM_TEST_BOT_TOKEN")
+	tgHost = os.Getenv("TELEGRAM_TEST_HOST")
+	os.Exit(m.Run())
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if tgBotToken == "" {
+		t.Skip("TELEGRAM_TEST_BOT_TOKEN not set")
+	}
+}
+
+func newTestBot() *tgapi.Bot {
+	var opts []tgapi.BotOption
+	if tgHost != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgHost))
+	}
+	return tgapi.NewBot(tgBotToken, "", opts...)
+}
+
+// confirmPendingUpdates checks if there are pending updates from previous seeds.
+func confirmPendingUpdates(t *testing.T) []*tgapi.ConvertedMessage {
+	t.Helper()
+	b := newTestBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	msgs, err := b.GetUpdates(ctx, 0, 5, nil)
+	require.NoError(t, err)
+	return msgs
+}
+
+// TestE2E_Adapter_Apply verifies that Apply correctly registers a bot.
+func TestE2E_Adapter_Apply(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_tg_adapter",
+		TeamID:   "team_e2e_tg",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Telegram: &robottypes.TelegramConfig{
+					Enabled:  true,
+					BotToken: tgBotToken,
+					Host:     tgHost,
+					AppID:    "e2e-test-app",
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+
+	a.mu.RLock()
+	entry, ok := a.bots["robot_e2e_tg_adapter"]
+	a.mu.RUnlock()
+
+	require.True(t, ok, "bot should be registered")
+	assert.Equal(t, tgBotToken, entry.bot.Token())
+	assert.Equal(t, "e2e-test-app", entry.appID)
+
+	// Verify GetMe works through the registered bot
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	me, err := entry.bot.GetMe(ctx)
+	require.NoError(t, err)
+	assert.True(t, me.IsBot)
+	t.Logf("OK  Apply: bot registered id=%d username=%s", me.ID, me.Username)
+
+	// Verify ResolveBot
+	resolved := a.ResolveBot("e2e-test-app")
+	require.NotNil(t, resolved)
+	assert.Equal(t, tgBotToken, resolved.Token())
+}
+
+// TestE2E_Adapter_Apply_Update verifies that Apply with a different token replaces the bot.
+func TestE2E_Adapter_Apply_Update(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_tg_update",
+		TeamID:   "team_e2e_tg",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Telegram: &robottypes.TelegramConfig{
+					Enabled:  true,
+					BotToken: tgBotToken,
+					Host:     tgHost,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_tg_update"]
+	a.mu.RUnlock()
+	require.True(t, ok)
+
+	// Apply again with same token — should be a no-op
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	assert.Len(t, a.bots, 1)
+	a.mu.RUnlock()
+
+	// Remove
+	a.Remove(context.Background(), "robot_e2e_tg_update")
+	a.mu.RLock()
+	_, ok = a.bots["robot_e2e_tg_update"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "bot should be removed")
+	t.Log("OK  Apply/Remove lifecycle verified")
+}
+
+// TestE2E_Adapter_PollAll verifies that pollAll fetches updates from Telegram
+// and processes them through handleMessages.
+func TestE2E_Adapter_PollAll(t *testing.T) {
+	skipIfNoToken(t)
+	testutils.Prepare(t)
+	defer testutils.Clean(t)
+
+	pending := confirmPendingUpdates(t)
+	if len(pending) == 0 {
+		t.Skip("no pending updates; run integrations/telegram seed first")
+	}
+	t.Logf("found %d pending updates", len(pending))
+
+	// Create adapter WITHOUT auto-starting pollLoop
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	memberID := "robot_e2e_tg_poll"
+	setupTestRobot(t, memberID)
+	defer cleanupTestRobots(t)
+
+	var opts []tgapi.BotOption
+	if tgHost != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgHost))
+	}
+	a.bots[memberID] = &botEntry{
+		robotID: memberID,
+		appID:   "e2e-poll-app",
+		bot:     tgapi.NewBot(tgBotToken, "", opts...),
+	}
+
+	// Start event bus so event.Push works
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	defer func() { _ = event.Stop(context.Background()) }()
+
+	// Manually trigger one poll cycle
+	a.pollAll()
+
+	// Verify offset advanced (meaning updates were processed)
+	a.mu.RLock()
+	entry := a.bots[memberID]
+	a.mu.RUnlock()
+	assert.Greater(t, entry.offset, int64(0), "offset should have advanced after processing updates")
+	t.Logf("OK  pollAll: offset advanced to %d", entry.offset)
+}
+
+// TestE2E_Adapter_Dedup verifies that duplicate messages are not processed twice.
+func TestE2E_Adapter_Dedup(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	key := "tg:test-robot:12345"
+	assert.True(t, a.dedup.markSeen(key), "first time should return true")
+	assert.False(t, a.dedup.markSeen(key), "second time should return false (dedup)")
+	t.Log("OK  dedup working correctly")
+}
+
+// TestE2E_Adapter_HandleMessages_Integration verifies the full flow:
+// GetUpdates → ConvertedMessage → handleMessages → event.Push
+func TestE2E_Adapter_HandleMessages_Integration(t *testing.T) {
+	skipIfNoToken(t)
+	testutils.Prepare(t)
+	defer testutils.Clean(t)
+
+	b := newTestBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	msgs, err := b.GetUpdates(ctx, 0, 5, nil)
+	require.NoError(t, err)
+	if len(msgs) == 0 {
+		t.Skip("no pending updates; run integrations/telegram seed first")
+	}
+
+	memberID := "robot_e2e_tg_handle"
+	setupTestRobot(t, memberID)
+	defer cleanupTestRobots(t)
+
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	defer func() { _ = event.Stop(context.Background()) }()
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	entry := &botEntry{
+		robotID: memberID,
+		appID:   "e2e-handle-app",
+		bot:     b,
+	}
+
+	// Group all messages by chatID (like pollAll does) and process each group
+	grouped := groupByChatID(msgs)
+	for chatID, chatMsgs := range grouped {
+		t.Logf("processing chat=%d messages=%d", chatID, len(chatMsgs))
+		for _, cm := range chatMsgs {
+			t.Logf("  update_id=%d msg_id=%d text=%q media=%d",
+				cm.UpdateID, cm.MessageID, truncate(cm.Text, 40), len(cm.MediaItems))
+		}
+		a.handleMessages(ctx, entry, chatMsgs)
+	}
+
+	// Verify dedup: all updates should be marked as seen
+	cm := msgs[0]
+	assert.False(t, a.dedup.markSeen(fmt.Sprintf("tg:%s:%d", memberID, cm.UpdateID)),
+		"update should be marked as seen after handleMessages")
+
+	// Second call with same messages should be fully deduped (no-op)
+	a.handleMessages(ctx, entry, msgs)
+	t.Logf("OK  handleMessages processed %d updates across %d chats", len(msgs), len(grouped))
+}
+
+// ==================== Helpers ====================
+
+func setupTestRobot(t *testing.T, memberID string) {
+	t.Helper()
+	m := model.Select("__yao.member")
+	if m == nil {
+		t.Skip("__yao.member model not loaded")
+	}
+	qb := capsule.Query()
+
+	robotConfig := map[string]interface{}{
+		"identity": map[string]interface{}{
+			"role":   "Telegram E2E Test Robot",
+			"duties": []string{"Process Telegram messages"},
+		},
+		"integrations": map[string]interface{}{
+			"telegram": map[string]interface{}{
+				"enabled":   true,
+				"bot_token": tgBotToken,
+				"host":      tgHost,
+				"app_id":    "e2e-tg-app-" + memberID,
+			},
+		},
+		"resources": map[string]interface{}{
+			"phases": map[string]interface{}{
+				"host": "robot.host",
+			},
+		},
+	}
+	configJSON, _ := json.Marshal(robotConfig)
+
+	err := qb.Table(m.MetaData.Table.Name).Insert([]map[string]interface{}{
+		{
+			"member_id":       memberID,
+			"team_id":         "team_e2e_tg",
+			"member_type":     "robot",
+			"display_name":    "E2E TG Adapter Test " + memberID,
+			"system_prompt":   "You are a test robot for Telegram adapter E2E testing.",
+			"status":          "active",
+			"role_id":         "member",
+			"autonomous_mode": false,
+			"robot_status":    "idle",
+			"robot_config":    string(configJSON),
+		},
+	})
+	if err != nil {
+		t.Fatalf("setup robot %s: %v", memberID, err)
+	}
+}
+
+func cleanupTestRobots(t *testing.T) {
+	t.Helper()
+	m := model.Select("__yao.member")
+	if m == nil {
+		return
+	}
+	qb := capsule.Query()
+	_, _ = qb.Table(m.MetaData.Table.Name).Where("member_id", "like", "robot_e2e_tg%").Delete()
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}

agent/robot/events/integrations/telegram/message.go

@@ -0,0 +1,136 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/event"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+// handleMessages builds a single event payload from a batch of ConvertedMessages
+// belonging to the same chat. Consecutive user messages are merged into one to
+// keep the messages array clean for the LLM.
+func (a *Adapter) handleMessages(ctx context.Context, entry *botEntry, cms []*tgapi.ConvertedMessage) {
+	if len(cms) == 0 {
+		return
+	}
+
+	var allParts []interface{}
+	var lastCM *tgapi.ConvertedMessage
+
+	for _, cm := range cms {
+		if cm == nil {
+			continue
+		}
+
+		if isBotCommand(cm) {
+			continue
+		}
+
+		dedupKey := fmt.Sprintf("tg:%s:%d", entry.robotID, cm.UpdateID)
+		if !a.dedup.markSeen(dedupKey) {
+			continue
+		}
+
+		parts := buildContentParts(cm)
+		if len(parts) == 0 {
+			continue
+		}
+
+		allParts = append(allParts, parts...)
+		lastCM = cm
+	}
+
+	if len(allParts) == 0 || lastCM == nil {
+		return
+	}
+
+	content := mergeContentParts(allParts)
+
+	msgPayload := events.MessagePayload{
+		RobotID: entry.robotID,
+		Messages: []agentcontext.Message{
+			{Role: agentcontext.RoleUser, Content: content},
+		},
+		Metadata: &events.MessageMetadata{
+			Channel:    "telegram",
+			MessageID:  strconv.FormatInt(lastCM.UpdateID, 10),
+			AppID:      entry.appID,
+			ChatID:     strconv.FormatInt(lastCM.ChatID, 10),
+			SenderID:   strconv.FormatInt(lastCM.SenderID, 10),
+			SenderName: lastCM.SenderName,
+			Locale:     events.NormalizeLocale(lastCM.LanguageCode),
+			Extra: map[string]any{
+				"tg_message_id": lastCM.MessageID,
+			},
+		},
+	}
+
+	if _, err := event.Push(ctx, events.Message, msgPayload); err != nil {
+		log.Error("telegram adapter: event.Push robot.message failed robot=%s: %v", entry.robotID, err)
+	}
+}
+
+// buildContentParts extracts content parts from a single ConvertedMessage.
+func buildContentParts(cm *tgapi.ConvertedMessage) []interface{} {
+	var parts []interface{}
+
+	if cm.HasText() {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": cm.Text,
+		})
+	}
+
+	for _, mi := range cm.MediaItems {
+		if mi.Wrapper == "" {
+			continue
+		}
+		parts = append(parts, map[string]interface{}{
+			"type":      "file",
+			"file_url":  mi.Wrapper,
+			"mime_type": mi.MimeType,
+			"file_name": mi.FileName,
+		})
+	}
+
+	return parts
+}
+
+// mergeContentParts merges collected parts into a single content value.
+// If all parts are text-only, they are joined with newlines into a plain string.
+// Otherwise the full parts array is returned.
+func mergeContentParts(parts []interface{}) interface{} {
+	allText := true
+	for _, p := range parts {
+		m, ok := p.(map[string]interface{})
+		if !ok || m["type"] != "text" {
+			allText = false
+			break
+		}
+	}
+
+	if allText {
+		var buf strings.Builder
+		for i, p := range parts {
+			if i > 0 {
+				buf.WriteString("\n")
+			}
+			m := p.(map[string]interface{})
+			buf.WriteString(m["text"].(string))
+		}
+		return buf.String()
+	}
+
+	return parts
+}
+
+// isBotCommand returns true if the message is a Telegram bot command (text starting with "/").
+func isBotCommand(cm *tgapi.ConvertedMessage) bool {
+	return !cm.HasMedia() && strings.HasPrefix(strings.TrimSpace(cm.Text), "/")
+}

agent/robot/events/integrations/telegram/polling.go

@@ -0,0 +1,89 @@
+package telegram
+
+import (
+	"context"
+	"time"
+
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+const (
+	pollInterval = 60 * time.Second
+	pollTimeout  = 30 // seconds, Telegram long-polling timeout per request
+)
+
+// pollLoop runs a single goroutine that iterates all registered bots
+// every pollInterval, calling getUpdates for each one sequentially.
+func (a *Adapter) pollLoop() {
+	log.Info("pollLoop started, interval=%s", pollInterval)
+	a.pollAll()
+
+	ticker := time.NewTicker(pollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-a.stopCh:
+			log.Info("pollLoop stopped")
+			return
+		case <-ticker.C:
+			a.pollAll()
+		}
+	}
+}
+
+func (a *Adapter) pollAll() {
+	entries := a.snapshot()
+	log.Debug("pollAll bots=%d", len(entries))
+	if len(entries) == 0 {
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), pollInterval)
+	defer cancel()
+
+	for _, entry := range entries {
+		select {
+		case <-a.stopCh:
+			return
+		default:
+		}
+
+		log.Debug("polling robot=%s offset=%d", entry.robotID, entry.offset)
+		groups := []string{"telegram", entry.robotID}
+		msgs, err := entry.bot.GetUpdates(ctx, entry.offset, pollTimeout, groups)
+		if err != nil {
+			log.Error("getUpdates failed robot=%s: %v", entry.robotID, err)
+			continue
+		}
+
+		if len(msgs) == 0 {
+			continue
+		}
+
+		// Advance offset for all received messages
+		for _, cm := range msgs {
+			if cm.UpdateID >= entry.offset {
+				entry.offset = cm.UpdateID + 1
+			}
+		}
+
+		// Group by chatID, preserving order
+		grouped := groupByChatID(msgs)
+		log.Info("robot=%s got %d updates in %d chats", entry.robotID, len(msgs), len(grouped))
+
+		for chatID, chatMsgs := range grouped {
+			log.Debug("robot=%s chat=%d messages=%d", entry.robotID, chatID, len(chatMsgs))
+			a.handleMessages(ctx, entry, chatMsgs)
+		}
+	}
+}
+
+// groupByChatID groups messages by chat ID, preserving chronological order.
+func groupByChatID(msgs []*tgapi.ConvertedMessage) map[int64][]*tgapi.ConvertedMessage {
+	grouped := make(map[int64][]*tgapi.ConvertedMessage)
+	for _, cm := range msgs {
+		grouped[cm.ChatID] = append(grouped[cm.ChatID], cm)
+	}
+	return grouped
+}

agent/robot/events/integrations/telegram/reply.go

@@ -0,0 +1,181 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+// Reply sends the assistant message back to the originating Telegram chat.
+// Content may be a plain string or []ContentPart (text, image_url, file, etc.).
+// Each adapter is responsible for interpreting the standard message format.
+func (a *Adapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if msg == nil || metadata == nil {
+		return fmt.Errorf("nil message or metadata")
+	}
+
+	chatID, err := strconv.ParseInt(metadata.ChatID, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid chat_id %q: %w", metadata.ChatID, err)
+	}
+
+	var replyTo int64
+	if metadata.Extra != nil {
+		if v, ok := metadata.Extra["tg_message_id"]; ok {
+			switch id := v.(type) {
+			case int64:
+				replyTo = id
+			case float64:
+				replyTo = int64(id)
+			}
+		}
+	}
+
+	entry := a.resolveByChat(metadata)
+	if entry == nil {
+		return fmt.Errorf("no bot registered for channel metadata (appID=%s)", metadata.AppID)
+	}
+
+	return a.sendContent(ctx, entry.bot, chatID, replyTo, msg.Content)
+}
+
+// sendContent dispatches based on the Content type.
+func (a *Adapter) sendContent(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, content interface{}) error {
+	switch c := content.(type) {
+	case string:
+		if strings.TrimSpace(c) == "" {
+			return nil
+		}
+		return bot.SendMessage(ctx, chatID, c, replyTo)
+
+	case []interface{}:
+		return a.sendParts(ctx, bot, chatID, replyTo, c)
+
+	default:
+		parts, ok := toContentParts(content)
+		if ok {
+			return a.sendPartsTyped(ctx, bot, chatID, replyTo, parts)
+		}
+		return bot.SendMessage(ctx, chatID, fmt.Sprintf("%v", content), replyTo)
+	}
+}
+
+// sendParts handles []interface{} content parts (common from JSON unmarshalling).
+func (a *Adapter) sendParts(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, parts []interface{}) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		m, ok := part.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		partType, _ := m["type"].(string)
+		switch partType {
+		case "text":
+			if text, ok := m["text"].(string); ok {
+				textBuf.WriteString(text)
+			}
+		case "image_url":
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if imgMap, ok := m["image_url"].(map[string]interface{}); ok {
+				if url, ok := imgMap["url"].(string); ok {
+					if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, url, ""); err != nil {
+						log.Error("telegram reply: send image: %v", err)
+					}
+				}
+			}
+		case "file":
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if fileMap, ok := m["file"].(map[string]interface{}); ok {
+				url, _ := fileMap["url"].(string)
+				filename, _ := fileMap["filename"].(string)
+				if url != "" {
+					if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, url, filename); err != nil {
+						log.Error("telegram reply: send file: %v", err)
+					}
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, bot, chatID, replyTo, &textBuf)
+}
+
+// sendPartsTyped handles typed []agentcontext.ContentPart slices.
+func (a *Adapter) sendPartsTyped(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, parts []agentcontext.ContentPart) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		switch part.Type {
+		case agentcontext.ContentText:
+			textBuf.WriteString(part.Text)
+		case agentcontext.ContentImageURL:
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if part.ImageURL != nil {
+				if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, part.ImageURL.URL, ""); err != nil {
+					log.Error("telegram reply: send image: %v", err)
+				}
+			}
+		case agentcontext.ContentFile:
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if part.File != nil {
+				if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, part.File.URL, part.File.Filename); err != nil {
+					log.Error("telegram reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, bot, chatID, replyTo, &textBuf)
+}
+
+func (a *Adapter) flushText(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, buf *strings.Builder) error {
+	if buf.Len() == 0 {
+		return nil
+	}
+	err := bot.SendMessage(ctx, chatID, buf.String(), replyTo)
+	buf.Reset()
+	return err
+}
+
+// sendFileOrWrapper sends a file from a wrapper (__yao.attachment://xxx) or URL.
+func sendFileOrWrapper(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, url, caption string) error {
+	if strings.Contains(url, "://") && !strings.HasPrefix(url, "http") {
+		return bot.SendMedia(ctx, chatID, url, caption, replyTo)
+	}
+	if strings.HasPrefix(url, "http") {
+		mediaType := tgapi.DetectMediaType("")
+		return bot.SendMediaByURL(ctx, chatID, mediaType, url, caption, replyTo)
+	}
+	return fmt.Errorf("unsupported file URL scheme: %s", url)
+}
+
+// toContentParts tries to type-assert content to []agentcontext.ContentPart.
+func toContentParts(content interface{}) ([]agentcontext.ContentPart, bool) {
+	parts, ok := content.([]agentcontext.ContentPart)
+	return parts, ok
+}
+
+// resolveByChat finds the bot entry matching the metadata.
+func (a *Adapter) resolveByChat(metadata *events.MessageMetadata) *botEntry {
+	if metadata.AppID != "" {
+		if entry, ok := a.resolveByAppID(metadata.AppID); ok {
+			return entry
+		}
+	}
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	for _, entry := range a.bots {
+		return entry
+	}
+	return nil
+}

agent/robot/events/integrations/telegram/telegram.go

@@ -0,0 +1,159 @@
+package telegram
+
+import (
+	"context"
+	"sync"
+
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+var log = logger.New("telegram")
+
+// Adapter implements the integrations.Adapter interface for Telegram Bot API.
+//
+// Architecture:
+//   - One polling goroutine (ticker) iterates all registered bots every 60s
+//   - One webhook goroutine listens to integration.webhook.telegram events
+//   - One dedup cleaner goroutine removes expired keys every hour
+type Adapter struct {
+	mu      sync.RWMutex
+	bots    map[string]*botEntry // robotID -> *botEntry
+	appIdx  map[string]string    // appID  -> robotID (webhook routing)
+	dedup   *dedupStore
+	webhSub string
+	stopCh  chan struct{}
+}
+
+// botEntry holds the state for one robot's Telegram integration.
+type botEntry struct {
+	robotID string
+	appID   string
+	bot     *tgapi.Bot // bound to this robot's token
+	offset  int64      // polling offset
+}
+
+// NewAdapter creates a new Telegram adapter.
+func NewAdapter() *Adapter {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	go a.dedup.cleaner(a.stopCh)
+	go a.pollLoop()
+	return a
+}
+
+// Apply is called by the Dispatcher when a robot config is created or updated.
+func (a *Adapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	tgConf := extractConfig(robot)
+	log.Debug("Apply robot=%s tgConf=%v", robot.MemberID, tgConf != nil)
+	if tgConf != nil {
+		log.Debug("Apply robot=%s enabled=%v token_len=%d host=%q",
+			robot.MemberID, tgConf.Enabled, len(tgConf.BotToken), tgConf.Host)
+	}
+
+	if tgConf == nil || !tgConf.Enabled || tgConf.BotToken == "" {
+		a.removeBot(robot.MemberID)
+		return
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if existing, ok := a.bots[robot.MemberID]; ok {
+		if existing.bot.Token() == tgConf.BotToken {
+			return
+		}
+		a.removeBotLocked(robot.MemberID)
+	}
+
+	var opts []tgapi.BotOption
+	if tgConf.Host != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgConf.Host))
+	}
+	entry := &botEntry{
+		robotID: robot.MemberID,
+		appID:   tgConf.AppID,
+		bot:     tgapi.NewBot(tgConf.BotToken, tgConf.WebhookSecret, opts...),
+	}
+	a.bots[robot.MemberID] = entry
+	if tgConf.AppID != "" {
+		a.appIdx[tgConf.AppID] = robot.MemberID
+	}
+	log.Info("telegram adapter: registered robot=%s", robot.MemberID)
+}
+
+// Remove is called by the Dispatcher when a robot is deleted.
+func (a *Adapter) Remove(ctx context.Context, robotID string) {
+	a.removeBot(robotID)
+}
+
+// Shutdown stops the polling loop, webhook subscription, and dedup cleaner.
+func (a *Adapter) Shutdown() {
+	close(a.stopCh)
+	a.StopWebhookSubscription()
+	log.Info("telegram adapter: shutdown complete")
+}
+
+// ResolveBot returns the tgapi.Bot for a given appID, used by the webhook
+// verification layer. Returns nil if not found.
+func (a *Adapter) ResolveBot(appID string) *tgapi.Bot {
+	entry, ok := a.resolveByAppID(appID)
+	if !ok {
+		return nil
+	}
+	return entry.bot
+}
+
+// --- Bot registry ---
+
+func (a *Adapter) removeBot(robotID string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.removeBotLocked(robotID)
+}
+
+func (a *Adapter) removeBotLocked(robotID string) {
+	entry, ok := a.bots[robotID]
+	if !ok {
+		return
+	}
+	if entry.appID != "" {
+		delete(a.appIdx, entry.appID)
+	}
+	delete(a.bots, robotID)
+	log.Info("telegram adapter: unregistered robot=%s", robotID)
+}
+
+// snapshot returns a copy of all bot entries for safe iteration outside the lock.
+func (a *Adapter) snapshot() []*botEntry {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	list := make([]*botEntry, 0, len(a.bots))
+	for _, entry := range a.bots {
+		list = append(list, entry)
+	}
+	return list
+}
+
+func (a *Adapter) resolveByAppID(appID string) (*botEntry, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	robotID, ok := a.appIdx[appID]
+	if !ok {
+		return nil, false
+	}
+	entry, ok := a.bots[robotID]
+	return entry, ok
+}
+
+func extractConfig(robot *robottypes.Robot) *robottypes.TelegramConfig {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return nil
+	}
+	return robot.Config.Integrations.Telegram
+}

agent/robot/events/integrations/telegram/webhook.go

@@ -0,0 +1,65 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+	webhooktypes "github.com/yaoapp/yao/openapi/integrations"
+)
+
+// StartWebhookSubscription subscribes to integration.webhook.telegram events.
+// Call once after event.Start().
+func (a *Adapter) StartWebhookSubscription() {
+	ch := make(chan *eventtypes.Event, 128)
+	a.webhSub = event.Subscribe("integration.webhook.telegram", ch)
+	go a.handleWebhooks(ch)
+	log.Info("telegram adapter: webhook subscription started")
+}
+
+// StopWebhookSubscription unsubscribes from webhook events.
+func (a *Adapter) StopWebhookSubscription() {
+	if a.webhSub != "" {
+		event.Unsubscribe(a.webhSub)
+		a.webhSub = ""
+	}
+}
+
+func (a *Adapter) handleWebhooks(ch <-chan *eventtypes.Event) {
+	for ev := range ch {
+		var payload webhooktypes.WebhookPayload
+		if err := ev.Should(&payload); err != nil {
+			log.Error("telegram adapter: invalid webhook event: %v", err)
+			continue
+		}
+
+		entry, ok := a.resolveByAppID(payload.AppID)
+		if !ok {
+			log.Warn("telegram adapter: unknown app_id=%s", payload.AppID)
+			continue
+		}
+
+		headerSecret := payload.Headers["X-Telegram-Bot-Api-Secret-Token"]
+		if !entry.bot.VerifyWebhook(headerSecret) {
+			log.Warn("telegram adapter: webhook secret mismatch app_id=%s", payload.AppID)
+			continue
+		}
+
+		var update models.Update
+		if err := json.Unmarshal(payload.Body, &update); err != nil {
+			log.Error("telegram adapter: webhook unmarshal failed: %v", err)
+			continue
+		}
+
+		cm := tgapi.ConvertUpdate(&update)
+		if cm != nil && cm.HasMedia() {
+			groups := []string{"telegram", entry.robotID}
+			ctx := context.Background()
+			entry.bot.ResolveMedia(ctx, cm, groups)
+		}
+		a.handleMessages(context.Background(), entry, []*tgapi.ConvertedMessage{cm})
+	}
+}

agent/robot/events/log.go

@@ -0,0 +1,5 @@
+package events
+
+import "github.com/yaoapp/yao/agent/robot/logger"
+
+var log = logger.New("events")

agent/robot/events/message.go

@@ -0,0 +1,240 @@
+package events
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agent "github.com/yaoapp/yao/agent"
+	"github.com/yaoapp/yao/agent/assistant"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotstore "github.com/yaoapp/yao/agent/robot/store"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	oauthtypes "github.com/yaoapp/yao/openapi/oauth/types"
+)
+
+// handleMessage processes messages from external integrations (Telegram, etc.).
+// It calls the Host Agent with the provided messages and returns a MessageResult.
+// Action detection is done via the Host Agent's Next hook return value.
+func (h *robotHandler) handleMessage(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	var payload MessagePayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("message handler: invalid payload: %v", err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	log.Info("message handler: robot=%s channel=%s msg_id=%s",
+		payload.RobotID, payload.Metadata.Channel, payload.Metadata.MessageID)
+
+	result, err := callHostAgent(ctx, &payload)
+	if err != nil {
+		log.Error("message handler: host agent call failed robot=%s: %v", payload.RobotID, err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	if reply := getReplyFunc(); reply != nil && result.Message != nil {
+		if err := reply(ctx, result.Message, payload.Metadata); err != nil {
+			log.Error("message handler: reply failed robot=%s channel=%s: %v",
+				payload.RobotID, payload.Metadata.Channel, err)
+		}
+	}
+
+	if ev.IsCall {
+		resp <- eventtypes.Result{Data: result}
+	}
+}
+
+// callHostAgent resolves the Host Agent for the robot and calls it with messages.
+// This avoids importing executor/standard to prevent import cycles; instead it
+// calls the assistant directly via assistant.Get + ast.Stream (same as AgentCaller.Call).
+func callHostAgent(ctx context.Context, payload *MessagePayload) (*MessageResult, error) {
+	hostID, record, err := resolveHostAssistantID(ctx, payload.RobotID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve host agent: %w", err)
+	}
+
+	ast, err := assistant.Get(hostID)
+	if err != nil {
+		return nil, fmt.Errorf("assistant not found: %s: %w", hostID, err)
+	}
+
+	opts := &agentcontext.Options{
+		Skip: &agentcontext.Skip{
+			Search: false,
+		},
+	}
+
+	authorized := &oauthtypes.AuthorizedInfo{
+		UserID: payload.Metadata.SenderID,
+	}
+	chatID := fmt.Sprintf("%s:%s", payload.Metadata.Channel, payload.Metadata.ChatID)
+	agentCtx := agentcontext.New(ctx, authorized, chatID)
+	agentCtx.AssistantID = hostID
+	agentCtx.Referer = "integration"
+	agentCtx.Locale = payload.Metadata.Locale
+	agentCtx.Metadata = map[string]interface{}{
+		"robot_id": payload.RobotID,
+		"channel":  payload.Metadata.Channel,
+	}
+
+	if dsl := agent.GetAgent(); dsl != nil {
+		if cache, err := dsl.GetCacheStore(); err == nil {
+			agentCtx.Cache = cache
+		}
+	}
+
+	defer agentCtx.Release()
+
+	response, err := ast.Stream(agentCtx, payload.Messages, opts)
+	if err != nil {
+		return nil, fmt.Errorf("host agent call failed: %w", err)
+	}
+
+	result := &MessageResult{
+		Metadata: payload.Metadata,
+	}
+
+	if response.Completion != nil {
+		result.Message = &agentcontext.Message{
+			Role:    agentcontext.RoleAssistant,
+			Content: response.Completion.Content,
+		}
+	}
+
+	// Detect action from Next hook return value
+	log.Debug("response.Next type=%T value=%+v", response.Next, response.Next)
+	if action := detectAction(response.Next); action != nil {
+		log.Info("action detected: name=%s payload=%+v", action.Name, action.Payload)
+		result.Action = action
+		if action.Name == "robot.execute" {
+			if execID := executeAction(ctx, payload, record, action); execID != "" {
+				result.ExecutionID = execID
+				result.Message = &agentcontext.Message{
+					Role:    agentcontext.RoleAssistant,
+					Content: taskDeployedMessage(execID, payload.Metadata.Locale),
+				}
+			}
+		}
+	} else {
+		log.Debug("no action detected from response.Next")
+	}
+
+	return result, nil
+}
+
+// executeAction triggers robot execution when the Host Agent returns a
+// confirmed action. Uses the injected TriggerFunc to call robotapi.TriggerManual
+// without creating a circular import.
+func executeAction(ctx context.Context, payload *MessagePayload, record *robotstore.RobotRecord, action *ActionResult) string {
+	trigger := getTriggerFunc()
+	if trigger == nil {
+		log.Warn("message handler: trigger func not registered, cannot execute action for robot=%s", payload.RobotID)
+		return ""
+	}
+
+	data, _ := action.Payload.(map[string]interface{})
+	goals, _ := data["goals"].(string)
+	if goals == "" {
+		log.Warn("message handler: confirmed action has no goals, robot=%s", payload.RobotID)
+		return ""
+	}
+
+	triggerData := &robottypes.TriggerInput{
+		Data: map[string]interface{}{
+			"goals":   goals,
+			"channel": payload.Metadata.Channel,
+			"chat_id": payload.Metadata.ChatID,
+			"extra":   payload.Metadata.Extra,
+		},
+	}
+
+	authorized := &oauthtypes.AuthorizedInfo{
+		UserID: record.MemberID,
+		TeamID: record.TeamID,
+	}
+	rCtx := robottypes.NewContext(ctx, authorized)
+
+	execID, accepted, err := trigger(rCtx, payload.RobotID, robottypes.TriggerHuman, triggerData)
+	if err != nil {
+		log.Error("message handler: execute action failed robot=%s: %v", payload.RobotID, err)
+		return ""
+	}
+	if !accepted {
+		log.Warn("message handler: execute action not accepted robot=%s", payload.RobotID)
+		return ""
+	}
+
+	log.Info("message handler: execution triggered robot=%s exec_id=%s", payload.RobotID, execID)
+	return execID
+}
+
+// detectAction checks the Next hook return value for a confirmed action.
+// The Host Agent returns { data: { confirmed: true, robot_id: "...", goals: "..." } }
+// when it detects a confirm_task tool call.
+func detectAction(next interface{}) *ActionResult {
+	if next == nil {
+		return nil
+	}
+
+	m, ok := next.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+
+	// Next hook may return { data: { confirmed, ... } } or flat { confirmed, ... }
+	data, _ := m["data"].(map[string]interface{})
+	if data == nil {
+		data = m
+	}
+
+	confirmed, _ := data["confirmed"].(bool)
+	if !confirmed {
+		return nil
+	}
+
+	return &ActionResult{
+		Name:    "robot.execute",
+		Payload: data,
+	}
+}
+
+// resolveHostAssistantID resolves the host assistant ID from a robot member ID.
+// Mirrors the logic in openapi/agent/robot/completions.go.
+func resolveHostAssistantID(ctx context.Context, memberID string) (string, *robotstore.RobotRecord, error) {
+	store := robotstore.NewRobotStore()
+	record, err := store.Get(ctx, memberID)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to get robot: %w", err)
+	}
+	if record == nil {
+		return "", nil, fmt.Errorf("robot not found: %s", memberID)
+	}
+
+	config, err := robottypes.ParseConfig(record.RobotConfig)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to parse robot config: %w", err)
+	}
+
+	var hostID string
+	if config != nil && config.Resources != nil {
+		hostID = config.Resources.GetPhaseAgent(robottypes.PhaseHost)
+	} else {
+		hostID = "__yao." + string(robottypes.PhaseHost)
+	}
+
+	return hostID, record, nil
+}
+
+func taskDeployedMessage(execID string, locale string) string {
+	if strings.HasPrefix(locale, "zh") {
+		return fmt.Sprintf("任务已部署（执行编号: %s），完成后会将结果发送给你。", execID)
+	}
+	return fmt.Sprintf("Task deployed (execution: %s). You will receive results once completed.", execID)
+}

agent/robot/executor/standard/delivery.go

@@ -7,7 +7,7 @@ import (
 	"time"
 
 	"github.com/yaoapp/gou/model"
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 	"github.com/yaoapp/yao/event"
@@ -82,16 +82,31 @@ func (e *Executor) RunDelivery(ctx *robottypes.Context, exec *robottypes.Executi
 // Registered handlers (see events/handlers.go) route to email/webhook/process channels.
 func (e *Executor) pushDeliveryEvent(ctx *robottypes.Context, exec *robottypes.Execution, robot *robottypes.Robot) error {
 	prefs := buildDeliveryPreferences(robot)
+
+	chatID := exec.ChatID
+	var extra map[string]any
+	if exec.Input != nil && exec.Input.Data != nil {
+		if sourceChatID, ok := exec.Input.Data["chat_id"].(string); ok && sourceChatID != "" {
+			if channel, ok := exec.Input.Data["channel"].(string); ok && channel != "" {
+				chatID = channel + ":" + sourceChatID
+			}
+		}
+		if e, ok := exec.Input.Data["extra"].(map[string]any); ok {
+			extra = e
+		}
+	}
+
 	_, err := event.Push(ctx.Context, robotevents.Delivery, robotevents.DeliveryPayload{
 		ExecutionID: exec.ID,
 		MemberID:    exec.MemberID,
 		TeamID:      exec.TeamID,
-		ChatID:      exec.ChatID,
+		ChatID:      chatID,
 		Content:     exec.Delivery.Content,
 		Preferences: prefs,
+		Extra:       extra,
 	})
 	if err != nil {
-		log.Error("delivery event push failed: execution=%s error=%v", exec.ID, err)
+		kunlog.Error("delivery event push failed: execution=%s error=%v", exec.ID, err)
 	}
 	return nil
 }

agent/robot/executor/standard/executor.go

@@ -6,7 +6,7 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	agentcontext "github.com/yaoapp/yao/agent/context"
 	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	"github.com/yaoapp/yao/agent/robot/executor/types"
@@ -122,7 +122,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		record := store.FromExecution(exec)
 		if err := e.store.Save(ctx.Context, record); err != nil {
 			// Log warning but don't fail execution
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"error":        err,
@@ -132,7 +132,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		// If goals were pre-injected, persist them and update the execution title
 		if exec.Goals != nil && exec.Goals.Content != "" {
 			if err := e.store.UpdatePhase(ctx.Context, exec.ID, robottypes.PhaseGoals, exec.Goals); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"error":        err,
@@ -147,7 +147,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 
 	// Acquire execution slot
 	if !robot.TryAcquireSlot(exec) {
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 		}).Warn("Execution quota exceeded")
@@ -163,7 +163,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		// Update robot status to idle if no more running executions
 		if robot.RunningCount() == 0 && !e.config.SkipPersistence && e.robotStore != nil {
 			if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotIdle); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"member_id": robot.MemberID,
 					"error":     err,
 				}).Warn("Failed to update robot status to idle: %v", err)
@@ -186,7 +186,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 
 	// Update status to running
 	exec.Status = robottypes.ExecRunning
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"trigger_type": string(exec.TriggerType),
@@ -195,7 +195,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Persist running status
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateStatus(ctx.Context, exec.ID, robottypes.ExecRunning, ""); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist running status: %v", err)
@@ -205,7 +205,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Update robot status to working (when execution starts)
 	if !e.config.SkipPersistence && e.robotStore != nil {
 		if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotWorking); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"member_id": robot.MemberID,
 				"error":     err,
 			}).Warn("Failed to update robot status to working: %v", err)
@@ -216,7 +216,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	if dataStr, ok := data.(string); ok && dataStr == "simulate_failure" {
 		exec.Status = robottypes.ExecFailed
 		exec.Error = "simulated failure"
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 		}).Warn("Simulated failure triggered")
@@ -239,7 +239,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		if err := e.runPhase(ctx, exec, phase, data, control); err != nil {
 			// Check if execution was suspended (needs human input)
 			if err == robottypes.ErrExecutionSuspended {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"phase":        string(phase),
@@ -257,7 +257,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 				// Update UI field for cancellation with i18n
 				e.updateUIFields(ctx, exec, "", getLocalizedMessage(locale, "cancelled"))
 
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"phase":        string(phase),
@@ -280,7 +280,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 			failureMsg := failedPrefix + phaseName
 			e.updateUIFields(ctx, exec, "", failureMsg)
 
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"phase":        string(phase),
@@ -303,7 +303,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	e.updateUIFields(ctx, exec, "", getLocalizedMessage(locale, "completed"))
 
 	duration := now.Sub(exec.StartTime)
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"duration_ms":  duration.Milliseconds(),
@@ -312,7 +312,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Persist completed status
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateStatus(ctx.Context, exec.ID, robottypes.ExecCompleted, ""); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist completed status: %v", err)
@@ -348,7 +348,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 
 	exec.Phase = phase
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"phase":        string(phase),
@@ -357,7 +357,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 	// Persist phase change immediately (so frontend sees current phase)
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdatePhase(ctx.Context, exec.ID, phase, nil); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"phase":        string(phase),
 				"error":        err,
@@ -390,14 +390,14 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 
 	if err != nil {
 		if err == robottypes.ErrExecutionSuspended {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"phase":        string(phase),
 			}).Info("Phase suspended: %s (waiting for human input)", phase)
 			return err
 		}
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 			"phase":        string(phase),
@@ -412,7 +412,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 		if phaseData != nil {
 			if err := e.store.UpdatePhase(ctx.Context, exec.ID, phase, phaseData); err != nil {
 				// Log warning but don't fail execution
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"phase":        string(phase),
 					"error":        err,
@@ -426,7 +426,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 	}
 
 	phaseDuration := time.Since(phaseStart).Milliseconds()
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"phase":        string(phase),
@@ -613,7 +613,7 @@ func (e *Executor) updateUIFields(ctx *robottypes.Context, exec *robottypes.Exec
 	// Persist to database
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateUIFields(ctx.Context, exec.ID, name, currentTaskName); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to update UI fields: %v", err)
@@ -638,7 +638,7 @@ func (e *Executor) updateTasksState(ctx *robottypes.Context, exec *robottypes.Ex
 	}
 
 	if err := e.store.UpdateTasks(ctx.Context, exec.ID, exec.Tasks, current); err != nil {
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"error":        err,
 		}).Warn("Failed to update tasks state: %v", err)
@@ -759,14 +759,14 @@ func (e *Executor) Suspend(ctx *robottypes.Context, exec *robottypes.Execution,
 		e.updateTasksState(ctx, exec)
 		// Persist P3 results so UI can show completed tasks while waiting (§16.26)
 		if err := e.store.UpdatePhase(ctx.Context, exec.ID, robottypes.PhaseRun, exec.Results); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist partial results on suspend: %v", err)
 		}
 		// Persist suspend state atomically
 		if err := e.store.UpdateSuspendState(ctx.Context, exec.ID, taskID, question, exec.ResumeContext); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"task_id":      taskID,
 				"error":        err,
@@ -774,7 +774,7 @@ func (e *Executor) Suspend(ctx *robottypes.Context, exec *robottypes.Execution,
 		}
 	}
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"task_id":      taskID,
@@ -854,7 +854,7 @@ func (e *Executor) Resume(ctx *robottypes.Context, execID string, reply string)
 		robot.RemoveExecution(exec.ID)
 		if robot.RunningCount() == 0 && !e.config.SkipPersistence && e.robotStore != nil {
 			if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotIdle); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"member_id": robot.MemberID,
 					"error":     err,
 				}).Warn("Failed to update robot status to idle after resume: %v", err)
@@ -901,14 +901,14 @@ func (e *Executor) Resume(ctx *robottypes.Context, execID string, reply string)
 
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateResumeState(ctx.Context, exec.ID); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist resume state: %v", err)
 		}
 	}
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"reply_len":    len(reply),

agent/robot/executor/standard/host.go

@@ -4,7 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
@@ -31,7 +31,7 @@ func (e *Executor) CallHostAgent(ctx *robottypes.Context, robot *robottypes.Robo
 		return nil, fmt.Errorf("failed to marshal host input: %w", err)
 	}
 
-	log.Info("calling Host Agent %s for scenario=%s chatID=%s", agentID, input.Scenario, chatID)
+	kunlog.Info("calling Host Agent %s for scenario=%s chatID=%s", agentID, input.Scenario, chatID)
 
 	caller := NewConversationCaller(chatID)
 	result, err := caller.CallWithMessages(ctx, agentID, string(inputJSON))
@@ -42,7 +42,7 @@ func (e *Executor) CallHostAgent(ctx *robottypes.Context, robot *robottypes.Robo
 	data, err := result.GetJSON()
 	if err != nil {
 		text := result.GetText()
-		log.Warn("Host Agent returned non-JSON response, treating as confirm: %s", text)
+		kunlog.Warn("Host Agent returned non-JSON response, treating as confirm: %s", text)
 		return &robottypes.HostOutput{
 			Reply:  text,
 			Action: robottypes.HostActionConfirm,

agent/robot/executor/standard/log.go

@@ -5,19 +5,15 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	"github.com/yaoapp/yao/config"
 
+	"github.com/yaoapp/yao/agent/robot/logger"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
-// execLogger provides structured, developer-facing logging for a single Robot execution.
+var log = logger.New("exec")
-// Each execution (Executor.ExecuteWithControl) creates one instance; it is passed to
+
-// RunTasks (P2) and Runner (P3) so every log line carries the same identity.
-//
-// Output routing:
-//   - development mode (config.IsDevelopment): human-readable console via fmt.Printf
-//   - production mode: structured fields via kun/log
 type execLogger struct {
 	robot  *robottypes.Robot
 	execID string
@@ -42,15 +38,14 @@ func (l *execLogger) connector() string {
 }
 
 // ---------------------------------------------------------------------------
-// P2: Task Overview — called once after RunTasks successfully generates tasks
+// P2: Task Overview
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskOverview(tasks []robottypes.Task) {
 	if config.IsDevelopment() {
 		l.devTaskOverview(tasks)
 	}
-	// Always emit structured log (Info level, hidden in prod unless needed)
+	kunlog.With(kunlog.F{
-	log.With(log.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"phase":          "tasks",
@@ -60,11 +55,21 @@ func (l *execLogger) logTaskOverview(tasks []robottypes.Task) {
 }
 
 func (l *execLogger) devTaskOverview(tasks []robottypes.Task) {
+	w := logger.Gray
+	h := logger.BoldCyan
+	v := logger.White
+	r := logger.Reset
+
 	var sb strings.Builder
-	sb.WriteString(fmt.Sprintf("%s ══════ P2: Task Overview ══════\n", l.prefix()))
+	sb.WriteString(fmt.Sprintf("\n%s%s%s\n", h, strings.Repeat("═", 60), r))
+	sb.WriteString(fmt.Sprintf("%s  TASK OVERVIEW%s\n", h, r))
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", h, strings.Repeat("─", 60), r))
+	sb.WriteString(fmt.Sprintf("%s  Robot:     %s%s%s\n", w, v, l.robotID(), r))
+	sb.WriteString(fmt.Sprintf("%s  Exec:      %s%s%s\n", w, v, l.execID, r))
 	if l.connector() != "" {
-		sb.WriteString(fmt.Sprintf("  Language Model: %s\n", l.connector()))
+		sb.WriteString(fmt.Sprintf("%s  Model:     %s%s%s\n", w, v, l.connector(), r))
 	}
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", w, strings.Repeat("─", 60), r))
 	for i, t := range tasks {
 		desc := t.Description
 		if desc == "" && len(t.Messages) > 0 {
@@ -72,22 +77,26 @@ func (l *execLogger) devTaskOverview(tasks []robottypes.Task) {
 				desc = s
 			}
 		}
-		desc = truncate(desc, 80)
+		desc = truncate(desc, 72)
-		sb.WriteString(fmt.Sprintf("  #%d %s [%s:%s] %q\n", i+1, t.ID, t.ExecutorType, t.ExecutorID, desc))
+		sb.WriteString(fmt.Sprintf("%s  #%d %s%s%s [%s:%s]\n", w, i+1, v, t.ID, r, t.ExecutorType, t.ExecutorID))
+		sb.WriteString(fmt.Sprintf("%s     %s%s\n", w, desc, r))
 	}
-	sb.WriteString(fmt.Sprintf("  Total: %d tasks\n", len(tasks)))
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", w, strings.Repeat("─", 60), r))
-	fmt.Print(sb.String())
+	sb.WriteString(fmt.Sprintf("%s  Total: %s%d tasks%s\n", w, v, len(tasks), r))
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", h, strings.Repeat("═", 60), r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// P3: Task Input — called before each task execution with the full prompt
+// P3: Task Input
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskInput(task *robottypes.Task, prompt string) {
 	if config.IsDevelopment() {
 		l.devTaskInput(task, prompt)
 	}
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"task_id":        task.ID,
@@ -99,14 +108,19 @@ func (l *execLogger) logTaskInput(task *robottypes.Task, prompt string) {
 }
 
 func (l *execLogger) devTaskInput(task *robottypes.Task, prompt string) {
-	sep := strings.Repeat("─", 40)
+	w := logger.Gray
-	fmt.Printf("%s ▶ Task %s [%s:%s]\n", l.prefix(), task.ID, task.ExecutorType, task.ExecutorID)
+	v := logger.White
-	fmt.Printf("  Prompt (%d chars):\n  %s\n%s\n  %s\n",
+	r := logger.Reset
-		len(prompt), sep, indentText(prompt, "  "), sep)
+
+	var sb strings.Builder
+	sb.WriteString(fmt.Sprintf("%s  ▶ Task %s%s%s [%s:%s]  Prompt: %d chars%s\n",
+		w, v, task.ID, w, task.ExecutorType, task.ExecutorID, len(prompt), r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// P3: Task Output — called after each task execution with the result
+// P3: Task Output
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.TaskResult) {
@@ -114,7 +128,7 @@ func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.Tas
 		l.devTaskOutput(task, result)
 	}
 
-	fields := log.F{
+	fields := kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"task_id":        result.TaskID,
@@ -130,24 +144,39 @@ func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.Tas
 		fields["error"] = result.Error
 	}
 	if result.Success {
-		log.With(fields).Info("Task completed: %s (%dms)", result.TaskID, result.Duration)
+		kunlog.With(fields).Info("Task completed: %s (%dms)", result.TaskID, result.Duration)
 	} else {
-		log.With(fields).Warn("Task failed: %s (%dms) %s", result.TaskID, result.Duration, result.Error)
+		kunlog.With(fields).Warn("Task failed: %s (%dms) %s", result.TaskID, result.Duration, result.Error)
 	}
 }
 
 func (l *execLogger) devTaskOutput(task *robottypes.Task, result *robottypes.TaskResult) {
+	w := logger.Gray
+	v := logger.White
+	g := logger.BoldGreen
+	rd := logger.BoldRed
+	r := logger.Reset
+
+	var sb strings.Builder
 	if result.Success {
-		fmt.Printf("%s ✓ Task %s completed (%dms)\n", l.prefix(), result.TaskID, result.Duration)
+		sb.WriteString(fmt.Sprintf("%s  ✓ %s%s%s completed %s(%dms)%s\n",
-		fmt.Printf("  Output: %s\n", outputSummary(result.Output))
+			g, v, result.TaskID, g, w, result.Duration, r))
+		out := outputSummary(result.Output)
+		if len(out) > 120 {
+			out = out[:120] + "..."
+		}
+		sb.WriteString(fmt.Sprintf("%s    Output: %s%s%s\n", w, v, out, r))
 	} else {
-		fmt.Printf("%s ✗ Task %s failed (%dms)\n", l.prefix(), result.TaskID, result.Duration)
+		sb.WriteString(fmt.Sprintf("%s  ✗ %s%s%s failed %s(%dms)%s\n",
-		fmt.Printf("  Error: %s\n", result.Error)
+			rd, v, result.TaskID, rd, w, result.Duration, r))
+		sb.WriteString(fmt.Sprintf("%s    Error:  %s%s%s\n", w, logger.Red, result.Error, r))
 	}
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// Agent Call — called after every AgentCaller.Call returns
+// Agent Call
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
@@ -158,7 +187,7 @@ func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
 		l.devAgentCall(agentID, result)
 	}
 
-	fields := log.F{
+	fields := kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"agent_id":       agentID,
@@ -169,16 +198,25 @@ func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
 		fields["next_type"] = fmt.Sprintf("%T", result.Next)
 		fields["next_len"] = outputLen(result.Next)
 	}
-	log.With(fields).Info("Agent call: %s (content=%d, next=%T)", agentID, len(result.Content), result.Next)
+	kunlog.With(fields).Info("Agent call: %s (content=%d, next=%T)", agentID, len(result.Content), result.Next)
 }
 
 func (l *execLogger) devAgentCall(agentID string, result *CallResult) {
-	nextInfo := "<nil>"
+	w := logger.Gray
+	v := logger.White
+	c := logger.Cyan
+	r := logger.Reset
+
+	nextInfo := "—"
 	if result.Next != nil {
-		nextInfo = fmt.Sprintf("%T(len=%d)", result.Next, outputLen(result.Next))
+		nextInfo = fmt.Sprintf("%T (len=%d)", result.Next, outputLen(result.Next))
 	}
-	fmt.Printf("%s   Agent(%s) → Content(len=%d) Next=%s\n",
+
-		l.prefix(), agentID, len(result.Content), nextInfo)
+	var sb strings.Builder
+	sb.WriteString(fmt.Sprintf("%s  → Agent(%s%s%s) Content: %s%d%s chars  Next: %s%s%s\n",
+		c, v, agentID, c, v, len(result.Content), w, v, nextInfo, r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------

agent/robot/logger/logger.go

@@ -0,0 +1,100 @@
+package logger
+
+import (
+	"fmt"
+
+	kunlog "github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/config"
+)
+
+const (
+	Reset     = "\033[0m"
+	Red       = "\033[31m"
+	Green     = "\033[32m"
+	Yellow    = "\033[33m"
+	Cyan      = "\033[36m"
+	White     = "\033[37m"
+	Gray      = "\033[90m"
+	BoldCyan  = "\033[1;36m"
+	BoldGreen = "\033[1;32m"
+	BoldRed   = "\033[1;31m"
+
+	reset  = Reset
+	red    = Red
+	yellow = Yellow
+	cyan   = Cyan
+	gray   = Gray
+)
+
+// Logger provides robot-level structured logging. All integration adapters,
+// dispatchers, event handlers, etc. share this implementation.
+//
+// Dev mode  → colored stdout + kun/log.Trace (unified).
+// Prod mode → kun/log at matching level.
+type Logger struct {
+	tag string
+}
+
+// New creates a Logger tagged with the given component name
+// (e.g. "telegram", "dispatcher", "message", "delivery").
+func New(tag string) *Logger {
+	return &Logger{tag: tag}
+}
+
+func (l *Logger) prefix() string {
+	return fmt.Sprintf("[robot:%s]", l.tag)
+}
+
+func (l *Logger) Trace(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  → %s %s%s\n", gray, l.prefix(), msg, reset)
+	}
+	kunlog.Trace("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Debug(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  • %s %s%s\n", gray, l.prefix(), msg, reset)
+	}
+	kunlog.Debug("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Info(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ℹ %s %s%s\n", cyan, l.prefix(), msg, reset)
+	}
+	kunlog.Info("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Warn(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ⚠ %s %s%s\n", yellow, l.prefix(), msg, reset)
+	}
+	kunlog.Warn("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Error(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ✗ %s %s%s\n", red, l.prefix(), msg, reset)
+	}
+	kunlog.Error("%s %s", l.prefix(), msg)
+}
+
+// IsDev returns true when running in development mode.
+func IsDev() bool {
+	return config.IsDevelopment()
+}
+
+// Raw writes pre-formatted text directly to stdout in dev mode only.
+// Use for rich multi-line output (box-style logs, tables, etc.)
+// that should bypass the standard single-line prefix format.
+func Raw(s string) {
+	if config.IsDevelopment() {
+		fmt.Print(s)
+	}
+}

agent/robot/pool/worker.go

@@ -1,13 +1,15 @@
 package pool
 
 import (
-	"fmt"
 	"sync"
 	"time"
 
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/types"
 )
 
+var log = logger.New("pool")
+
 // Worker represents a worker goroutine that processes jobs
 type Worker struct {
 	id       int
@@ -96,13 +98,13 @@ func (w *Worker) execute(item *QueueItem) {
 		// so that Resume can find it later (§16.1).
 		if err == types.ErrExecutionSuspended {
 			if execution != nil {
-				fmt.Printf("Worker %d: Execution %s suspended for robot %s (waiting for input)\n",
+				log.Info("Worker %d: Execution %s suspended for robot %s (waiting for input)",
 					w.id, execution.ID, item.Robot.MemberID)
 			}
 			return
 		}
 
-		fmt.Printf("Worker %d: Execution failed for robot %s: %v\n",
+		log.Error("Worker %d: Execution failed for robot %s: %v",
 			w.id, item.Robot.MemberID, err)
 		// Notify completion callback with appropriate status
 		if w.pool.onComplete != nil {
@@ -116,7 +118,7 @@ func (w *Worker) execute(item *QueueItem) {
 	}
 
 	if execution != nil {
-		fmt.Printf("Worker %d: Execution %s completed for robot %s (status: %s)\n",
+		log.Info("Worker %d: Execution %s completed for robot %s (status: %s)",
 			w.id, execution.ID, item.Robot.MemberID, execution.Status)
 		// Notify completion callback
 		if w.pool.onComplete != nil {
@@ -131,8 +133,7 @@ func (w *Worker) requeue(item *QueueItem, reason string) {
 	// - If queue has space: task waits for robot quota
 	// - If queue is full: system is overloaded, drop task
 	if !w.pool.queue.Enqueue(item) {
-		// Queue full = system overloaded, drop task (protective discard)
+		log.Warn("Worker %d: Task for robot %s dropped (queue full, %s)",
-		fmt.Printf("Worker %d: Task for robot %s dropped (queue full, %s)\n",
 			w.id, item.Robot.MemberID, reason)
 	}
 }

agent/robot/robot.go

@@ -1,51 +1,66 @@
 package robot
 
 import (
+	"context"
+
 	"github.com/yaoapp/yao/agent/robot/cache"
 	"github.com/yaoapp/yao/agent/robot/dedup"
+	"github.com/yaoapp/yao/agent/robot/events/integrations"
+	"github.com/yaoapp/yao/agent/robot/events/integrations/telegram"
 	"github.com/yaoapp/yao/agent/robot/executor"
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/manager"
 	"github.com/yaoapp/yao/agent/robot/plan"
 	"github.com/yaoapp/yao/agent/robot/pool"
 	"github.com/yaoapp/yao/agent/robot/store"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
 var (
-	// Global instances (will be initialized in Init)
+	log = logger.New("robot")
-	globalManager  *manager.Manager
+
-	globalCache    *cache.Cache
+	globalManager    *manager.Manager
-	globalPool     *pool.Pool
+	globalCache      *cache.Cache
-	globalDedup    *dedup.Dedup
+	globalPool       *pool.Pool
-	globalStore    *store.Store
+	globalDedup      *dedup.Dedup
-	globalExecutor executor.Executor
+	globalStore      *store.Store
-	globalPlan     *plan.Plan
+	globalExecutor   executor.Executor
+	globalPlan       *plan.Plan
+	globalDispatcher *integrations.Dispatcher
 )
 
 // Init initializes the robot agent system
-// Stub: placeholder (will be implemented in Phase 3)
 func Init() error {
-	// Initialize global instances
 	globalCache = cache.New()
 	globalDedup = dedup.New()
 	globalStore = store.New()
-	globalPool = pool.New() // Default pool size
+	globalPool = pool.New()
 	globalExecutor = executor.New()
 	globalManager = manager.New()
 	globalPlan = plan.New()
 
-	// TODO Phase 3: Start manager and pool
+	// Load robots into cache from database before starting dispatcher
-	// return globalManager.Start()
+	rCtx := robottypes.NewContext(context.Background(), nil)
+	if err := globalCache.Load(rCtx); err != nil {
+		log.Warn("robot.Init: cache load failed (will rely on config events): %v", err)
+	}
+
+	adapters := map[string]integrations.Adapter{
+		"telegram": telegram.NewAdapter(),
+	}
+	globalDispatcher = integrations.NewDispatcher(globalCache, adapters)
+	if err := globalDispatcher.Start(context.Background()); err != nil {
+		return err
+	}
 
 	return nil
 }
 
 // Shutdown gracefully shuts down the robot agent system
-// Stub: placeholder (will be implemented in Phase 3)
 func Shutdown() error {
-	// TODO Phase 3: Stop manager and pool
+	if globalDispatcher != nil {
-	// if globalManager != nil {
+		globalDispatcher.Stop()
-	//     return globalManager.Stop()
+	}
-	// }
 	return nil
 }
 

agent/robot/types/config.go

@@ -19,6 +19,22 @@ type Config struct {
 	Events        []Event              `json:"events,omitempty"`
 	Executor      *ExecutorConfig      `json:"executor,omitempty"`       // executor mode settings
 	DefaultLocale string               `json:"default_locale,omitempty"` // default language for clock/event triggers ("en", "zh")
+	Integrations  *Integrations        `json:"integrations,omitempty"`   // external channel integrations (telegram, etc.)
+}
+
+// Integrations holds configuration for external platform integrations.
+type Integrations struct {
+	Telegram *TelegramConfig `json:"telegram,omitempty"`
+}
+
+// TelegramConfig holds Telegram Bot integration settings.
+type TelegramConfig struct {
+	Enabled       bool   `json:"enabled"`
+	BotToken      string `json:"bot_token"`
+	Host          string `json:"host,omitempty"`           // custom Bot API server, defaults to https://api.telegram.org
+	AppID         string `json:"app_id,omitempty"`         // auto-generated, used for webhook URL routing
+	ChatID        string `json:"chat_id,omitempty"`        // default reply chat
+	WebhookSecret string `json:"webhook_secret,omitempty"` // sent with SetWebhook, verified on incoming webhooks
 }
 
 // ExecutorConfig - executor settings

go.mod

@@ -9,6 +9,8 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.79.3
 	github.com/blang/semver v3.5.1+incompatible
 	github.com/caarlos0/env/v6 v6.10.1
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/dchest/captcha v1.1.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.5.0
@@ -22,12 +24,14 @@ require (
 	github.com/golang-jwt/jwt/v4 v4.5.2
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
+	github.com/gotd/td v0.140.0
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/joho/godotenv v1.5.1
 	github.com/json-iterator/go v1.1.12
 	github.com/kaptinlin/jsonrepair v0.1.1
 	github.com/kaptinlin/jsonschema v0.6.1
 	github.com/matoous/go-nanoid/v2 v2.1.0
+	github.com/mattn/go-isatty v0.0.20
 	github.com/mozillazg/go-pinyin v0.20.0
 	github.com/pkoukk/tiktoken-go v0.1.7
 	github.com/pquerna/otp v1.5.0
@@ -40,9 +44,9 @@ require (
 	github.com/yaoapp/kun v0.9.0
 	github.com/yaoapp/xun v0.9.0
 	go.mongodb.org/mongo-driver v1.17.3
-	golang.org/x/crypto v0.45.0
+	golang.org/x/crypto v0.48.0
-	golang.org/x/net v0.47.0
+	golang.org/x/net v0.50.0
-	golang.org/x/text v0.31.0
+	golang.org/x/text v0.34.0
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 	gopkg.in/yaml.v3 v3.0.1
 	rogchap.com/v8go v0.9.0
@@ -69,14 +73,14 @@ require (
 	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
 	github.com/bytedance/sonic v1.13.2 // indirect
 	github.com/bytedance/sonic/loader v0.2.4 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/charmbracelet/bubbletea v1.3.10 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.10.1 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
 	github.com/cloudwego/base64x v0.1.5 // indirect
+	github.com/coder/websocket v1.8.14 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
@@ -88,8 +92,13 @@ require (
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.9 // indirect
+	github.com/ghodss/yaml v1.0.0 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
 	github.com/go-errors/errors v1.5.1 // indirect
+	github.com/go-faster/errors v0.7.1 // indirect
+	github.com/go-faster/jx v1.2.0 // indirect
+	github.com/go-faster/xor v1.0.0 // indirect
+	github.com/go-faster/yaml v0.4.6 // indirect
 	github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -99,12 +108,15 @@ require (
 	github.com/go-redis/redis/v8 v8.11.5 // indirect
 	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
 	github.com/go-sql-driver/mysql v1.9.2 // indirect
+	github.com/go-telegram/bot v1.19.0 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/goccy/go-yaml v1.18.0 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/golang/snappy v1.0.0 // indirect
 	github.com/google/go-github/v30 v30.1.0 // indirect
 	github.com/google/go-querystring v1.1.0 // indirect
+	github.com/gotd/ige v0.2.2 // indirect
+	github.com/gotd/neo v0.1.5 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-hclog v1.6.3 // indirect
 	github.com/hashicorp/go-plugin v1.6.3 // indirect
@@ -119,14 +131,13 @@ require (
 	github.com/kaptinlin/go-i18n v0.2.0 // indirect
 	github.com/kaptinlin/jsonpointer v0.4.6 // indirect
 	github.com/kaptinlin/messageformat-go v0.4.6 // indirect
-	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/klauspost/compress v1.18.4 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/lib/pq v1.10.9 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
 	github.com/mark3labs/mcp-go v0.32.0 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-sqlite3 v1.14.28 // indirect
@@ -140,6 +151,7 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/neo4j/neo4j-go-driver/v5 v5.28.1 // indirect
+	github.com/ogen-go/ogen v1.19.0 // indirect
 	github.com/oklog/run v1.1.0 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.0 // indirect
@@ -153,7 +165,9 @@ require (
 	github.com/richardlehane/msoleps v1.0.4 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/robfig/cron/v3 v3.0.1 // indirect
+	github.com/segmentio/asm v1.2.1 // indirect
 	github.com/sergi/go-diff v1.4.0 // indirect
+	github.com/shopspring/decimal v1.4.0 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/tcnksm/go-gitconfig v0.1.2 // indirect
@@ -183,21 +197,25 @@ require (
 	go.opentelemetry.io/otel v1.40.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 // indirect
 	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/sdk/metric v1.40.0 // indirect
 	go.opentelemetry.io/otel/trace v1.40.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.9.0 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.uber.org/zap v1.27.1 // indirect
 	golang.org/x/arch v0.17.0 // indirect
+	golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 // indirect
 	golang.org/x/image v0.29.0 // indirect
-	golang.org/x/mod v0.29.0 // indirect
+	golang.org/x/mod v0.33.0 // indirect
 	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
-	golang.org/x/tools v0.38.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 // indirect
 	google.golang.org/grpc v1.75.1 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gotest.tools/v3 v3.5.2 // indirect
+	rsc.io/qr v0.2.0 // indirect
 )
 
 // go env -w GOPRIVATE=github.com/yaoapp/*

go.sum

@@ -60,8 +60,8 @@ github.com/bytedance/sonic/loader v0.2.4 h1:ZWCw4stuXUsn1/+zQDqeE7JKP+QO47tz7QCN
 github.com/bytedance/sonic/loader v0.2.4/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFosQU6FxH2JmUe6VI=
 github.com/caarlos0/env/v6 v6.10.1 h1:t1mPSxNpei6M5yAeu1qtRdPAK29Nbcf/n3G7x+b3/II=
 github.com/caarlos0/env/v6 v6.10.1/go.mod h1:hvp/ryKXKipEkcuYjs9mI4bBCg+UI0Yhgm5Zu0ddvwc=
-github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
-github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
@@ -79,6 +79,8 @@ github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNE
 github.com/cloudwego/base64x v0.1.5 h1:XPciSp1xaq2VCSt6lF0phncD4koWyULpl5bUxbfCyP4=
 github.com/cloudwego/base64x v0.1.5/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
 github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
 github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
 github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
@@ -130,12 +132,23 @@ github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/gabriel-vasile/mimetype v1.4.9 h1:5k+WDwEsD9eTLL8Tz3L0VnmVh9QxGjRmjBvAG7U/oYY=
 github.com/gabriel-vasile/mimetype v1.4.9/go.mod h1:WnSQhFKJuBlRyLiKohA/2DtIlPFAbguNaG7QCHcyGok=
+github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk=
+github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
 github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
 github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
 github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
 github.com/gin-gonic/gin v1.10.1/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
 github.com/go-errors/errors v1.5.1 h1:ZwEMSLRCapFLflTpT7NKaAc7ukJ8ZPEjzlxt8rPN8bk=
 github.com/go-errors/errors v1.5.1/go.mod h1:sIVyrIiJhuEF+Pj9Ebtd6P/rEYROXFi3BopGUQ5a5Og=
+github.com/go-faster/errors v0.7.1 h1:MkJTnDoEdi9pDabt1dpWf7AA8/BaSYZqibYyhZ20AYg=
+github.com/go-faster/errors v0.7.1/go.mod h1:5ySTjWFiphBs07IKuiL69nxdfd5+fzh1u7FPGZP2quo=
+github.com/go-faster/jx v1.2.0 h1:T2YHJPrFaYu21fJtUxC9GzmluKu8rVIFDwwGBKTDseI=
+github.com/go-faster/jx v1.2.0/go.mod h1:UWLOVDmMG597a5tBFPLIWJdUxz5/2emOpfsj9Neg0PE=
+github.com/go-faster/xor v0.3.0/go.mod h1:x5CaDY9UKErKzqfRfFZdfu+OSTfoZny3w5Ak7UxcipQ=
+github.com/go-faster/xor v1.0.0 h1:2o8vTOgErSGHP3/7XwA5ib1FTtUsNtwCoLLBjl31X38=
+github.com/go-faster/xor v1.0.0/go.mod h1:x5CaDY9UKErKzqfRfFZdfu+OSTfoZny3w5Ak7UxcipQ=
+github.com/go-faster/yaml v0.4.6 h1:lOK/EhI04gCpPgPhgt0bChS6bvw7G3WwI8xxVe0sw9I=
+github.com/go-faster/yaml v0.4.6/go.mod h1:390dRIvV4zbnO7qC9FGo6YYutc+wyyUSHBgbXL52eXk=
 github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
 github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -158,6 +171,8 @@ github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5Nq
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-sql-driver/mysql v1.9.2 h1:4cNKDYQ1I84SXslGddlsrMhc8k4LeDVj6Ad6WRjiHuU=
 github.com/go-sql-driver/mysql v1.9.2/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
+github.com/go-telegram/bot v1.19.0 h1:tuvTQhgNietHFRN0HUDhuXsgfgkGSaO8WWwZQW3DMQg=
+github.com/go-telegram/bot v1.19.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
@@ -184,6 +199,12 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/gotd/ige v0.2.2 h1:XQ9dJZwBfDnOGSTxKXBGP4gMud3Qku2ekScRjDWWfEk=
+github.com/gotd/ige v0.2.2/go.mod h1:tuCRb+Y5Y3eNTo3ypIfNpQ4MFjrnONiL2jN2AKZXmb0=
+github.com/gotd/neo v0.1.5 h1:oj0iQfMbGClP8xI59x7fE/uHoTJD7NZH9oV1WNuPukQ=
+github.com/gotd/neo v0.1.5/go.mod h1:9A2a4bn9zL6FADufBdt7tZt+WMhvZoc5gWXihOPoiBQ=
+github.com/gotd/td v0.140.0 h1:trNBzTnhNtNwHsFp5qwKnNxQRAZJ6/BRE+uH3Lojauk=
+github.com/gotd/td v0.140.0/go.mod h1:0ZkRxG7N+5ooG7/zdRXcnGautGPM6IKmyPQvdsAeF20=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 h1:8Tjv8EJ+pM1xP8mK6egEbD1OgnVTyacbefKhmbLhIhU=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2/go.mod h1:pkJQ2tZHJ0aFOVEEot6oZmaVEZcRme73eIFmhiVuRWs=
 github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
@@ -230,8 +251,8 @@ github.com/kaptinlin/jsonschema v0.6.1 h1:RNUQ11ZCHTtM80YcVwRm033H5OJS+MpO06d9x7
 github.com/kaptinlin/jsonschema v0.6.1/go.mod h1:T8SNWNTRLDS1w+ogMZpGYqIfUXn/8DK9r06mf8XbNLE=
 github.com/kaptinlin/messageformat-go v0.4.6 h1:57DUC9en40mGZR7MvqOS+5EYogAl465fjo+loAA1KPg=
 github.com/kaptinlin/messageformat-go v0.4.6/go.mod h1:r0PH7FsxJX8jS/n6LAYZon5w3X+yfCLUrquqYd2H7ks=
-github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
-github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
@@ -299,6 +320,8 @@ github.com/neo4j/neo4j-go-driver/v5 v5.28.1 h1:RKWQW7wTgYAY2fU9S+9LaJ9OwRPbRc0I1
 github.com/neo4j/neo4j-go-driver/v5 v5.28.1/go.mod h1:Vff8OwT7QpLm7L2yYr85XNWe9Rbqlbeb9asNXJTHO4k=
 github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
+github.com/ogen-go/ogen v1.19.0 h1:YvdNpeQJ8A8dLLpS6Vs4WxXL53BT6tBPxH0VSjfALhA=
+github.com/ogen-go/ogen v1.19.0/go.mod h1:DeShwO+TEpLYXNCuZliSAedphphXsJaTGGbmSomWUjE=
 github.com/oklog/run v1.1.0 h1:GEenZ1cK0+q0+wsJew9qUg/DyD8k3JzYsZAi5gYi2mA=
 github.com/oklog/run v1.1.0/go.mod h1:sVPdnTZT1zYwAJeCMu2Th4T21pA3FPOQRfWjQlk7DVU=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -344,8 +367,12 @@ github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8rc=
 github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
+github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
+github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
 github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
+github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
+github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
 github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE=
@@ -442,6 +469,14 @@ go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZY
 go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
 go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
 go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
+go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
 golang.org/x/arch v0.17.0 h1:4O3dfLzd+lQewptAHqjewQZQDyEdejz3VwgeYwkZneU=
 golang.org/x/arch v0.17.0/go.mod h1:bdwinDaKcfZUGpH09BB7ZmOfhalA8lQdzl62l8gGWsk=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -451,8 +486,10 @@ golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliY
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
-golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 h1:Di6/M8l0O2lCLc6VVRWhgCiApHV8MnQurBnFSHsQtNY=
+golang.org/x/exp v0.0.0-20230725093048-515e97ebf090/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
 golang.org/x/image v0.29.0 h1:HcdsyR4Gsuys/Axh0rDEmlBmB68rW1U9BUdB3UVHsas=
 golang.org/x/image v0.29.0/go.mod h1:RVJROnf3SLK8d26OW91j4FrIHGbsJ8QnbEocVTOWQDA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
@@ -460,8 +497,8 @@ golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.29.0 h1:HV8lRxZC4l2cr3Zq1LvtOsi/ThTgWnUk/y64QSs8GwA=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
-golang.org/x/mod v0.29.0/go.mod h1:NyhrlYXJ2H4eJiRy/WDBO6HMqZQ6q9nk4JzS3NuCK+w=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
@@ -475,22 +512,23 @@ golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
-golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
-golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.0.0-20181106182150-f42d05182288/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
 golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201207232520-09787c993a3a/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -512,8 +550,8 @@ golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
@@ -536,8 +574,8 @@ golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
-golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4=
 golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -546,8 +584,8 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
-golang.org/x/tools v0.38.0/go.mod h1:yEsQ/d/YK8cjh0L6rZlY8tgtlKiBNTL14pGDJPJpYQs=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
@@ -581,4 +619,8 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
+nhooyr.io/websocket v1.8.17 h1:KEVeLJkUywCKVsnLIDlD/5gtayKp8VoCkksHCGGfT9Y=
+nhooyr.io/websocket v1.8.17/go.mod h1:rN9OFWIUwuxg4fR5tELlYC04bXYowCP9GX47ivo2l+c=
 nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=

integrations/telegram/bot.go

@@ -0,0 +1,83 @@
+package telegram
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-telegram/bot"
+)
+
+const defaultAPIBase = "https://api.telegram.org"
+
+// Bot represents a single Telegram bot instance bound to a specific token.
+// Each registered robot gets its own Bot. All API methods live on Bot so
+// callers never need to pass the token around.
+type Bot struct {
+	token       string
+	secretToken string // for webhook X-Telegram-Bot-Api-Secret-Token verification
+	apiBase     string // e.g. "https://api.telegram.org" or "http://localhost:3001"
+	httpClient  *http.Client
+}
+
+// BotOption configures optional Bot parameters.
+type BotOption func(*Bot)
+
+// WithAPIBase sets a custom Bot API server URL (e.g. a local telegram-bot-api instance).
+func WithAPIBase(url string) BotOption {
+	return func(b *Bot) {
+		b.apiBase = strings.TrimRight(url, "/")
+	}
+}
+
+// NewBot creates a Bot bound to the given token.
+// secretToken is optional — when set it is sent with SetWebhook and used by
+// VerifyWebhook to authenticate incoming requests.
+func NewBot(token string, secretToken string, opts ...BotOption) *Bot {
+	b := &Bot{
+		token:       token,
+		secretToken: secretToken,
+		apiBase:     defaultAPIBase,
+		httpClient:  &http.Client{Timeout: 90 * time.Second},
+	}
+	for _, o := range opts {
+		o(b)
+	}
+	return b
+}
+
+// Token returns the raw bot token.
+func (b *Bot) Token() string { return b.token }
+
+// SecretToken returns the webhook secret (may be empty).
+func (b *Bot) SecretToken() string { return b.secretToken }
+
+// APIBase returns the API server base URL.
+func (b *Bot) APIBase() string { return b.apiBase }
+
+// botURL builds the bot-method base URL: {apiBase}/bot{token}
+func (b *Bot) botURL() string {
+	return b.apiBase + "/bot" + b.token
+}
+
+// fileURL builds the file download URL: {apiBase}/file/bot{token}/{path}
+func (b *Bot) fileURL(filePath string) string {
+	return b.apiBase + "/file/bot" + b.token + "/" + filePath
+}
+
+// sdk returns a go-telegram/bot.Bot instance for typed method calls.
+func (b *Bot) sdk() (*bot.Bot, error) {
+	opts := []bot.Option{
+		bot.WithSkipGetMe(),
+		bot.WithHTTPClient(90*time.Second, b.httpClient),
+	}
+	if b.apiBase != defaultAPIBase {
+		opts = append(opts, bot.WithServerURL(b.apiBase))
+	}
+	sdkBot, err := bot.New(b.token, opts...)
+	if err != nil {
+		return nil, fmt.Errorf("create bot sdk: %w", err)
+	}
+	return sdkBot, nil
+}

integrations/telegram/bot_test.go

@@ -0,0 +1,22 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestNewBot(t *testing.T) {
+	b := NewBot("123:ABC", "my-secret")
+	if b.Token() != "123:ABC" {
+		t.Fatalf("expected token 123:ABC, got %s", b.Token())
+	}
+	if b.SecretToken() != "my-secret" {
+		t.Fatalf("expected secret my-secret, got %s", b.SecretToken())
+	}
+}
+
+func TestNewBot_EmptySecret(t *testing.T) {
+	b := NewBot("123:ABC", "")
+	if b.SecretToken() != "" {
+		t.Fatalf("expected empty secret, got %s", b.SecretToken())
+	}
+}

integrations/telegram/convert.go

@@ -0,0 +1,298 @@
+package telegram
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// ConvertedMessage is the unified output of ConvertUpdate, usable by any
+// consumer regardless of whether the Update came from GetUpdates or a webhook.
+type ConvertedMessage struct {
+	UpdateID     int64          `json:"update_id"`
+	MessageID    int64          `json:"message_id"`
+	ChatID       int64          `json:"chat_id"`
+	ChatType     string         `json:"chat_type"`
+	SenderID     int64          `json:"sender_id,omitempty"`
+	SenderName   string         `json:"sender_name,omitempty"`
+	LanguageCode string         `json:"language_code,omitempty"`
+	Date         int            `json:"date"`
+	Text         string         `json:"text,omitempty"`
+	MediaItems   []MediaItem    `json:"media,omitempty"`
+	ReplyTo      *ReplyInfo     `json:"reply_to,omitempty"`
+	Raw          *models.Update `json:"-"`
+}
+
+// MediaItem describes a single media attachment extracted from the message.
+type MediaItem struct {
+	Type         MediaType `json:"type"`
+	FileID       string    `json:"file_id"`
+	FileUniqueID string    `json:"file_unique_id"`
+	MimeType     string    `json:"mime_type"`
+	FileName     string    `json:"file_name,omitempty"`
+	FileSize     int64     `json:"file_size,omitempty"`
+	Wrapper      string    `json:"wrapper,omitempty"` // __yao.attachment://xxx after ResolveMedia
+}
+
+// ReplyInfo holds info about the message being replied to.
+type ReplyInfo struct {
+	MessageID int64 `json:"message_id"`
+	ChatID    int64 `json:"chat_id,omitempty"`
+}
+
+// ConvertUpdate transforms a raw Telegram Update into a ConvertedMessage.
+// Returns nil if the update contains no processable message.
+func ConvertUpdate(u *models.Update) *ConvertedMessage {
+	msg := u.Message
+	if msg == nil {
+		return nil
+	}
+
+	cm := &ConvertedMessage{
+		UpdateID:  int64(u.ID),
+		MessageID: int64(msg.ID),
+		ChatID:    msg.Chat.ID,
+		ChatType:  string(msg.Chat.Type),
+		Date:      msg.Date,
+		Raw:       u,
+	}
+
+	if msg.From != nil {
+		cm.SenderID = msg.From.ID
+		cm.SenderName = buildSenderName(msg.From)
+		cm.LanguageCode = msg.From.LanguageCode
+	}
+
+	if msg.Text != "" {
+		cm.Text = ApplyEntities(msg.Text, msg.Entities)
+	} else if msg.Caption != "" {
+		cm.Text = ApplyEntities(msg.Caption, msg.CaptionEntities)
+	}
+
+	cm.MediaItems = extractMedia(msg)
+
+	if msg.ReplyToMessage != nil {
+		cm.ReplyTo = &ReplyInfo{
+			MessageID: int64(msg.ReplyToMessage.ID),
+			ChatID:    msg.ReplyToMessage.Chat.ID,
+		}
+	}
+
+	return cm
+}
+
+// HasMedia returns true if the message contains any media attachments.
+func (cm *ConvertedMessage) HasMedia() bool {
+	return len(cm.MediaItems) > 0
+}
+
+// HasText returns true if the message contains text content.
+func (cm *ConvertedMessage) HasText() bool {
+	return cm.Text != ""
+}
+
+func buildSenderName(u *models.User) string {
+	name := u.FirstName
+	if u.LastName != "" {
+		name += " " + u.LastName
+	}
+	return name
+}
+
+func extractMedia(msg *models.Message) []MediaItem {
+	var items []MediaItem
+
+	if len(msg.Photo) > 0 {
+		best := pickBestPhoto(msg.Photo)
+		items = append(items, MediaItem{
+			Type:         MediaPhoto,
+			FileID:       best.FileID,
+			FileUniqueID: best.FileUniqueID,
+			MimeType:     "image/jpeg",
+			FileName:     "photo.jpg",
+			FileSize:     int64(best.FileSize),
+		})
+	}
+
+	if msg.Document != nil {
+		d := msg.Document
+		mime := d.MimeType
+		if mime == "" {
+			mime = "application/octet-stream"
+		}
+		name := d.FileName
+		if name == "" {
+			name = "document"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaDocument,
+			FileID:       d.FileID,
+			FileUniqueID: d.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(d.FileSize),
+		})
+	}
+
+	if msg.Audio != nil {
+		a := msg.Audio
+		mime := a.MimeType
+		if mime == "" {
+			mime = "audio/mpeg"
+		}
+		name := a.FileName
+		if name == "" {
+			name = "audio.mp3"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaAudio,
+			FileID:       a.FileID,
+			FileUniqueID: a.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(a.FileSize),
+		})
+	}
+
+	if msg.Voice != nil {
+		v := msg.Voice
+		mime := v.MimeType
+		if mime == "" {
+			mime = "audio/ogg"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaVoice,
+			FileID:       v.FileID,
+			FileUniqueID: v.FileUniqueID,
+			MimeType:     mime,
+			FileName:     "voice.ogg",
+			FileSize:     int64(v.FileSize),
+		})
+	}
+
+	if msg.Video != nil {
+		v := msg.Video
+		mime := v.MimeType
+		if mime == "" {
+			mime = "video/mp4"
+		}
+		name := v.FileName
+		if name == "" {
+			name = "video.mp4"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaVideo,
+			FileID:       v.FileID,
+			FileUniqueID: v.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(v.FileSize),
+		})
+	}
+
+	if msg.Animation != nil {
+		a := msg.Animation
+		mime := a.MimeType
+		if mime == "" {
+			mime = "video/mp4"
+		}
+		name := a.FileName
+		if name == "" {
+			name = "animation.mp4"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaAnimation,
+			FileID:       a.FileID,
+			FileUniqueID: a.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(a.FileSize),
+		})
+	}
+
+	if msg.Sticker != nil {
+		s := msg.Sticker
+		items = append(items, MediaItem{
+			Type:         MediaSticker,
+			FileID:       s.FileID,
+			FileUniqueID: s.FileUniqueID,
+			MimeType:     "image/webp",
+			FileName:     "sticker.webp",
+			FileSize:     int64(s.FileSize),
+		})
+	}
+
+	return items
+}
+
+func pickBestPhoto(photos []models.PhotoSize) models.PhotoSize {
+	if len(photos) == 0 {
+		return models.PhotoSize{}
+	}
+	sorted := make([]models.PhotoSize, len(photos))
+	copy(sorted, photos)
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i].Width*sorted[i].Height > sorted[j].Width*sorted[j].Height
+	})
+	return sorted[0]
+}
+
+// ApplyEntities converts Telegram MessageEntity formatting to Markdown.
+func ApplyEntities(text string, entities []models.MessageEntity) string {
+	if len(entities) == 0 {
+		return text
+	}
+
+	runes := []rune(text)
+
+	sorted := make([]models.MessageEntity, len(entities))
+	copy(sorted, entities)
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i].Offset > sorted[j].Offset
+	})
+
+	for _, e := range sorted {
+		start := e.Offset
+		end := e.Offset + e.Length
+		if start < 0 || end > len(runes) {
+			continue
+		}
+		segment := string(runes[start:end])
+
+		var replacement string
+		switch e.Type {
+		case "bold":
+			replacement = "**" + segment + "**"
+		case "italic":
+			replacement = "_" + segment + "_"
+		case "underline":
+			replacement = "__" + segment + "__"
+		case "strikethrough":
+			replacement = "~~" + segment + "~~"
+		case "code":
+			replacement = "`" + segment + "`"
+		case "pre":
+			lang := ""
+			if e.Language != "" {
+				lang = e.Language
+			}
+			replacement = "```" + lang + "\n" + segment + "\n```"
+		case "text_link":
+			replacement = "[" + segment + "](" + e.URL + ")"
+		case "text_mention":
+			if e.User != nil {
+				replacement = "[" + segment + "](tg://user?id=" + strconv.FormatInt(e.User.ID, 10) + ")"
+			} else {
+				replacement = segment
+			}
+		default:
+			continue
+		}
+
+		runes = append(runes[:start], append([]rune(replacement), runes[end:]...)...)
+	}
+
+	return strings.TrimSpace(string(runes))
+}

integrations/telegram/e2e_test.go

@@ -0,0 +1,416 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"mime/multipart"
+	"net/textproto"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/yaoapp/yao/attachment"
+)
+
+// TestE2E_00_Seed must run first (go test runs in lexical order).
+// It sends a text + photo to the bot via MTProto so later tests have data.
+func TestE2E_00_Seed(t *testing.T) {
+	skipIfNoToken(t)
+	seedBotMessages(t)
+}
+
+func TestE2E_01_GetMe(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	user, err := b.GetMe(ctx)
+	if err != nil {
+		t.Fatalf("GetMe failed: %v", err)
+	}
+
+	if user.ID == 0 {
+		t.Error("user.ID should not be 0")
+	}
+	if !user.IsBot {
+		t.Error("user.IsBot should be true")
+	}
+	if user.FirstName == "" {
+		t.Error("user.FirstName should not be empty")
+	}
+	if user.Username == "" {
+		t.Error("user.Username should not be empty")
+	}
+
+	expected := os.Getenv("TG_TEST_BOT_USERNAME")
+	if expected != "" && user.Username != expected {
+		t.Errorf("username mismatch: got %q, want %q", user.Username, expected)
+	}
+
+	if !user.CanJoinGroups {
+		t.Log("warning: bot cannot join groups (CanJoinGroups=false)")
+	}
+	t.Logf("OK  id=%d username=%s first_name=%s can_read_all=%v",
+		user.ID, user.Username, user.FirstName, user.CanReadAllGroupMessages)
+}
+
+func TestE2E_02_GetUpdates(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	updates, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=0): %v", err)
+	}
+	if len(updates) == 0 {
+		t.Fatal("expected at least 1 update after seed, got 0")
+	}
+
+	var prevID int64
+	for i, u := range updates {
+		if u.ID == 0 {
+			t.Errorf("updates[%d].ID should not be 0", i)
+		}
+		if u.ID < 0 {
+			t.Errorf("updates[%d].ID=%d is negative", i, u.ID)
+		}
+		if i > 0 && int64(u.ID) <= prevID {
+			t.Errorf("update_id not increasing: updates[%d].ID=%d <= prev=%d", i, u.ID, prevID)
+		}
+		prevID = int64(u.ID)
+
+		if u.Message != nil {
+			msg := u.Message
+			if msg.ID == 0 {
+				t.Errorf("updates[%d].Message.ID should not be 0", i)
+			}
+			if msg.Date == 0 {
+				t.Errorf("updates[%d].Message.Date should not be 0", i)
+			}
+			if msg.Chat.ID == 0 {
+				t.Errorf("updates[%d].Message.Chat.ID should not be 0", i)
+			}
+			if msg.Chat.Type == "" {
+				t.Errorf("updates[%d].Message.Chat.Type should not be empty", i)
+			}
+			if msg.From != nil && msg.From.ID == 0 {
+				t.Errorf("updates[%d].Message.From.ID should not be 0", i)
+			}
+
+			t.Logf("  update[%d] id=%d msg_id=%d chat=%d from=%d text=%q has_photo=%v has_doc=%v",
+				i, u.ID, msg.ID, msg.Chat.ID, safeUserID(msg.From), truncate(msg.Text, 40),
+				len(msg.Photo) > 0, msg.Document != nil)
+		}
+	}
+
+	firstID := int64(updates[0].ID)
+	lastID := int64(updates[len(updates)-1].ID)
+
+	// offset = first_id: non-destructive, returns from first_id onwards
+	updates2, err := b.GetRawUpdates(ctx, firstID, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=first_id=%d): %v", firstID, err)
+	}
+	if len(updates2) == 0 {
+		t.Error("offset=first_id returned 0 updates, expected >= 1")
+	}
+	if len(updates2) > 0 && int64(updates2[0].ID) != firstID {
+		t.Errorf("offset=first_id: first returned update_id=%d, want %d", updates2[0].ID, firstID)
+	}
+	for _, u2 := range updates2 {
+		if int64(u2.ID) < firstID {
+			t.Errorf("offset=first_id: got update_id=%d < offset=%d", u2.ID, firstID)
+		}
+	}
+
+	t.Logf("OK  total=%d first_id=%d last_id=%d monotonic=true offset_filter=ok",
+		len(updates), firstID, lastID)
+}
+
+func TestE2E_03_GetFile_Download(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	var fileID string
+	for i := 0; i < 3 && fileID == ""; i++ {
+		if i > 0 {
+			time.Sleep(time.Second)
+		}
+		fileID = findFileID(t, b, ctx)
+	}
+	if fileID == "" {
+		t.Fatal("expected a photo/file from seed, got none")
+	}
+
+	fileMeta, err := b.GetFile(ctx, fileID)
+	if err != nil {
+		t.Fatalf("GetFile failed: %v", err)
+	}
+	if fileMeta.FileID == "" {
+		t.Error("fileMeta.FileID should not be empty")
+	}
+	if fileMeta.FileID != fileID {
+		t.Errorf("fileMeta.FileID=%q should match requested %q", fileMeta.FileID, fileID)
+	}
+	if fileMeta.FilePath == "" {
+		t.Fatal("fileMeta.FilePath should not be empty")
+	}
+	if fileMeta.FileSize <= 0 {
+		t.Error("fileMeta.FileSize should be > 0")
+	}
+
+	body, contentType, size, err := b.DownloadFile(ctx, fileMeta.FilePath)
+	if err != nil {
+		t.Fatalf("DownloadFile failed: %v", err)
+	}
+	defer body.Close()
+
+	data, err := io.ReadAll(body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	if len(data) == 0 {
+		t.Fatal("downloaded file has 0 bytes")
+	}
+	if contentType == "" {
+		t.Error("content-type should not be empty")
+	}
+
+	t.Logf("OK  file_id=%s path=%s api_size=%d content_type=%s downloaded=%d",
+		fileMeta.FileID, fileMeta.FilePath, size, contentType, len(data))
+}
+
+func TestE2E_04_DownloadAndStore(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	photoFileID, photoUniqueID := findPhotoIDs(t, b, ctx)
+	if photoFileID == "" {
+		t.Fatal("expected a photo from seed, got none")
+	}
+
+	groups := []string{"telegram", "e2e-test"}
+
+	result, err := b.DownloadAndStore(ctx, photoFileID, photoUniqueID, "image/jpeg", "test_photo.jpg", groups)
+	if err != nil {
+		t.Fatalf("DownloadAndStore failed: %v", err)
+	}
+	if result.Wrapper == "" {
+		t.Fatal("wrapper should not be empty")
+	}
+	if !strings.HasPrefix(result.Wrapper, defaultUploader+"://") {
+		t.Errorf("wrapper should start with %s://, got %s", defaultUploader, result.Wrapper)
+	}
+	if result.MimeType == "" {
+		t.Error("mime_type should not be empty")
+	}
+	if result.FileName == "" {
+		t.Error("file_name should not be empty")
+	}
+
+	manager := attachment.Managers[defaultUploader]
+	_, fileID, _ := attachment.Parse(result.Wrapper)
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		t.Fatalf("attachment.Download failed: %v", err)
+	}
+	defer resp.Reader.Close()
+	stored, err := io.ReadAll(resp.Reader)
+	if err != nil {
+		t.Fatalf("read stored: %v", err)
+	}
+	if len(stored) == 0 {
+		t.Fatal("stored file has 0 bytes")
+	}
+	t.Logf("OK  wrapper=%s stored_bytes=%d content_type=%s", result.Wrapper, len(stored), resp.ContentType)
+
+	result2, err := b.DownloadAndStore(ctx, photoFileID, photoUniqueID, "image/jpeg", "test_photo.jpg", groups)
+	if err != nil {
+		t.Fatalf("DownloadAndStore (dedup) failed: %v", err)
+	}
+	if result2.Wrapper != result.Wrapper {
+		t.Errorf("dedup failed: first=%s second=%s", result.Wrapper, result2.Wrapper)
+	}
+	t.Log("OK  dedup verified")
+}
+
+func TestE2E_05_SendMessage(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	err := b.SendMessage(ctx, chatID, fmt.Sprintf("*E2E test* at `%s`", time.Now().Format(time.RFC3339)), 0)
+	if err != nil {
+		t.Fatalf("SendMessage failed: %v", err)
+	}
+	t.Logf("OK  sent text message to chat=%d", chatID)
+}
+
+func TestE2E_06_SendMedia_Wrapper(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		t.Fatal("attachment manager not found")
+	}
+
+	imgData := generateTestPNG()
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: "e2e_test.png",
+			Size:     int64(len(imgData)),
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", "image/png")
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(imgData), attachment.UploadOption{
+		OriginalFilename: "e2e_test.png",
+		Groups:           []string{"telegram", "e2e-test"},
+	})
+	if err != nil {
+		t.Fatalf("attachment upload failed: %v", err)
+	}
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	if uploaded.Bytes <= 0 {
+		t.Error("uploaded.Bytes should be > 0")
+	}
+	t.Logf("uploaded wrapper=%s bytes=%d", wrapper, uploaded.Bytes)
+
+	err = b.SendMedia(ctx, chatID, wrapper, "E2E attachment test", 0)
+	if err != nil {
+		t.Fatalf("SendMedia(wrapper) failed: %v", err)
+	}
+	t.Logf("OK  sent media via wrapper to chat=%d", chatID)
+}
+
+func TestE2E_07_SendMediaByReader(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	imgData := generateTestPNG()
+	err := b.SendMediaByReader(ctx, chatID, MediaPhoto, "e2e_test.png", bytes.NewReader(imgData), "E2E reader test", 0)
+	if err != nil {
+		t.Fatalf("SendMediaByReader failed: %v", err)
+	}
+	t.Logf("OK  sent photo via reader to chat=%d", chatID)
+}
+
+// --------------- helpers ---------------
+
+func fetchUpdates(t *testing.T, b *Bot, ctx context.Context) []*ConvertedMessage {
+	t.Helper()
+	updates, err := b.GetUpdates(ctx, 0, 5, nil)
+	if err != nil {
+		t.Fatalf("GetUpdates: %v", err)
+	}
+	return updates
+}
+
+func findChatID(t *testing.T, b *Bot, ctx context.Context) int64 {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm != nil && cm.ChatID != 0 {
+			return cm.ChatID
+		}
+	}
+	return 0
+}
+
+func findFileID(t *testing.T, b *Bot, ctx context.Context) string {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm == nil {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			if m.Type == MediaPhoto || m.Type == MediaDocument {
+				return m.FileID
+			}
+		}
+	}
+	return ""
+}
+
+func findPhotoIDs(t *testing.T, b *Bot, ctx context.Context) (fileID, uniqueID string) {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm == nil {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			if m.Type == MediaPhoto {
+				return m.FileID, m.FileUniqueID
+			}
+		}
+	}
+	return "", ""
+}
+
+func safeUserID(u *User) int64 {
+	if u == nil {
+		return 0
+	}
+	return u.ID
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max] + "..."
+}
+
+// generateTestPNG produces a 100x100 red PNG that Telegram will accept.
+func generateTestPNG() []byte {
+	img := image.NewRGBA(image.Rect(0, 0, 100, 100))
+	red := color.RGBA{R: 255, A: 255}
+	for y := 0; y < 100; y++ {
+		for x := 0; x < 100; x++ {
+			img.Set(x, y, red)
+		}
+	}
+	var buf bytes.Buffer
+	_ = png.Encode(&buf, img)
+	return buf.Bytes()
+}

integrations/telegram/file.go

@@ -0,0 +1,206 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/attachment"
+)
+
+const defaultUploader = "__yao.attachment"
+
+// FileResult holds the attachment wrapper and metadata for a downloaded
+// Telegram file that has been stored via the attachment manager.
+type FileResult struct {
+	Wrapper  string // e.g. __yao.attachment://ccd472d11feb96e03a3fc468f494045c
+	MimeType string
+	FileName string
+}
+
+// GetFile retrieves file metadata (including download path) for a given file_id.
+// Uses raw HTTP for compatibility with both official and local Bot API servers.
+func (b *Bot) GetFile(ctx context.Context, fileID string) (*models.File, error) {
+	body, err := json.Marshal(map[string]string{"file_id": fileID})
+	if err != nil {
+		return nil, fmt.Errorf("marshal: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", b.botURL()+"/getFile", bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	var result struct {
+		OK     bool        `json:"ok"`
+		Result models.File `json:"result"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("getFile: API returned ok=false, body=%s", string(respBody))
+	}
+	return &result.Result, nil
+}
+
+// DownloadFile downloads a file given its file_path from GetFile.
+// Returns the response body (caller must close), content type, and file size.
+// When file_path is an absolute path (local Bot API server --local mode),
+// the file is read directly from disk instead of HTTP download.
+func (b *Bot) DownloadFile(ctx context.Context, filePath string) (io.ReadCloser, string, int64, error) {
+	if strings.HasPrefix(filePath, "/") {
+		f, err := os.Open(filePath)
+		if err != nil {
+			return nil, "", 0, fmt.Errorf("open local file: %w", err)
+		}
+		info, _ := f.Stat()
+		var size int64
+		if info != nil {
+			size = info.Size()
+		}
+		return f, "application/octet-stream", size, nil
+	}
+
+	url := b.fileURL(filePath)
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return nil, "", 0, err
+	}
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, "", 0, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		return nil, "", 0, fmt.Errorf("download file: status %d", resp.StatusCode)
+	}
+	return resp.Body, resp.Header.Get("Content-Type"), resp.ContentLength, nil
+}
+
+// DownloadAndStore downloads a Telegram file by file_id, stores it through the
+// attachment manager, and returns the wrapper string. Uses file_unique_id as
+// the Content-Fingerprint so that the same Telegram file is never downloaded
+// and stored twice — attachment's built-in fingerprint dedup handles it.
+func (b *Bot) DownloadAndStore(ctx context.Context, tgFileID, fileUniqueID, mimeType, filename string, groups []string) (*FileResult, error) {
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	probeID := fingerprintFileID(fileUniqueID, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		log.Trace("telegram file: cache hit file_unique_id=%s wrapper=%s", fileUniqueID, wrapper)
+		return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: filename}, nil
+	}
+
+	fileMeta, err := b.GetFile(ctx, tgFileID)
+	if err != nil {
+		return nil, fmt.Errorf("getFile: %w", err)
+	}
+
+	body, contentType, size, err := b.DownloadFile(ctx, fileMeta.FilePath)
+	if err != nil {
+		return nil, fmt.Errorf("download: %w", err)
+	}
+	defer body.Close()
+
+	if contentType != "" && mimeType == "application/octet-stream" {
+		mimeType = contentType
+	}
+
+	data, err := io.ReadAll(body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+	if size <= 0 {
+		size = int64(len(data))
+	}
+
+	ext := filepath.Ext(filename)
+
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: filename,
+			Size:     size,
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", mimeType)
+	header.Header.Set("Content-Fingerprint", fileUniqueID)
+	if ext != "" {
+		header.Header.Set("Content-Extension", ext)
+	}
+
+	option := attachment.UploadOption{
+		OriginalFilename: filename,
+		Groups:           groups,
+	}
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), option)
+	if err != nil {
+		return nil, fmt.Errorf("attachment upload: %w", err)
+	}
+
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: filename}, nil
+}
+
+// ResolveMedia downloads and stores all media items in the ConvertedMessage,
+// filling each MediaItem.Wrapper with the attachment wrapper string.
+// Items that fail to download are logged and left with an empty Wrapper.
+func (b *Bot) ResolveMedia(ctx context.Context, cm *ConvertedMessage, groups []string) {
+	if cm == nil {
+		return
+	}
+	for i := range cm.MediaItems {
+		mi := &cm.MediaItems[i]
+		result, err := b.DownloadAndStore(ctx, mi.FileID, mi.FileUniqueID, mi.MimeType, mi.FileName, groups)
+		if err != nil {
+			log.Error("telegram ResolveMedia: %s %s: %v", mi.Type, mi.FileID, err)
+			continue
+		}
+		mi.Wrapper = result.Wrapper
+		if result.MimeType != "" {
+			mi.MimeType = result.MimeType
+		}
+	}
+}
+
+// fingerprintFileID reproduces the file_id that attachment.Manager would
+// generate when Content-Fingerprint is set, so we can probe Exists() before
+// downloading anything.
+func fingerprintFileID(fileUniqueID string, groups []string) string {
+	parts := make([]string, 0, len(groups)+1)
+	parts = append(parts, groups...)
+	parts = append(parts, fileUniqueID)
+	storagePath := strings.Join(parts, "/")
+	hash := md5.Sum([]byte(storagePath))
+	return hex.EncodeToString(hash[:])
+}

integrations/telegram/file_test.go

@@ -0,0 +1,35 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestFingerprintFileID(t *testing.T) {
+	id1 := fingerprintFileID("unique1", []string{"telegram", "bot123"})
+	id2 := fingerprintFileID("unique1", []string{"telegram", "bot123"})
+	if id1 != id2 {
+		t.Fatalf("same input should produce same fingerprint, got %s vs %s", id1, id2)
+	}
+
+	id3 := fingerprintFileID("unique2", []string{"telegram", "bot123"})
+	if id1 == id3 {
+		t.Fatalf("different file_unique_id should produce different fingerprint")
+	}
+
+	id4 := fingerprintFileID("unique1", []string{"telegram", "bot456"})
+	if id1 == id4 {
+		t.Fatalf("different groups should produce different fingerprint")
+	}
+
+	id5 := fingerprintFileID("unique1", nil)
+	if id5 == "" {
+		t.Fatal("nil groups should still produce a valid fingerprint")
+	}
+	if id5 == id1 {
+		t.Fatal("nil groups vs non-nil groups should differ")
+	}
+
+	if len(id1) != 32 {
+		t.Fatalf("fingerprint should be 32 hex chars (md5), got length %d", len(id1))
+	}
+}

integrations/telegram/format.go

@@ -0,0 +1,219 @@
+package telegram
+
+import (
+	"html"
+	"regexp"
+	"strings"
+)
+
+// FormatTelegramHTML converts standard Markdown to the HTML subset supported by
+// Telegram's Bot API. Unsupported constructs (tables, images, etc.) are
+// gracefully degraded to plain text.
+//
+// Supported Telegram HTML tags: <b>, <i>, <u>, <s>, <code>, <pre>, <a>, <blockquote>
+func FormatTelegramHTML(md string) string {
+	md = strings.ReplaceAll(md, "\r\n", "\n")
+
+	var out strings.Builder
+	lines := strings.Split(md, "\n")
+
+	inCodeBlock := false
+	var codeLang string
+	var codeLines []string
+
+	inTable := false
+	var tableRows [][]string
+
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+
+		if strings.HasPrefix(line, "```") {
+			if !inCodeBlock {
+				inCodeBlock = true
+				codeLang = strings.TrimSpace(strings.TrimPrefix(line, "```"))
+				codeLines = nil
+			} else {
+				inCodeBlock = false
+				if codeLang != "" {
+					out.WriteString("<pre><code class=\"language-" + html.EscapeString(codeLang) + "\">")
+				} else {
+					out.WriteString("<pre>")
+				}
+				out.WriteString(html.EscapeString(strings.Join(codeLines, "\n")))
+				if codeLang != "" {
+					out.WriteString("</code></pre>\n")
+				} else {
+					out.WriteString("</pre>\n")
+				}
+			}
+			continue
+		}
+		if inCodeBlock {
+			codeLines = append(codeLines, line)
+			continue
+		}
+
+		if isTableRow(line) {
+			if !inTable {
+				inTable = true
+				tableRows = nil
+			}
+			if isTableSeparator(line) {
+				continue
+			}
+			tableRows = append(tableRows, parseTableRow(line))
+			continue
+		}
+		if inTable {
+			flushTable(&out, tableRows)
+			inTable = false
+			tableRows = nil
+		}
+
+		if line == "---" || line == "***" || line == "___" {
+			out.WriteString("——————\n")
+			continue
+		}
+
+		if m := reHeading.FindStringSubmatch(line); m != nil {
+			out.WriteString("<b>" + formatInline(html.EscapeString(m[2])) + "</b>\n")
+			continue
+		}
+
+		if m := reBlockquote.FindStringSubmatch(line); m != nil {
+			out.WriteString("<blockquote>" + formatInline(html.EscapeString(m[1])) + "</blockquote>\n")
+			continue
+		}
+
+		if m := reUnorderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString("• " + formatInline(html.EscapeString(m[1])) + "\n")
+			continue
+		}
+
+		if m := reOrderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString(m[1] + ". " + formatInline(html.EscapeString(m[2])) + "\n")
+			continue
+		}
+
+		out.WriteString(formatInline(html.EscapeString(line)) + "\n")
+	}
+
+	if inCodeBlock && len(codeLines) > 0 {
+		out.WriteString("<pre>" + html.EscapeString(strings.Join(codeLines, "\n")) + "</pre>\n")
+	}
+	if inTable {
+		flushTable(&out, tableRows)
+	}
+
+	return strings.TrimRight(out.String(), "\n")
+}
+
+var (
+	reHeading       = regexp.MustCompile(`^(#{1,6})\s+(.+)$`)
+	reBlockquote    = regexp.MustCompile(`^>\s*(.*)$`)
+	reUnorderedList = regexp.MustCompile(`^[\s]*[-*+]\s+(.+)$`)
+	reOrderedList   = regexp.MustCompile(`^[\s]*(\d+)[.)]\s+(.+)$`)
+
+	reBold          = regexp.MustCompile(`\*\*(.+?)\*\*`)
+	reBoldAlt       = regexp.MustCompile(`__(.+?)__`)
+	reItalic        = regexp.MustCompile(`(?:^|[^*])\*([^*]+?)\*(?:[^*]|$)`)
+	reItalicAlt     = regexp.MustCompile(`(?:^|[^_])_([^_]+?)_(?:[^_]|$)`)
+	reStrikethrough = regexp.MustCompile(`~~(.+?)~~`)
+	reCode          = regexp.MustCompile("`([^`]+)`")
+	reLink          = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`)
+
+	reTableRow = regexp.MustCompile(`^\|.*\|$`)
+	reTableSep = regexp.MustCompile(`^\|[\s\-:|]+\|$`)
+)
+
+// formatInline applies inline Markdown formatting to already HTML-escaped text.
+// Order matters: code first (to protect its content), then links, bold, italic, etc.
+func formatInline(escaped string) string {
+	escaped = reCode.ReplaceAllString(escaped, "<code>$1</code>")
+
+	escaped = reLink.ReplaceAllStringFunc(escaped, func(match string) string {
+		m := reLink.FindStringSubmatch(match)
+		if len(m) < 3 {
+			return match
+		}
+		return `<a href="` + unescapeHTML(m[2]) + `">` + m[1] + `</a>`
+	})
+
+	escaped = reBold.ReplaceAllString(escaped, "<b>$1</b>")
+	escaped = reBoldAlt.ReplaceAllString(escaped, "<b>$1</b>")
+	escaped = reStrikethrough.ReplaceAllString(escaped, "<s>$1</s>")
+
+	return escaped
+}
+
+func unescapeHTML(s string) string {
+	return html.UnescapeString(s)
+}
+
+func isTableRow(line string) bool {
+	return reTableRow.MatchString(strings.TrimSpace(line))
+}
+
+func isTableSeparator(line string) bool {
+	return reTableSep.MatchString(strings.TrimSpace(line))
+}
+
+func parseTableRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	cells := strings.Split(line, "|")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+func flushTable(out *strings.Builder, rows [][]string) {
+	if len(rows) == 0 {
+		return
+	}
+	out.WriteString("<pre>")
+	colWidths := make([]int, len(rows[0]))
+	for _, row := range rows {
+		for i, cell := range row {
+			if i < len(colWidths) && len(cell) > colWidths[i] {
+				colWidths[i] = len(cell)
+			}
+		}
+	}
+	for ri, row := range rows {
+		for ci, cell := range row {
+			if ci > 0 {
+				out.WriteString(" | ")
+			}
+			w := 0
+			if ci < len(colWidths) {
+				w = colWidths[ci]
+			}
+			out.WriteString(html.EscapeString(padRight(cell, w)))
+		}
+		out.WriteString("\n")
+		if ri == 0 && len(rows) > 1 {
+			for ci := range row {
+				if ci > 0 {
+					out.WriteString("-+-")
+				}
+				w := 0
+				if ci < len(colWidths) {
+					w = colWidths[ci]
+				}
+				out.WriteString(strings.Repeat("-", w))
+			}
+			out.WriteString("\n")
+		}
+	}
+	out.WriteString("</pre>\n")
+}
+
+func padRight(s string, width int) string {
+	if len(s) >= width {
+		return s
+	}
+	return s + strings.Repeat(" ", width-len(s))
+}

integrations/telegram/media_e2e_test.go

@@ -0,0 +1,299 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/textproto"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/yaoapp/yao/attachment"
+)
+
+type mediaTestCase struct {
+	name      string
+	file      string // relative to testdata/
+	mimeType  string
+	mediaType MediaType
+}
+
+var mediaTestCases = []mediaTestCase{
+	{"jpg", "test.jpg", "image/jpeg", MediaPhoto},
+	{"png", "test.png", "image/png", MediaPhoto},
+	{"gif", "test.gif", "image/gif", MediaAnimation},
+	{"webp", "test.webp", "image/webp", MediaSticker},
+	{"mp3", "test.mp3", "audio/mpeg", MediaAudio},
+	{"ogg", "test.ogg", "audio/ogg", MediaVoice},
+	{"mp4", "test.mp4", "video/mp4", MediaVideo},
+	{"pdf", "test.pdf", "application/pdf", MediaDocument},
+	{"docx", "test.docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", MediaDocument},
+	{"pptx", "test.pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation", MediaDocument},
+}
+
+func readTestFile(t *testing.T, name string) []byte {
+	t.Helper()
+	data, err := os.ReadFile("../testdata/" + name)
+	if err != nil {
+		t.Fatalf("read ../testdata/%s: %v", name, err)
+	}
+	if len(data) == 0 {
+		t.Fatalf("../testdata/%s is empty", name)
+	}
+	return data
+}
+
+func TestE2E_08_SendMediaByReader_MultiType(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("no chat_id")
+	}
+
+	for _, tc := range mediaTestCases {
+		t.Run(tc.name, func(t *testing.T) {
+			data := readTestFile(t, tc.file)
+
+			detected := DetectMediaType(tc.mimeType)
+			if detected != tc.mediaType {
+				t.Errorf("DetectMediaType(%q) = %q, want %q", tc.mimeType, detected, tc.mediaType)
+			}
+
+			err := b.SendMediaByReader(ctx, chatID, tc.mediaType, tc.file, bytes.NewReader(data), fmt.Sprintf("E2E %s %d bytes", tc.name, len(data)), 0)
+			if err != nil {
+				t.Fatalf("SendMediaByReader(%s) failed: %v", tc.name, err)
+			}
+			t.Logf("OK  %s %s %d bytes -> chat=%d", tc.name, tc.mimeType, len(data), chatID)
+		})
+	}
+}
+
+func TestE2E_09_SendMedia_Wrapper_MultiType(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("no chat_id")
+	}
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		t.Fatal("attachment manager not found")
+	}
+
+	for _, tc := range mediaTestCases {
+		t.Run(tc.name, func(t *testing.T) {
+			data := readTestFile(t, tc.file)
+
+			header := &attachment.FileHeader{
+				FileHeader: &multipart.FileHeader{
+					Filename: tc.file,
+					Size:     int64(len(data)),
+					Header:   make(textproto.MIMEHeader),
+				},
+			}
+			header.Header.Set("Content-Type", tc.mimeType)
+
+			uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), attachment.UploadOption{
+				OriginalFilename: tc.file,
+				Groups:           []string{"telegram", "e2e-media"},
+			})
+			if err != nil {
+				t.Fatalf("upload %s: %v", tc.name, err)
+			}
+
+			wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+
+			err = b.SendMedia(ctx, chatID, wrapper, fmt.Sprintf("E2E wrapper %s", tc.name), 0)
+			if err != nil {
+				t.Fatalf("SendMedia(%s) failed: %v", tc.name, err)
+			}
+			t.Logf("OK  %s -> %s -> chat=%d", tc.name, wrapper, chatID)
+		})
+	}
+}
+
+// TestE2E_10_Receive_DownloadAndStore_Dedup pulls updates from the bot,
+// finds media messages (seeded by TestE2E_00_Seed), and for each one:
+//  1. DownloadAndStore -> verify wrapper format + stored bytes > 0
+//  2. Read back from attachment manager -> verify content non-empty
+//  3. Call DownloadAndStore again -> verify same wrapper (fingerprint dedup)
+func TestE2E_10_Receive_DownloadAndStore_Dedup(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	updates := fetchUpdates(t, b, ctx)
+	if len(updates) == 0 {
+		t.Fatal("no updates")
+	}
+
+	groups := []string{"telegram", "e2e-recv"}
+	manager := attachment.Managers[defaultUploader]
+	if manager == nil {
+		t.Fatal("attachment manager not found")
+	}
+
+	type mediaHit struct {
+		kind         string
+		fileID       string
+		fileUniqueID string
+		mimeType     string
+		filename     string
+	}
+
+	var hits []mediaHit
+	for _, cm := range updates {
+		if cm == nil || !cm.HasMedia() {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			mime := m.MimeType
+			if mime == "" {
+				mime = "application/octet-stream"
+			}
+			name := m.FileName
+			if name == "" {
+				name = string(m.Type)
+			}
+			hits = append(hits, mediaHit{string(m.Type), m.FileID, m.FileUniqueID, mime, name})
+		}
+	}
+
+	if len(hits) == 0 {
+		t.Fatal("no media messages found in updates")
+	}
+	t.Logf("found %d media items in updates", len(hits))
+
+	for i, h := range hits {
+		t.Run(fmt.Sprintf("%s_%d", h.kind, i), func(t *testing.T) {
+			// 1. DownloadAndStore
+			result, err := b.DownloadAndStore(ctx, h.fileID, h.fileUniqueID, h.mimeType, h.filename, groups)
+			if err != nil {
+				t.Fatalf("DownloadAndStore: %v", err)
+			}
+			if result.Wrapper == "" {
+				t.Fatal("wrapper is empty")
+			}
+			if !strings.HasPrefix(result.Wrapper, defaultUploader+"://") {
+				t.Errorf("wrapper format: %s", result.Wrapper)
+			}
+			if result.FileName == "" {
+				t.Error("filename is empty")
+			}
+
+			// 2. Read back from attachment
+			_, fileID, ok := attachment.Parse(result.Wrapper)
+			if !ok {
+				t.Fatalf("failed to parse wrapper: %s", result.Wrapper)
+			}
+			resp, err := manager.Download(ctx, fileID)
+			if err != nil {
+				t.Fatalf("attachment Download: %v", err)
+			}
+			stored, err := io.ReadAll(resp.Reader)
+			resp.Reader.Close()
+			if err != nil {
+				t.Fatalf("read stored: %v", err)
+			}
+			if len(stored) == 0 {
+				t.Fatal("stored file is 0 bytes")
+			}
+
+			// 3. Dedup: same file_unique_id -> same wrapper
+			result2, err := b.DownloadAndStore(ctx, h.fileID, h.fileUniqueID, h.mimeType, h.filename, groups)
+			if err != nil {
+				t.Fatalf("DownloadAndStore dedup: %v", err)
+			}
+			if result2.Wrapper != result.Wrapper {
+				t.Errorf("dedup failed: %s vs %s", result.Wrapper, result2.Wrapper)
+			}
+
+			t.Logf("OK  %s unique=%s wrapper=%s stored=%d dedup=ok",
+				h.kind, h.fileUniqueID, result.Wrapper, len(stored))
+		})
+	}
+}
+
+// TestE2E_99_Offset_Confirm runs last (highest number, file sorted after e2e_test.go).
+// It validates offset-based acknowledgement and confirm semantics:
+//  1. offset=last_id returns from last_id onwards (confirms ids < last_id)
+//  2. offset=last_id+1 confirms all, subsequent offset=0 returns nothing old
+func TestE2E_99_Offset_Confirm(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	updates, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("initial pull: %v", err)
+	}
+	if len(updates) == 0 {
+		t.Skip("no pending updates to test offset confirm")
+	}
+	firstID := int64(updates[0].ID)
+	lastID := int64(updates[len(updates)-1].ID)
+	t.Logf("pending updates: count=%d first_id=%d last_id=%d", len(updates), firstID, lastID)
+
+	// offset = last_id: confirms everything with id < last_id, returns from last_id
+	partial, err := b.GetRawUpdates(ctx, lastID, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=last_id=%d): %v", lastID, err)
+	}
+	if len(partial) == 0 {
+		t.Error("offset=last_id returned 0 updates, expected at least 1")
+	}
+	if len(partial) > 0 && int64(partial[0].ID) != lastID {
+		t.Errorf("offset=last_id: first_id=%d, want %d", partial[0].ID, lastID)
+	}
+	for _, p := range partial {
+		if int64(p.ID) < lastID {
+			t.Errorf("offset=last_id: got update_id=%d < %d", p.ID, lastID)
+		}
+	}
+	t.Logf("offset=last_id(%d): returned=%d, first_id=%d", lastID, len(partial), partial[0].ID)
+
+	// offset = last_id+1: confirms all remaining updates
+	confirmOffset := lastID + 1
+	afterConfirm, err := b.GetRawUpdates(ctx, confirmOffset, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=%d): %v", confirmOffset, err)
+	}
+	for _, ac := range afterConfirm {
+		if int64(ac.ID) <= lastID {
+			t.Errorf("post-confirm: got update_id=%d <= %d", ac.ID, lastID)
+		}
+	}
+	t.Logf("confirm offset=%d: returned=%d new", confirmOffset, len(afterConfirm))
+
+	// Re-pull offset=0: old updates should be purged
+	repull, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=0 post-confirm): %v", err)
+	}
+	for _, r := range repull {
+		if int64(r.ID) <= lastID {
+			t.Errorf("post-confirm offset=0: stale update_id=%d (expected > %d)", r.ID, lastID)
+		}
+	}
+	t.Logf("post-confirm offset=0: returned=%d (old updates purged)", len(repull))
+}

integrations/telegram/message.go

@@ -0,0 +1,200 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/yao/attachment"
+)
+
+// SendMessage sends a message to a chat. If the text contains Markdown formatting,
+// it is automatically converted to Telegram-compatible HTML.
+func (b *Bot) SendMessage(ctx context.Context, chatID int64, text string, replyTo int64) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+
+	formatted := FormatTelegramHTML(text)
+	params := &bot.SendMessageParams{
+		ChatID:    chatID,
+		Text:      formatted,
+		ParseMode: models.ParseModeHTML,
+	}
+	if replyTo > 0 {
+		params.ReplyParameters = &models.ReplyParameters{MessageID: int(replyTo)}
+	}
+	_, err = sdk.SendMessage(ctx, params)
+	return err
+}
+
+// MediaType indicates which Telegram send method to use.
+type MediaType string
+
+const (
+	MediaPhoto     MediaType = "photo"
+	MediaDocument  MediaType = "document"
+	MediaAudio     MediaType = "audio"
+	MediaVideo     MediaType = "video"
+	MediaVoice     MediaType = "voice"
+	MediaAnimation MediaType = "animation"
+	MediaSticker   MediaType = "sticker"
+)
+
+// SendMedia sends a media message from a Yao attachment wrapper
+// (e.g. "__yao.attachment://ccd472d11feb96e03a3fc468f494045c").
+// It reads the file from the attachment manager, detects the media type from
+// the stored content type, and uploads it to the Telegram chat.
+func (b *Bot) SendMedia(ctx context.Context, chatID int64, wrapper string, caption string, replyTo int64) error {
+	managerName, fileID, err := parseWrapper(wrapper)
+	if err != nil {
+		return err
+	}
+
+	manager, exists := attachment.Managers[managerName]
+	if !exists {
+		return fmt.Errorf("attachment manager %s not found", managerName)
+	}
+
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		return fmt.Errorf("attachment download %s: %w", fileID, err)
+	}
+	defer resp.Reader.Close()
+
+	mediaType := DetectMediaType(resp.ContentType)
+	filename := fileID + resp.Extension
+
+	file := &models.InputFileUpload{Filename: filename, Data: resp.Reader}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// SendMediaByURL sends a media message from a public URL.
+// Telegram downloads the file directly from the URL.
+func (b *Bot) SendMediaByURL(ctx context.Context, chatID int64, mediaType MediaType, url string, caption string, replyTo int64) error {
+	file := &models.InputFileString{Data: url}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// SendMediaByReader sends a media message by uploading raw bytes.
+func (b *Bot) SendMediaByReader(ctx context.Context, chatID int64, mediaType MediaType, filename string, data io.Reader, caption string, replyTo int64) error {
+	file := &models.InputFileUpload{Filename: filename, Data: data}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// DetectMediaType guesses the MediaType from a MIME string.
+// Falls back to MediaDocument for unknown types.
+func DetectMediaType(mimeType string) MediaType {
+	lower := strings.ToLower(mimeType)
+	switch {
+	case strings.HasPrefix(lower, "image/webp"):
+		return MediaSticker
+	case strings.HasPrefix(lower, "image/gif"):
+		return MediaAnimation
+	case strings.HasPrefix(lower, "image/"):
+		return MediaPhoto
+	case strings.HasPrefix(lower, "video/"):
+		return MediaVideo
+	case strings.HasPrefix(lower, "audio/ogg"):
+		return MediaVoice
+	case strings.HasPrefix(lower, "audio/"):
+		return MediaAudio
+	default:
+		return MediaDocument
+	}
+}
+
+// parseWrapper splits "__yao.attachment://fileID" into manager name and file ID.
+func parseWrapper(wrapper string) (managerName string, fileID string, err error) {
+	idx := strings.Index(wrapper, "://")
+	if idx < 0 {
+		return "", "", fmt.Errorf("invalid attachment wrapper: %s", wrapper)
+	}
+	return wrapper[:idx], wrapper[idx+3:], nil
+}
+
+func (b *Bot) sendMedia(ctx context.Context, chatID int64, mediaType MediaType, file models.InputFile, caption string, replyTo int64) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+
+	var replyParams *models.ReplyParameters
+	if replyTo > 0 {
+		replyParams = &models.ReplyParameters{MessageID: int(replyTo)}
+	}
+
+	htmlCaption := FormatTelegramHTML(caption)
+
+	switch mediaType {
+	case MediaPhoto:
+		_, err = sdk.SendPhoto(ctx, &bot.SendPhotoParams{
+			ChatID:          chatID,
+			Photo:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaDocument:
+		_, err = sdk.SendDocument(ctx, &bot.SendDocumentParams{
+			ChatID:          chatID,
+			Document:        file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaAudio:
+		_, err = sdk.SendAudio(ctx, &bot.SendAudioParams{
+			ChatID:          chatID,
+			Audio:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaVideo:
+		_, err = sdk.SendVideo(ctx, &bot.SendVideoParams{
+			ChatID:          chatID,
+			Video:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaVoice:
+		_, err = sdk.SendVoice(ctx, &bot.SendVoiceParams{
+			ChatID:          chatID,
+			Voice:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaAnimation:
+		_, err = sdk.SendAnimation(ctx, &bot.SendAnimationParams{
+			ChatID:          chatID,
+			Animation:       file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaSticker:
+		_, err = sdk.SendSticker(ctx, &bot.SendStickerParams{
+			ChatID:          chatID,
+			Sticker:         file,
+			ReplyParameters: replyParams,
+		})
+
+	default:
+		return fmt.Errorf("unsupported media type: %s", mediaType)
+	}
+
+	return err
+}

integrations/telegram/message_test.go

@@ -0,0 +1,64 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestDetectMediaType(t *testing.T) {
+	cases := []struct {
+		mime     string
+		expected MediaType
+	}{
+		{"image/jpeg", MediaPhoto},
+		{"image/png", MediaPhoto},
+		{"IMAGE/PNG", MediaPhoto},
+		{"image/gif", MediaAnimation},
+		{"image/webp", MediaSticker},
+		{"video/mp4", MediaVideo},
+		{"video/webm", MediaVideo},
+		{"audio/mpeg", MediaAudio},
+		{"audio/mp3", MediaAudio},
+		{"audio/ogg", MediaVoice},
+		{"audio/ogg; codecs=opus", MediaVoice},
+		{"application/pdf", MediaDocument},
+		{"application/octet-stream", MediaDocument},
+		{"text/plain", MediaDocument},
+		{"", MediaDocument},
+	}
+	for _, tc := range cases {
+		got := DetectMediaType(tc.mime)
+		if got != tc.expected {
+			t.Errorf("DetectMediaType(%q) = %q, want %q", tc.mime, got, tc.expected)
+		}
+	}
+}
+
+func TestParseWrapper(t *testing.T) {
+	cases := []struct {
+		input   string
+		manager string
+		fileID  string
+		wantErr bool
+	}{
+		{"__yao.attachment://abc123", "__yao.attachment", "abc123", false},
+		{"__custom.uploader://xyz", "__custom.uploader", "xyz", false},
+		{"no-separator", "", "", true},
+		{"://empty-manager", "", "empty-manager", false},
+	}
+	for _, tc := range cases {
+		manager, fileID, err := parseWrapper(tc.input)
+		if tc.wantErr {
+			if err == nil {
+				t.Errorf("parseWrapper(%q) expected error, got nil", tc.input)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("parseWrapper(%q) unexpected error: %v", tc.input, err)
+			continue
+		}
+		if manager != tc.manager || fileID != tc.fileID {
+			t.Errorf("parseWrapper(%q) = (%q, %q), want (%q, %q)", tc.input, manager, fileID, tc.manager, tc.fileID)
+		}
+	}
+}

integrations/telegram/polling.go

@@ -0,0 +1,81 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// GetUpdates fetches new updates via long polling and returns them as
+// ConvertedMessages ready for consumption. Non-message updates (e.g.
+// callback_query without a message) are silently skipped.
+// When groups is non-nil, media attachments are automatically downloaded
+// and stored via DownloadAndStore, filling each MediaItem.Wrapper.
+func (b *Bot) GetUpdates(ctx context.Context, offset int64, timeout int, groups []string) ([]*ConvertedMessage, error) {
+	raw, err := b.GetRawUpdates(ctx, offset, timeout)
+	if err != nil {
+		return nil, err
+	}
+	var msgs []*ConvertedMessage
+	for i := range raw {
+		if cm := ConvertUpdate(&raw[i]); cm != nil {
+			if groups != nil && cm.HasMedia() {
+				b.ResolveMedia(ctx, cm, groups)
+			}
+			msgs = append(msgs, cm)
+		}
+	}
+	return msgs, nil
+}
+
+// GetRawUpdates fetches raw Telegram updates without conversion.
+// Use this when you need access to the original models.Update (e.g. for
+// offset tracking). Uses raw HTTP because the SDK keeps getUpdates private.
+func (b *Bot) GetRawUpdates(ctx context.Context, offset int64, timeout int) ([]models.Update, error) {
+	params := map[string]interface{}{
+		"offset":  offset,
+		"timeout": timeout,
+		"limit":   100,
+	}
+	body, err := json.Marshal(params)
+	if err != nil {
+		return nil, fmt.Errorf("marshal params: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", b.botURL()+"/getUpdates", bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("telegram API error status=%d body=%s", resp.StatusCode, string(respBody))
+	}
+
+	var result struct {
+		OK     bool            `json:"ok"`
+		Result []models.Update `json:"result"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal response: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("telegram API returned ok=false")
+	}
+	return result.Result, nil
+}

integrations/telegram/telegram_test.go

@@ -0,0 +1,177 @@
+package telegram
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gotd/td/session"
+	"github.com/gotd/td/telegram"
+	"github.com/gotd/td/telegram/uploader"
+	"github.com/gotd/td/tg"
+	"github.com/yaoapp/yao/attachment"
+	"github.com/yaoapp/yao/config"
+	"github.com/yaoapp/yao/test"
+)
+
+var testBotToken string
+
+func TestMain(m *testing.M) {
+	testBotToken = os.Getenv("TELEGRAM_TEST_BOT_TOKEN")
+	os.Exit(m.Run())
+}
+
+func prepare(t *testing.T) {
+	t.Helper()
+	test.Prepare(t, config.Conf)
+	if err := attachment.Load(config.Conf); err != nil {
+		t.Fatalf("load attachment: %v", err)
+	}
+}
+
+func cleanup() {
+	test.Clean()
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if testBotToken == "" {
+		t.Skip("TELEGRAM_TEST_BOT_TOKEN not set, skipping E2E test")
+	}
+}
+
+func testBot(opts ...BotOption) *Bot {
+	if host := os.Getenv("TELEGRAM_TEST_HOST"); host != "" {
+		opts = append([]BotOption{WithAPIBase(host)}, opts...)
+	}
+	return NewBot(testBotToken, "", opts...)
+}
+
+// seedBotMessages uses the persisted MTProto user session to send a text
+// message and a small PNG photo to the test bot, so that subsequent
+// GetUpdates calls have real data to work with.
+// Requires TG_TEST_SESSION and TG_TEST_BOT_USERNAME env vars.
+func seedBotMessages(t *testing.T) {
+	t.Helper()
+
+	sessionPath := os.Getenv("TG_TEST_SESSION")
+	botUsername := os.Getenv("TG_TEST_BOT_USERNAME")
+	if sessionPath == "" || botUsername == "" {
+		t.Skip("TG_TEST_SESSION or TG_TEST_BOT_USERNAME not set, cannot seed messages")
+	}
+
+	if !filepath.IsAbs(sessionPath) {
+		if root := os.Getenv("YAO_DEV"); root != "" {
+			sessionPath = filepath.Join(root, sessionPath)
+		}
+	}
+
+	if _, err := os.Stat(sessionPath); os.IsNotExist(err) {
+		t.Skipf("session file %s not found, run tg-login first", sessionPath)
+	}
+	t.Logf("seed: using session %s, bot @%s", sessionPath, botUsername)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	storage := &session.FileStorage{Path: sessionPath}
+	client := telegram.NewClient(17349, "344583e45741c457fe1862106095a5eb", telegram.Options{
+		SessionStorage: storage,
+	})
+
+	err := client.Run(ctx, func(ctx context.Context) error {
+		status, err := client.Auth().Status(ctx)
+		if err != nil {
+			return fmt.Errorf("auth status: %w", err)
+		}
+		if !status.Authorized {
+			return fmt.Errorf("not authorized — run tg-login first")
+		}
+
+		api := client.API()
+		resolved, err := api.ContactsResolveUsername(ctx, &tg.ContactsResolveUsernameRequest{
+			Username: botUsername,
+		})
+		if err != nil {
+			return fmt.Errorf("resolve @%s: %w", botUsername, err)
+		}
+		if len(resolved.Users) == 0 {
+			return fmt.Errorf("bot @%s not found", botUsername)
+		}
+		u, ok := resolved.Users[0].(*tg.User)
+		if !ok {
+			return fmt.Errorf("resolved entity is not a user")
+		}
+		peer := &tg.InputPeerUser{UserID: u.ID, AccessHash: u.AccessHash}
+
+		tag := time.Now().Format("15:04:05")
+		_, err = api.MessagesSendMessage(ctx, &tg.MessagesSendMessageRequest{
+			Peer:     peer,
+			Message:  fmt.Sprintf("[e2e-test] hello at %s", tag),
+			RandomID: mtpRandID(),
+		})
+		if err != nil {
+			return fmt.Errorf("send text: %w", err)
+		}
+		t.Log("seed: sent text")
+
+		up := uploader.NewUploader(api)
+
+		seedFiles := []struct {
+			path  string
+			photo bool
+			attrs []tg.DocumentAttributeClass
+		}{
+			{"../testdata/test.jpg", true, nil},
+			{"../testdata/test.mp3", false, []tg.DocumentAttributeClass{
+				&tg.DocumentAttributeAudio{Duration: 5, Title: "e2e-test"},
+			}},
+			{"../testdata/test.pdf", false, []tg.DocumentAttributeClass{
+				&tg.DocumentAttributeFilename{FileName: "test.pdf"},
+			}},
+		}
+
+		for _, sf := range seedFiles {
+			f, err := up.FromPath(ctx, sf.path)
+			if err != nil {
+				return fmt.Errorf("upload %s: %w", sf.path, err)
+			}
+			var media tg.InputMediaClass
+			if sf.photo {
+				media = &tg.InputMediaUploadedPhoto{File: f}
+			} else {
+				media = &tg.InputMediaUploadedDocument{
+					File:       f,
+					Attributes: sf.attrs,
+				}
+			}
+			_, err = api.MessagesSendMedia(ctx, &tg.MessagesSendMediaRequest{
+				Peer:     peer,
+				Media:    media,
+				Message:  fmt.Sprintf("[e2e-test] %s at %s", filepath.Base(sf.path), tag),
+				RandomID: mtpRandID(),
+			})
+			if err != nil {
+				return fmt.Errorf("send %s: %w", sf.path, err)
+			}
+			t.Logf("seed: sent %s", filepath.Base(sf.path))
+		}
+
+		time.Sleep(time.Second)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("seedBotMessages: %v", err)
+	}
+}
+
+func mtpRandID() int64 {
+	var b [8]byte
+	_, _ = rand.Read(b[:])
+	return int64(binary.LittleEndian.Uint64(b[:]))
+}

integrations/telegram/types.go

@@ -0,0 +1,21 @@
+package telegram
+
+import "github.com/go-telegram/bot/models"
+
+// Re-export SDK types so adapter code imports from one place.
+// When the SDK upgrades, any breaking field changes surface here at compile time.
+type (
+	Update    = models.Update
+	Message   = models.Message
+	User      = models.User
+	Chat      = models.Chat
+	PhotoSize = models.PhotoSize
+	Document  = models.Document
+	Voice     = models.Voice
+	Video     = models.Video
+	Sticker   = models.Sticker
+	Audio     = models.Audio
+	Animation = models.Animation
+
+	MessageEntity = models.MessageEntity
+)

integrations/telegram/verify.go

@@ -0,0 +1,53 @@
+package telegram
+
+import (
+	"context"
+	"crypto/subtle"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// GetMe calls the getMe endpoint to verify the bot token is valid.
+// Uses raw HTTP for compatibility with both official and local Bot API servers.
+func (b *Bot) GetMe(ctx context.Context) (*models.User, error) {
+	req, err := http.NewRequestWithContext(ctx, "GET", b.botURL()+"/getMe", nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	var result struct {
+		OK     bool        `json:"ok"`
+		Result models.User `json:"result"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("getMe: API returned ok=false")
+	}
+	return &result.Result, nil
+}
+
+// VerifyWebhook checks the X-Telegram-Bot-Api-Secret-Token header value
+// against the bot's configured secret_token using constant-time comparison.
+// Returns true if the secret matches or if no secret was configured.
+func (b *Bot) VerifyWebhook(headerSecret string) bool {
+	if b.secretToken == "" {
+		return true
+	}
+	return subtle.ConstantTimeCompare([]byte(b.secretToken), []byte(headerSecret)) == 1
+}

integrations/telegram/verify_test.go

@@ -0,0 +1,32 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestVerifyWebhook_NoSecret(t *testing.T) {
+	b := NewBot("token", "")
+	if !b.VerifyWebhook("anything") {
+		t.Fatal("should pass when no secret configured")
+	}
+	if !b.VerifyWebhook("") {
+		t.Fatal("should pass with empty header when no secret configured")
+	}
+}
+
+func TestVerifyWebhook_CorrectSecret(t *testing.T) {
+	b := NewBot("token", "s3cr3t-t0ken")
+	if !b.VerifyWebhook("s3cr3t-t0ken") {
+		t.Fatal("should pass with matching secret")
+	}
+}
+
+func TestVerifyWebhook_WrongSecret(t *testing.T) {
+	b := NewBot("token", "s3cr3t-t0ken")
+	if b.VerifyWebhook("wrong") {
+		t.Fatal("should reject mismatched secret")
+	}
+	if b.VerifyWebhook("") {
+		t.Fatal("should reject empty header when secret configured")
+	}
+}

integrations/telegram/webhook.go

@@ -0,0 +1,82 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+)
+
+// SetWebhook registers a webhook URL with Telegram. The configured
+// secret_token (if any) is sent along so Telegram includes it in every
+// webhook request header for verification.
+func (b *Bot) SetWebhook(ctx context.Context, url string, allowedUpdates []string) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+	params := &bot.SetWebhookParams{
+		URL:            url,
+		AllowedUpdates: allowedUpdates,
+		SecretToken:    b.secretToken,
+	}
+	if _, err := sdk.SetWebhook(ctx, params); err != nil {
+		return fmt.Errorf("setWebhook: %w", err)
+	}
+	return nil
+}
+
+// DeleteWebhook removes the webhook configuration from Telegram.
+func (b *Bot) DeleteWebhook(ctx context.Context, dropPending bool) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+	if _, err := sdk.DeleteWebhook(ctx, &bot.DeleteWebhookParams{
+		DropPendingUpdates: dropPending,
+	}); err != nil {
+		return fmt.Errorf("deleteWebhook: %w", err)
+	}
+	return nil
+}
+
+// ParseWebhookPayload reads and parses a Telegram webhook request body,
+// verifies the secret header, and returns a ConvertedMessage ready for use.
+// Returns nil message (no error) if the update contains no processable message.
+// When groups is non-nil, media attachments are automatically resolved.
+func (b *Bot) ParseWebhookPayload(ctx context.Context, r *http.Request, groups []string) (*ConvertedMessage, error) {
+	update, err := b.ParseRawWebhookPayload(r)
+	if err != nil {
+		return nil, err
+	}
+	cm := ConvertUpdate(update)
+	if cm != nil && groups != nil && cm.HasMedia() {
+		b.ResolveMedia(ctx, cm, groups)
+	}
+	return cm, nil
+}
+
+// ParseRawWebhookPayload reads and parses a Telegram webhook request body
+// into a raw models.Update. It also verifies the X-Telegram-Bot-Api-Secret-Token
+// header when a secret is configured.
+func (b *Bot) ParseRawWebhookPayload(r *http.Request) (*models.Update, error) {
+	if !b.VerifyWebhook(r.Header.Get("X-Telegram-Bot-Api-Secret-Token")) {
+		return nil, fmt.Errorf("webhook secret mismatch")
+	}
+
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+	defer r.Body.Close()
+
+	var update models.Update
+	if err := json.Unmarshal(body, &update); err != nil {
+		return nil, fmt.Errorf("unmarshal update: %w", err)
+	}
+	return &update, nil
+}

integrations/telegram/webhook_e2e_test.go

@@ -0,0 +1,280 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestE2E_Webhook requires a local telegram-bot-api server (TELEGRAM_TEST_HOST)
+// because the official Telegram API only accepts HTTPS webhooks on public IPs.
+// A local Bot API server can deliver webhooks to http://127.0.0.1.
+//
+// Flow:
+//  1. Start a local HTTP server on a random port
+//  2. SetWebhook to http://127.0.0.1:{port}/webhook with a secret token
+//  3. Seed a message via MTProto
+//  4. Wait for the webhook to deliver the Update
+//  5. Verify: ParseWebhookPayload succeeds, secret header correct, Update fields valid
+//  6. DeleteWebhook to restore polling mode
+func TestE2E_Webhook(t *testing.T) {
+	skipIfNoToken(t)
+
+	host := os.Getenv("TELEGRAM_TEST_HOST")
+	if host == "" {
+		t.Skip("TELEGRAM_TEST_HOST not set — need local bot-api server for webhook test")
+	}
+
+	const secret = "e2e-webhook-test-secret"
+	b := testBot(WithAPIBase(host))
+	bWithSecret := NewBot(testBotToken, secret, WithAPIBase(host))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	// --- 1. Start local webhook receiver ---
+	var (
+		mu          sync.Mutex
+		received    []webhookHit
+		wrongSecret int
+	)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
+		headerSec := r.Header.Get("X-Telegram-Bot-Api-Secret-Token")
+		cm, err := bWithSecret.ParseWebhookPayload(r.Context(), r, nil)
+
+		mu.Lock()
+		defer mu.Unlock()
+
+		if err != nil {
+			wrongSecret++
+			t.Logf("webhook: rejected request (secret=%q err=%v)", headerSec, err)
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		received = append(received, webhookHit{
+			secret: headerSec,
+			cm:     cm,
+		})
+		if cm != nil {
+			t.Logf("webhook: accepted update_id=%d secret=%q", cm.UpdateID, headerSec)
+		} else {
+			t.Logf("webhook: accepted (no processable message) secret=%q", headerSec)
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	port := listener.Addr().(*net.TCPAddr).Port
+	server := &http.Server{Handler: mux}
+	go server.Serve(listener)
+	defer server.Close()
+	t.Logf("webhook server listening on 127.0.0.1:%d", port)
+
+	// --- 2. SetWebhook ---
+	webhookURL := fmt.Sprintf("http://127.0.0.1:%d/webhook", port)
+	if err := bWithSecret.SetWebhook(ctx, webhookURL, []string{"message"}); err != nil {
+		t.Fatalf("SetWebhook: %v", err)
+	}
+	t.Logf("SetWebhook -> %s", webhookURL)
+
+	defer func() {
+		cleanCtx, cleanCancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cleanCancel()
+		if err := b.DeleteWebhook(cleanCtx, true); err != nil {
+			t.Logf("warning: DeleteWebhook failed: %v", err)
+		} else {
+			t.Log("DeleteWebhook -> ok (polling restored)")
+		}
+	}()
+
+	// --- 3. Seed a message ---
+	seedBotMessages(t)
+
+	// --- 4. Wait for webhook delivery ---
+	deadline := time.After(30 * time.Second)
+	ticker := time.NewTicker(500 * time.Millisecond)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-deadline:
+			mu.Lock()
+			count := len(received)
+			mu.Unlock()
+			if count == 0 {
+				t.Fatal("timeout: no webhook updates received within 30s")
+			}
+			goto verify
+		case <-ticker.C:
+			mu.Lock()
+			count := len(received)
+			mu.Unlock()
+			if count >= 2 {
+				time.Sleep(2 * time.Second)
+				goto verify
+			}
+		}
+	}
+
+verify:
+	mu.Lock()
+	defer mu.Unlock()
+
+	if len(received) == 0 {
+		t.Fatal("no webhook updates received")
+	}
+	t.Logf("total webhook hits: %d (rejected: %d)", len(received), wrongSecret)
+
+	// --- 5. Validate received updates ---
+	for i, hit := range received {
+		t.Run(fmt.Sprintf("update_%d", i), func(t *testing.T) {
+			if hit.secret != secret {
+				t.Errorf("secret header = %q, want %q", hit.secret, secret)
+			}
+
+			cm := hit.cm
+			if cm == nil {
+				t.Log("webhook hit has no processable message (cm nil)")
+				return
+			}
+
+			if cm.UpdateID == 0 {
+				t.Error("ConvertedMessage.UpdateID should not be 0")
+			}
+			if cm.MessageID == 0 {
+				t.Error("ConvertedMessage.MessageID should not be 0")
+			}
+			if cm.ChatID == 0 {
+				t.Error("ConvertedMessage.ChatID should not be 0")
+			}
+			if cm.Date == 0 {
+				t.Error("ConvertedMessage.Date should not be 0")
+			}
+			if cm.SenderID == 0 {
+				t.Error("ConvertedMessage.SenderID should not be 0")
+			}
+			if cm.SenderName == "" {
+				t.Error("ConvertedMessage.SenderName should not be empty")
+			}
+			if !cm.HasText() && !cm.HasMedia() {
+				t.Error("message has neither text nor media")
+			}
+
+			for j, mi := range cm.MediaItems {
+				if mi.FileID == "" {
+					t.Errorf("media[%d].FileID should not be empty", j)
+				}
+				if mi.FileUniqueID == "" {
+					t.Errorf("media[%d].FileUniqueID should not be empty", j)
+				}
+				if mi.MimeType == "" {
+					t.Errorf("media[%d].MimeType should not be empty", j)
+				}
+				if mi.Type == "" {
+					t.Errorf("media[%d].Type should not be empty", j)
+				}
+			}
+
+			t.Logf("webhook update[%d] id=%d msg=%d chat=%d sender=%q text=%q media=%d",
+				i, cm.UpdateID, cm.MessageID, cm.ChatID, cm.SenderName,
+				truncate(cm.Text, 40), len(cm.MediaItems))
+		})
+	}
+
+	// --- 6. Compare with GetUpdates ---
+	// Delete webhook first, then seed + poll to verify ConvertUpdate consistency.
+	t.Run("convert_consistency", func(t *testing.T) {
+		delCtx, delCancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer delCancel()
+		if err := b.DeleteWebhook(delCtx, true); err != nil {
+			t.Fatalf("DeleteWebhook for polling: %v", err)
+		}
+		time.Sleep(time.Second)
+
+		seedBotMessages(t)
+		time.Sleep(2 * time.Second)
+
+		pollCtx, pollCancel := context.WithTimeout(context.Background(), 15*time.Second)
+		defer pollCancel()
+		polled := fetchUpdates(t, b, pollCtx)
+		if len(polled) == 0 {
+			t.Skip("no polled updates to compare")
+		}
+
+		polledCM := polled[0]
+		if polledCM == nil {
+			t.Skip("polled update has no message")
+		}
+
+		var webhookCM *ConvertedMessage
+		for _, hit := range received {
+			if hit.cm != nil {
+				webhookCM = hit.cm
+				break
+			}
+		}
+		if webhookCM == nil {
+			t.Skip("no webhook update with message")
+		}
+
+		if webhookCM.ChatID == 0 || polledCM.ChatID == 0 {
+			t.Error("both sources should have non-zero ChatID")
+		}
+		if webhookCM.SenderID == 0 || polledCM.SenderID == 0 {
+			t.Error("both sources should have non-zero SenderID")
+		}
+		if webhookCM.Date == 0 || polledCM.Date == 0 {
+			t.Error("both sources should have non-zero Date")
+		}
+		if webhookCM.ChatType != polledCM.ChatType {
+			t.Errorf("ChatType mismatch: webhook=%q polled=%q", webhookCM.ChatType, polledCM.ChatType)
+		}
+
+		webhookHasContent := webhookCM.HasText() || webhookCM.HasMedia()
+		polledHasContent := polledCM.HasText() || polledCM.HasMedia()
+		if !webhookHasContent {
+			t.Error("webhook ConvertUpdate produced no content")
+		}
+		if !polledHasContent {
+			t.Error("polled ConvertUpdate produced no content")
+		}
+
+		t.Logf("consistency OK: webhook(text=%v media=%d) polled(text=%v media=%d) chat_type=%s",
+			webhookCM.HasText(), len(webhookCM.MediaItems),
+			polledCM.HasText(), len(polledCM.MediaItems),
+			polledCM.ChatType)
+	})
+
+	// Verify ParseWebhookPayload rejects wrong secrets
+	t.Run("wrong_secret_rejected", func(t *testing.T) {
+		fakeReq, _ := http.NewRequest("POST", "/webhook", nil)
+		fakeReq.Header.Set("X-Telegram-Bot-Api-Secret-Token", "wrong-secret")
+		_, err := bWithSecret.ParseWebhookPayload(fakeReq.Context(), fakeReq, nil)
+		if err == nil {
+			t.Error("expected error for wrong secret, got nil")
+		}
+	})
+}
+
+type webhookHit struct {
+	secret string
+	cm     *ConvertedMessage
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}

openapi/integrations/integrations.go

@@ -0,0 +1,99 @@
+package integrations
+
+import (
+	"context"
+	"io"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/event"
+	"github.com/yaoapp/yao/openapi/response"
+)
+
+// WebhookPayload is the event payload pushed to "integration.webhook.{provider}".
+// Subscribers receive this and handle it according to their own protocol.
+type WebhookPayload struct {
+	Provider string            `json:"provider"`
+	AppID    string            `json:"app_id"`
+	Method   string            `json:"method"`
+	Body     []byte            `json:"body,omitempty"`
+	Headers  map[string]string `json:"headers,omitempty"`
+	Query    map[string]string `json:"query,omitempty"`
+}
+
+// Attach registers the integrations webhook endpoints.
+// These are public endpoints (no OAuth) since external platforms push here.
+func Attach(group *gin.RouterGroup) {
+	group.GET("/:provider/:app_id", webhookHandler)
+	group.POST("/:provider/:app_id", webhookHandler)
+}
+
+// webhookHandler receives webhooks from external platforms, packs the raw
+// request into a WebhookPayload, and pushes an event for async processing.
+// It returns HTTP 200 immediately — subscribers handle the rest.
+func webhookHandler(c *gin.Context) {
+	provider := c.Param("provider")
+	appID := c.Param("app_id")
+
+	if provider == "" || appID == "" {
+		response.RespondWithError(c, response.StatusBadRequest, &response.ErrorResponse{
+			Code:             response.ErrInvalidRequest.Code,
+			ErrorDescription: "provider and app_id are required",
+		})
+		return
+	}
+
+	payload := WebhookPayload{
+		Provider: provider,
+		AppID:    appID,
+		Method:   c.Request.Method,
+	}
+
+	// Read body for POST/PUT/PATCH
+	if c.Request.Body != nil && c.Request.Method != http.MethodGet {
+		body, err := io.ReadAll(c.Request.Body)
+		if err != nil {
+			log.Error("integrations webhook: read body failed provider=%s app_id=%s: %v", provider, appID, err)
+			c.Status(http.StatusOK)
+			return
+		}
+		payload.Body = body
+	}
+
+	payload.Headers = flattenHeaders(c.Request.Header)
+	payload.Query = flattenQuery(c.Request.URL.Query())
+
+	c.Status(http.StatusOK)
+
+	eventType := "integration.webhook." + provider
+	if _, err := event.Push(context.Background(), eventType, payload); err != nil {
+		log.Error("integrations webhook: event.Push failed type=%s app_id=%s: %v", eventType, appID, err)
+	}
+}
+
+func flattenHeaders(h http.Header) map[string]string {
+	if len(h) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(h))
+	for k, v := range h {
+		if len(v) > 0 {
+			out[k] = v[0]
+		}
+	}
+	return out
+}
+
+func flattenQuery(q map[string][]string) map[string]string {
+	if len(q) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(q))
+	for k, v := range q {
+		if len(v) > 0 {
+			out[k] = v[0]
+		}
+	}
+	return out
+}

openapi/openapi.go

@@ -13,6 +13,7 @@ import (
 	"github.com/yaoapp/yao/openapi/dsl"
 	"github.com/yaoapp/yao/openapi/file"
 	"github.com/yaoapp/yao/openapi/hello"
+	openintegrations "github.com/yaoapp/yao/openapi/integrations"
 	"github.com/yaoapp/yao/openapi/job"
 	"github.com/yaoapp/yao/openapi/kb"
 	"github.com/yaoapp/yao/openapi/llm"
@@ -149,6 +150,9 @@ func (openapi *OpenAPI) Attach(router *gin.Engine) {
 	// Messenger webhook handlers
 	messenger.Attach(group.Group("/messenger"), openapi.OAuth)
 
+	// Integrations webhook handlers (public, no OAuth - external platforms push here)
+	openintegrations.Attach(group.Group("/integrations"))
+
 	// Agent handlers
 	agent.Attach(group.Group("/agent"), openapi.OAuth)
 

openapi/tests/integrations_webhook_test.go

@@ -0,0 +1,361 @@
+package openapi_test
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	jsoniter "github.com/json-iterator/go"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	"github.com/yaoapp/yao/openapi"
+	integrations "github.com/yaoapp/yao/openapi/integrations"
+	"github.com/yaoapp/yao/openapi/tests/testutils"
+)
+
+// integrationHandler is a minimal handler to accept "integration.*" events during tests.
+type integrationHandler struct{}
+
+func (h *integrationHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	if ev.IsCall {
+		resp <- eventtypes.Result{Data: ev.Payload}
+	}
+}
+
+func (h *integrationHandler) Shutdown(ctx context.Context) error { return nil }
+
+func init() {
+	event.Register("integration", &integrationHandler{})
+}
+
+func TestWebhookPost_Telegram(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	// Subscribe to integration.webhook.telegram events
+	ch := make(chan *eventtypes.Event, 16)
+	subID := event.Subscribe("integration.webhook.telegram", ch)
+	defer event.Unsubscribe(subID)
+
+	// Simulate a Telegram webhook POST
+	telegramBody := `{"update_id":123456,"message":{"message_id":1,"from":{"id":999,"first_name":"Test"},"chat":{"id":999,"type":"private"},"text":"hello bot"}}`
+	url := fmt.Sprintf("%s%s/integrations/telegram/app-abc123", serverURL, baseURL)
+
+	req, err := http.NewRequest(http.MethodPost, url, bytes.NewBufferString(telegramBody))
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Telegram-Bot-Api-Secret-Token", "test-secret-token")
+
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	// Wait for the event to arrive
+	select {
+	case ev := <-ch:
+		assert.Equal(t, "integration.webhook.telegram", ev.Type)
+
+		var payload integrations.WebhookPayload
+		err := ev.Should(&payload)
+		require.NoError(t, err)
+
+		assert.Equal(t, "telegram", payload.Provider)
+		assert.Equal(t, "app-abc123", payload.AppID)
+		assert.Equal(t, http.MethodPost, payload.Method)
+
+		// Verify body is passed through
+		assert.JSONEq(t, telegramBody, string(payload.Body))
+
+		// Verify headers are forwarded
+		assert.Equal(t, "application/json", payload.Headers["Content-Type"])
+		assert.Equal(t, "test-secret-token", payload.Headers["X-Telegram-Bot-Api-Secret-Token"])
+
+		t.Logf("Received event: type=%s provider=%s app_id=%s body_len=%d headers=%v",
+			ev.Type, payload.Provider, payload.AppID, len(payload.Body), payload.Headers)
+
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for integration.webhook.telegram event")
+	}
+}
+
+func TestWebhookGet_Verification(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	ch := make(chan *eventtypes.Event, 16)
+	subID := event.Subscribe("integration.webhook.telegram", ch)
+	defer event.Unsubscribe(subID)
+
+	// Simulate a Telegram setWebhook verification GET with query parameters
+	url := fmt.Sprintf("%s%s/integrations/telegram/app-xyz789?hub.mode=subscribe&hub.verify_token=abc", serverURL, baseURL)
+
+	resp, err := http.Get(url)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	select {
+	case ev := <-ch:
+		var payload integrations.WebhookPayload
+		err := ev.Should(&payload)
+		require.NoError(t, err)
+
+		assert.Equal(t, "telegram", payload.Provider)
+		assert.Equal(t, "app-xyz789", payload.AppID)
+		assert.Equal(t, http.MethodGet, payload.Method)
+		assert.Empty(t, payload.Body, "GET request should have no body")
+		assert.Equal(t, "subscribe", payload.Query["hub.mode"])
+		assert.Equal(t, "abc", payload.Query["hub.verify_token"])
+
+		t.Logf("Received GET event: provider=%s app_id=%s query=%v", payload.Provider, payload.AppID, payload.Query)
+
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for integration.webhook.telegram event")
+	}
+}
+
+func TestWebhookPost_Stripe(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	ch := make(chan *eventtypes.Event, 16)
+	subID := event.Subscribe("integration.webhook.stripe", ch)
+	defer event.Unsubscribe(subID)
+
+	stripeBody := `{"id":"evt_1234","type":"checkout.session.completed","data":{"object":{"amount_total":1000}}}`
+	url := fmt.Sprintf("%s%s/integrations/stripe/whsec-test123", serverURL, baseURL)
+
+	req, err := http.NewRequest(http.MethodPost, url, bytes.NewBufferString(stripeBody))
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Stripe-Signature", "t=123,v1=abc")
+
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	select {
+	case ev := <-ch:
+		assert.Equal(t, "integration.webhook.stripe", ev.Type)
+
+		var payload integrations.WebhookPayload
+		err := ev.Should(&payload)
+		require.NoError(t, err)
+
+		assert.Equal(t, "stripe", payload.Provider)
+		assert.Equal(t, "whsec-test123", payload.AppID)
+		assert.JSONEq(t, stripeBody, string(payload.Body))
+		assert.Equal(t, "t=123,v1=abc", payload.Headers["Stripe-Signature"])
+
+		t.Logf("Received Stripe event: provider=%s app_id=%s", payload.Provider, payload.AppID)
+
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for integration.webhook.stripe event")
+	}
+}
+
+func TestWebhookMissingParams(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	// The route pattern requires both :provider and :app_id in the path.
+	// Missing parameters would result in 404 from the Gin router, not 400.
+	// Test with the actual endpoint to verify it's registered and working.
+	url := fmt.Sprintf("%s%s/integrations/telegram/test-app", serverURL, baseURL)
+	resp, err := http.Post(url, "application/json", bytes.NewBufferString("{}"))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+}
+
+func TestWebhookEmptyBody(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	ch := make(chan *eventtypes.Event, 16)
+	subID := event.Subscribe("integration.webhook.wechat", ch)
+	defer event.Unsubscribe(subID)
+
+	url := fmt.Sprintf("%s%s/integrations/wechat/app-wechat-001", serverURL, baseURL)
+	resp, err := http.Post(url, "application/json", nil)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	select {
+	case ev := <-ch:
+		var payload integrations.WebhookPayload
+		err := ev.Should(&payload)
+		require.NoError(t, err)
+
+		assert.Equal(t, "wechat", payload.Provider)
+		assert.Equal(t, "app-wechat-001", payload.AppID)
+		assert.Empty(t, payload.Body)
+
+		t.Logf("Received empty-body event: provider=%s app_id=%s", payload.Provider, payload.AppID)
+
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for integration.webhook.wechat event")
+	}
+}
+
+func TestWebhookLargeBody(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	ch := make(chan *eventtypes.Event, 16)
+	subID := event.Subscribe("integration.webhook.generic", ch)
+	defer event.Unsubscribe(subID)
+
+	// Build a large payload (~100KB)
+	largeData := map[string]interface{}{
+		"items": make([]map[string]string, 1000),
+	}
+	for i := 0; i < 1000; i++ {
+		largeData["items"].([]map[string]string)[i] = map[string]string{
+			"key":   fmt.Sprintf("item-%d", i),
+			"value": "a]b]c]d]e]f]g]h]i]j]k]l]m]n]o]p]q]r]s]t]u]v]w]x]y]z",
+		}
+	}
+	bodyBytes, err := jsoniter.Marshal(largeData)
+	require.NoError(t, err)
+
+	url := fmt.Sprintf("%s%s/integrations/generic/app-large", serverURL, baseURL)
+	resp, err := http.Post(url, "application/json", bytes.NewBuffer(bodyBytes))
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	select {
+	case ev := <-ch:
+		var payload integrations.WebhookPayload
+		err := ev.Should(&payload)
+		require.NoError(t, err)
+
+		assert.Equal(t, "generic", payload.Provider)
+		assert.Equal(t, len(bodyBytes), len(payload.Body))
+
+		t.Logf("Received large-body event: provider=%s body_size=%d bytes", payload.Provider, len(payload.Body))
+
+	case <-time.After(5 * time.Second):
+		t.Fatal("Timed out waiting for large body event")
+	}
+}
+
+func TestWebhookResponseImmediate(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	url := fmt.Sprintf("%s%s/integrations/telegram/app-timing", serverURL, baseURL)
+
+	start := time.Now()
+	resp, err := http.Post(url, "application/json", bytes.NewBufferString(`{"test":"timing"}`))
+	elapsed := time.Since(start)
+
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	// Response body should be empty (just status 200)
+	body, _ := io.ReadAll(resp.Body)
+	assert.Empty(t, body)
+
+	// Response should be near-instant (< 1 second); the event is pushed async
+	assert.Less(t, elapsed, 1*time.Second, "Webhook response should be immediate, got %v", elapsed)
+
+	t.Logf("Webhook response time: %v", elapsed)
+}
+
+func TestWebhookMultipleProviders(t *testing.T) {
+	serverURL := testutils.Prepare(t)
+	defer testutils.Clean()
+
+	baseURL := ""
+	if openapi.Server != nil && openapi.Server.Config != nil {
+		baseURL = openapi.Server.Config.BaseURL
+	}
+
+	// Subscribe to all integration.webhook.* events
+	ch := make(chan *eventtypes.Event, 32)
+	subID := event.Subscribe("integration.webhook.*", ch)
+	defer event.Unsubscribe(subID)
+
+	providers := []string{"telegram", "stripe", "wechat", "dingtalk", "feishu"}
+	for _, provider := range providers {
+		url := fmt.Sprintf("%s%s/integrations/%s/app-%s-001", serverURL, baseURL, provider, provider)
+		body := fmt.Sprintf(`{"provider":"%s","test":true}`, provider)
+		resp, err := http.Post(url, "application/json", bytes.NewBufferString(body))
+		require.NoError(t, err)
+		resp.Body.Close()
+		assert.Equal(t, http.StatusOK, resp.StatusCode)
+	}
+
+	received := make(map[string]bool)
+	timeout := time.After(5 * time.Second)
+	for len(received) < len(providers) {
+		select {
+		case ev := <-ch:
+			var payload integrations.WebhookPayload
+			err := ev.Should(&payload)
+			require.NoError(t, err)
+			received[payload.Provider] = true
+			t.Logf("Received event for provider: %s", payload.Provider)
+		case <-timeout:
+			t.Fatalf("Timed out: received %d/%d provider events: %v", len(received), len(providers), received)
+		}
+	}
+
+	for _, provider := range providers {
+		assert.True(t, received[provider], "Should have received event for provider: %s", provider)
+	}
+}