openclaw-seatalk 0.2.0 → 0.3.0

package/README.md

@@ -26,8 +26,9 @@ OpenClaw channel plugin for [SeaTalk](https://seatalk.io/) messaging.
 - **Dual gateway mode** — **webhook** (direct HTTP server) or **relay** (WebSocket client via [seatalk-relay](https://github.com/lf4096/seatalk-relay))
 - **Security** — SHA256 signature verification for all incoming events
 - **Token management** — automatic access token obtain, cache, and refresh
+- **Outbound coalescing** — consecutive reply payloads are merged into a single message with automatic markdown-aware chunking at 4000 chars; configurable via `outboundCoalescing`
 - **Deduplication** — event ID dedup + per-sender debounce buffer (thread-aware)
-- **Access control** — DM policy (`open`/`allowlist`), group policy (`disabled`/`allowlist`/`open`), per-group and per-sender allow-lists
+- **Access control** — DM policy (`open`/`allowlist`/`pairing`), group policy (`disabled`/`allowlist`/`open`), per-group and per-sender allow-lists
 - **Email resolution** — email-to-employee_code lookup for outbound message targets
 - **Multi-account** — multiple SeaTalk bot apps in one OpenClaw instance
 - **Health probing** — connection health check on startup
@@ -87,14 +88,11 @@ openclaw plugins install -l .
 
 ## Upgrading
 
-Regular upgrade:
-
 ```bash
-openclaw update
+openclaw plugins update openclaw-seatalk
+openclaw gateway restart
 ```
 
-`openclaw update` automatically upgrades both OpenClaw and installed plugins.
-
 Upgrading OpenClaw across the 2026.3.22 SDK boundary (e.g. 2026.3.13 -> 2026.3.22):
 
 ```bash
@@ -152,8 +150,8 @@ Or edit the OpenClaw config file directly (`~/.openclaw/openclaw.json`).
       signingSecret: "your_signing_secret",
       webhookPort: 3210,
       webhookPath: "/callback",
-      dmPolicy: "open",  // or "allowlist"
-      // allowFrom: ["12345678", "alice@company.com"],
+      dmPolicy: "open",  // or "allowlist" | "pairing"
+      // allowFrom: ["e_12345678", "alice@company.com"],
     },
   },
 }
@@ -200,12 +198,14 @@ Or edit the OpenClaw config file directly (`~/.openclaw/openclaw.json`).
 | `webhookPort` | number | `8080` | HTTP port (webhook mode only) |
 | `webhookPath` | string | `"/callback"` | HTTP path (webhook mode only) |
 | `relayUrl` | string | — | WebSocket URL (relay mode only) |
-| `dmPolicy` | `"open"` \| `"allowlist"` | `"allowlist"` | Who can DM the bot |
+| `dmPolicy` | `"open"` \| `"allowlist"` \| `"pairing"` | `"allowlist"` | Who can DM the bot (`pairing`: approve via CLI) |
 | `allowFrom` | string[] | — | Allowed DM senders (employee codes or emails) |
 | `groupPolicy` | `"disabled"` \| `"allowlist"` \| `"open"` | `"disabled"` | Group chat policy |
 | `groupAllowFrom` | string[] | — | Allowed group IDs (when `groupPolicy: "allowlist"`) |
 | `groupSenderAllowFrom` | string[] | — | Allowed senders within groups (employee codes or emails) |
+| `outboundCoalescing` | boolean | `true` | Merge consecutive reply payloads into a single message (4000-char chunking) |
 | `processingIndicator` | `"typing"` \| `"off"` | `"typing"` | Show typing status while processing |
+| `mediaAllowHosts` | string[] | `["openapi.seatalk.io"]` | Allowed hostnames for inbound media downloads (HTTPS only) |
 | `tools.groupInfo` | boolean | `true` | Enable `seatalk` tool `group_info` action |
 | `tools.groupHistory` | boolean | `true` | Enable `seatalk` tool `group_history` action |
 | `tools.groupList` | boolean | `true` | Enable `seatalk` tool `group_list` action |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "openclaw-seatalk",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "OpenClaw SeaTalk channel plugin",
 	"type": "module",
 	"license": "Apache-2.0",
@@ -46,7 +46,6 @@
 	},
 	"openclaw": {
 		"extensions": ["./index.ts"],
-		"setupEntry": "./setup-entry.ts",
 		"channel": {
 			"id": "seatalk",
 			"label": "SeaTalk",
@@ -58,6 +57,9 @@
 		"install": {
 			"npmSpec": "openclaw-seatalk",
 			"defaultChoice": "npm"
+		},
+		"compat": {
+			"pluginApi": ">=2026.3.22"
 		}
 	}
 }

package/src/access.ts

@@ -0,0 +1,46 @@
+export function checkGroupAccess(params: {
+	groupPolicy: string;
+	groupAllowFrom?: string[];
+	groupSenderAllowFrom?: string[];
+	groupId: string;
+	senderEmployeeCode: string;
+	senderEmail?: string;
+}): { allowed: boolean; reason?: string } {
+	const {
+		groupPolicy,
+		groupAllowFrom,
+		groupSenderAllowFrom,
+		groupId,
+		senderEmployeeCode,
+		senderEmail,
+	} = params;
+
+	if (groupPolicy === "disabled") {
+		return { allowed: false, reason: "groupPolicy is disabled" };
+	}
+
+	if (groupPolicy === "allowlist") {
+		const list = groupAllowFrom ?? [];
+		if (!list.includes(groupId)) {
+			return { allowed: false, reason: `group ${groupId} not in groupAllowFrom` };
+		}
+	}
+
+	if (groupSenderAllowFrom && groupSenderAllowFrom.length > 0) {
+		const match = groupSenderAllowFrom.some((entry) => {
+			const e = entry.trim();
+			if (e === "*") return true;
+			if (e === senderEmployeeCode) return true;
+			if (senderEmail && e.toLowerCase() === senderEmail.toLowerCase()) return true;
+			return false;
+		});
+		if (!match) {
+			return {
+				allowed: false,
+				reason: `sender ${senderEmployeeCode} not in groupSenderAllowFrom`,
+			};
+		}
+	}
+
+	return { allowed: true };
+}

package/src/bot.ts

@@ -1,13 +1,23 @@
 import type { OpenClawConfig, RuntimeEnv } from "openclaw/plugin-sdk";
+import { createChannelPairingController } from "openclaw/plugin-sdk/channel-pairing";
 import {
-	resolveSendableOutboundReplyParts,
-	sendMediaWithLeadingCaption,
-} from "openclaw/plugin-sdk/reply-payload";
+	DM_GROUP_ACCESS_REASON,
+	resolveDmGroupAccessWithLists,
+} from "openclaw/plugin-sdk/channel-policy";
+import { resolveSendableOutboundReplyParts } from "openclaw/plugin-sdk/reply-payload";
+import { checkGroupAccess } from "./access.js";
 import { resolveSeaTalkAccount } from "./accounts.js";
 import type { SeaTalkClient } from "./client.js";
+import {
+	type MessageResolveContext,
+	deliverMediaReplies,
+	resolveForwardedMessages,
+	resolveQuotedMessage,
+} from "./inbound-resolve.js";
 import { buildSeaTalkMediaPayload, resolveInboundMedia } from "./media.js";
+import { createOutboundCoalescer } from "./outbound-coalescer.js";
 import { getSeatalkRuntime } from "./runtime.js";
-import { sendGroupTextMessage, sendMediaToTarget, sendTextMessage } from "./send.js";
+import { sendGroupTextMessage, sendTextMessage } from "./send.js";
 import type {
 	SeaTalkCallbackRequest,
 	SeaTalkGroupMessageEvent,
@@ -16,6 +26,20 @@ import type {
 	SeaTalkMessageEvent,
 } from "./types.js";
 
+function isSeaTalkSenderAllowed(
+	employeeCode: string,
+	email: string | undefined,
+	allowFrom: string[],
+): boolean {
+	return allowFrom.some((entry) => {
+		const e = entry.trim();
+		if (e === "*") return true;
+		if (e === employeeCode) return true;
+		if (email && e.toLowerCase() === email.toLowerCase()) return true;
+		return false;
+	});
+}
+
 export function dispatchSeaTalkEvent(params: {
 	cfg: OpenClawConfig;
 	event: SeaTalkCallbackRequest;
@@ -87,6 +111,9 @@ function tryRecordEvent(eventId: string): boolean {
 const DEBOUNCE_SLIDE_MS = 1500;
 const DEBOUNCE_HARD_CAP_MS = 5000;
 
+const SEATALK_TEXT_CHUNK_LIMIT = 4000;
+const OUTBOUND_COALESCE_IDLE_MS = 1000;
+
 type DmBufferEntry = {
 	kind: "dm";
 	event: SeaTalkCallbackRequest;
@@ -191,76 +218,6 @@ function pushToBuffer(key: string, entry: BufferEntry, context: DebounceContext)
 	scheduleFlush(key, state);
 }
 
-async function resolveQuotedMessage(params: {
-	client: SeaTalkClient;
-	quotedMessageId: string;
-	log: (msg: string) => void;
-}): Promise<{ text: string; media: SeaTalkMediaInfo[] } | null> {
-	const { client, quotedMessageId, log } = params;
-	try {
-		const data = await client.getMessageByMessageId(quotedMessageId);
-		const sender =
-			(data.sender as { employee_code?: string } | undefined)?.employee_code ?? "unknown";
-		const tag = data.tag as string | undefined;
-
-		const media: SeaTalkMediaInfo[] = [];
-		let content = "";
-
-		if (tag === "text") {
-			const textObj = data.text as { plain_text?: string; content?: string } | undefined;
-			content = textObj?.plain_text ?? textObj?.content ?? "";
-		} else if (tag === "image" || tag === "file" || tag === "video") {
-			const fakeMsg: SeaTalkMessage = {
-				message_id: quotedMessageId,
-				tag,
-				image:
-					tag === "image" ? (data.image as { content: string } | undefined) : undefined,
-				file:
-					tag === "file"
-						? (data.file as { content: string; filename: string } | undefined)
-						: undefined,
-				video:
-					tag === "video" ? (data.video as { content: string } | undefined) : undefined,
-			};
-			const resolved = await resolveInboundMedia({ message: fakeMsg, client, log });
-			if (resolved) {
-				media.push(resolved);
-				content = resolved.placeholder;
-			} else {
-				content = `<media:${tag}>`;
-			}
-		} else {
-			content = `<unsupported:${tag ?? "unknown"}>`;
-		}
-
-		return { text: `[Quoted from ${sender}: ${content}]`, media };
-	} catch (err) {
-		log(`seatalk: failed to resolve quoted message ${quotedMessageId}: ${String(err)}`);
-		return null;
-	}
-}
-
-async function deliverMediaReplies(params: {
-	mediaUrls: string[];
-	client: SeaTalkClient;
-	to: string;
-	threadId?: string;
-	isGroup: boolean;
-	log: (msg: string) => void;
-}): Promise<void> {
-	const { mediaUrls, client, to, threadId, isGroup, log } = params;
-	await sendMediaWithLeadingCaption({
-		mediaUrls,
-		caption: "",
-		send: async ({ mediaUrl }) => {
-			await sendMediaToTarget({ client, to, mediaUrl, threadId, isGroup });
-		},
-		onError: async ({ error, mediaUrl }) => {
-			log(`seatalk: failed to send media ${mediaUrl}: ${String(error)}`);
-		},
-	});
-}
-
 async function processBufferedDmEvents(
 	entries: DmBufferEntry[],
 	context: DebounceContext,
@@ -273,8 +230,64 @@ async function processBufferedDmEvents(
 	const employeeCode = first.employee_code;
 	const email = first.email;
 
+	const account = resolveSeaTalkAccount({ cfg, accountId });
+	const seatalkCfg = account.config;
+
+	const core = getSeatalkRuntime();
+	const dmPolicy = seatalkCfg?.dmPolicy ?? "allowlist";
+	const configAllowFrom = (seatalkCfg?.allowFrom ?? []).map((v) => String(v));
+
+	const pairing = createChannelPairingController({ core, channel: "seatalk", accountId });
+	const storeAllowFrom =
+		dmPolicy === "pairing" ? await pairing.readAllowFromStore().catch(() => []) : [];
+
+	const accessDecision = resolveDmGroupAccessWithLists({
+		isGroup: false,
+		dmPolicy,
+		groupPolicy: "disabled",
+		allowFrom: configAllowFrom,
+		groupAllowFrom: [],
+		storeAllowFrom,
+		isSenderAllowed: (list) => isSeaTalkSenderAllowed(employeeCode, email, list),
+	});
+
+	if (accessDecision.decision === "pairing") {
+		const result = await pairing.issueChallenge({
+			senderId: employeeCode,
+			senderIdLine: `Your SeaTalk employee code: ${employeeCode}`,
+			meta: email ? { email } : undefined,
+			onCreated: ({ code }) => {
+				log(`seatalk[${accountId}]: pairing request sender=${employeeCode} code=${code}`);
+			},
+			sendPairingReply: async (text) => {
+				await sendTextMessage(client, employeeCode, text, 1, first.message.thread_id);
+			},
+			onReplyError: (err) => {
+				log(
+					`seatalk[${accountId}]: pairing reply failed for ${employeeCode}: ${String(err)}`,
+				);
+			},
+		});
+		if (!result.created) {
+			log(`seatalk[${accountId}]: pairing already pending for ${employeeCode}`);
+		}
+		return;
+	}
+
+	if (accessDecision.decision !== "allow") {
+		if (accessDecision.reasonCode === DM_GROUP_ACCESS_REASON.DM_POLICY_DISABLED) {
+			log(`seatalk[${accountId}]: blocked DM from ${employeeCode} (dmPolicy=disabled)`);
+		} else {
+			log(`seatalk[${accountId}]: sender ${employeeCode} not in allowlist, dropping`);
+		}
+		return;
+	}
+
+	const mediaAllowHosts = seatalkCfg?.mediaAllowHosts;
+	const resolveCtx: MessageResolveContext = { client, mediaAllowHosts, log };
+
 	const textParts: string[] = [];
-	const mediaMessages: SeaTalkMessage[] = [];
+	const mediaList: SeaTalkMediaInfo[] = [];
 
 	for (const { parsedEvent } of entries) {
 		const msg = parsedEvent.message;
@@ -285,52 +298,44 @@ async function processBufferedDmEvents(
 				break;
 			case "image":
 			case "file":
-			case "video":
-				mediaMessages.push(msg);
+			case "video": {
+				const media = await resolveInboundMedia({
+					message: msg,
+					client,
+					mediaAllowHosts,
+					log,
+				});
+				if (media) mediaList.push(media);
 				break;
-			case "combined_forwarded_chat_history":
-				log(`seatalk[${accountId}]: skipping combined_forwarded_chat_history`);
+			}
+			case "combined_forwarded_chat_history": {
+				const fwd = msg.combined_forwarded_chat_history?.content;
+				if (fwd) {
+					const result = await resolveForwardedMessages(fwd, resolveCtx);
+					mediaList.push(...result.media);
+					textParts.push(
+						result.lines.length > 0
+							? `[Forwarded messages]\n${result.lines.join("\n")}`
+							: "[Forwarded messages]",
+					);
+				}
 				break;
+			}
 		}
 	}
 
-	const account = resolveSeaTalkAccount({ cfg, accountId });
-	const seatalkCfg = account.config;
-
-	const dmPolicy = seatalkCfg?.dmPolicy ?? "allowlist";
-	const allowFrom = seatalkCfg?.allowFrom ?? [];
-
-	if (dmPolicy === "allowlist") {
-		const allowed =
-			allowFrom.length === 0
-				? false
-				: allowFrom.some((entry) => {
-						const e = entry.trim();
-						if (e === "*") return true;
-						if (e === employeeCode) return true;
-						if (email && e.toLowerCase() === email.toLowerCase()) return true;
-						return false;
-					});
-
-		if (!allowed) {
-			log(`seatalk[${accountId}]: sender ${employeeCode} not in allowlist, dropping`);
-			return;
-		}
-	}
-
-	const mediaList: SeaTalkMediaInfo[] = [];
-	for (const msg of mediaMessages) {
-		const media = await resolveInboundMedia({ message: msg, client, log });
-		if (media) mediaList.push(media);
-	}
-
 	const seenQuotedIds = new Set<string>();
 	const quotedTexts: string[] = [];
 	for (const { parsedEvent } of entries) {
 		const qid = parsedEvent.message.quoted_message_id;
 		if (!qid || seenQuotedIds.has(qid)) continue;
 		seenQuotedIds.add(qid);
-		const quoted = await resolveQuotedMessage({ client, quotedMessageId: qid, log });
+		const quoted = await resolveQuotedMessage({
+			client,
+			quotedMessageId: qid,
+			mediaAllowHosts,
+			log,
+		});
 		if (quoted) {
 			quotedTexts.push(quoted.text);
 			mediaList.push(...quoted.media);
@@ -358,8 +363,6 @@ async function processBufferedDmEvents(
 	const threadId = first.message.thread_id;
 
 	try {
-		const core = getSeatalkRuntime();
-
 		const seatalkFrom = `seatalk:${employeeCode}`;
 		const seatalkTo = employeeCode;
 
@@ -379,13 +382,16 @@ async function processBufferedDmEvents(
 			contextKey: `seatalk:message:${employeeCode}:${messageId}`,
 		});
 
+		const eventTimestamp = entries[0].event.timestamp;
+		const messageTimestamp = eventTimestamp ? new Date(eventTimestamp * 1000) : new Date();
+
 		const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
 		const bodyForAgent = `${senderName}: ${messageText}`;
 
 		const body = core.channel.reply.formatAgentEnvelope({
 			channel: "SeaTalk",
 			from: employeeCode,
-			timestamp: new Date(),
+			timestamp: messageTimestamp,
 			envelope: envelopeOptions,
 			body: bodyForAgent,
 		});
@@ -411,7 +417,7 @@ async function processBufferedDmEvents(
 			Surface: "seatalk" as const,
 			MessageSid: messageId,
 			MessageThreadId: threadId || undefined,
-			Timestamp: Date.now(),
+			Timestamp: eventTimestamp ? eventTimestamp * 1000 : Date.now(),
 			WasMentioned: false,
 			CommandAuthorized: true,
 			OriginatingChannel: "seatalk" as const,
@@ -427,6 +433,21 @@ async function processBufferedDmEvents(
 				.catch((err) => log(`seatalk[${accountId}]: typing failed: ${String(err)}`));
 		}
 
+		const coalescingEnabled = seatalkCfg?.outboundCoalescing !== false;
+		const sendDmText = (text: string) =>
+			sendTextMessage(client, employeeCode, text, 1, threadId);
+		const chunkText = (text: string, limit: number) =>
+			core.channel.text.chunkMarkdownText(text, limit);
+		const coalescer = coalescingEnabled
+			? createOutboundCoalescer({
+					send: sendDmText,
+					chunkText,
+					maxLength: SEATALK_TEXT_CHUNK_LIMIT,
+					joiner: "\n\n",
+					idleFlushMs: OUTBOUND_COALESCE_IDLE_MS,
+				})
+			: null;
+
 		const typingResult = core.channel.reply.createReplyDispatcherWithTyping({
 			humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
 			deliver: async (payload) => {
@@ -437,10 +458,18 @@ async function processBufferedDmEvents(
 					log(
 						`seatalk[${accountId}]: inline deliver DM to ${employeeCode} threadId=${threadId || "none"}`,
 					);
-					await sendTextMessage(client, employeeCode, reply.trimmedText, 1, threadId);
+					if (coalescer) {
+						coalescer.append(reply.trimmedText);
+					} else {
+						const chunks = chunkText(reply.trimmedText, SEATALK_TEXT_CHUNK_LIMIT);
+						for (const chunk of chunks) {
+							await sendDmText(chunk);
+						}
+					}
 				}
 
 				if (reply.hasMedia) {
+					if (coalescer) await coalescer.flush();
 					await deliverMediaReplies({
 						mediaUrls: reply.mediaUrls,
 						client,
@@ -476,6 +505,10 @@ async function processBufferedDmEvents(
 			);
 		} finally {
 			typingResult.markDispatchIdle();
+			if (coalescer) {
+				await typingResult.dispatcher.waitForIdle();
+				await coalescer.flush();
+			}
 		}
 	} catch (err) {
 		error(`seatalk[${accountId}]: failed to dispatch message: ${String(err)}`);
@@ -506,7 +539,6 @@ export async function handleSeaTalkMessage(params: {
 	log(
 		`seatalk[${accountId}]: received ${msgEvent.message.tag} from ${msgEvent.employee_code} (threadId=${msgEvent.message.thread_id || "none"})`,
 	);
-
 	const key = dmDebounceKey(accountId, msgEvent.employee_code, msgEvent.message.thread_id);
 	pushToBuffer(
 		key,
@@ -515,53 +547,6 @@ export async function handleSeaTalkMessage(params: {
 	);
 }
 
-function checkGroupAccess(params: {
-	groupPolicy: string;
-	groupAllowFrom?: string[];
-	groupSenderAllowFrom?: string[];
-	groupId: string;
-	senderEmployeeCode: string;
-	senderEmail?: string;
-}): { allowed: boolean; reason?: string } {
-	const {
-		groupPolicy,
-		groupAllowFrom,
-		groupSenderAllowFrom,
-		groupId,
-		senderEmployeeCode,
-		senderEmail,
-	} = params;
-
-	if (groupPolicy === "disabled") {
-		return { allowed: false, reason: "groupPolicy is disabled" };
-	}
-
-	if (groupPolicy === "allowlist") {
-		const list = groupAllowFrom ?? [];
-		if (!list.includes(groupId)) {
-			return { allowed: false, reason: `group ${groupId} not in groupAllowFrom` };
-		}
-	}
-
-	if (groupSenderAllowFrom && groupSenderAllowFrom.length > 0) {
-		const match = groupSenderAllowFrom.some((entry) => {
-			const e = entry.trim();
-			if (e === "*") return true;
-			if (e === senderEmployeeCode) return true;
-			if (senderEmail && e.toLowerCase() === senderEmail.toLowerCase()) return true;
-			return false;
-		});
-		if (!match) {
-			return {
-				allowed: false,
-				reason: `sender ${senderEmployeeCode} not in groupSenderAllowFrom`,
-			};
-		}
-	}
-
-	return { allowed: true };
-}
-
 export async function handleSeaTalkGroupMessage(params: {
 	cfg: OpenClawConfig;
 	event: SeaTalkCallbackRequest;
@@ -641,8 +626,13 @@ async function processBufferedGroupEvents(
 	const senderEmail = sender.email;
 	const threadId = msg.thread_id;
 
+	const account = resolveSeaTalkAccount({ cfg, accountId });
+	const seatalkCfg = account.config;
+	const mediaAllowHosts = seatalkCfg?.mediaAllowHosts;
+	const resolveCtx: MessageResolveContext = { client, mediaAllowHosts, log };
+
 	const textParts: string[] = [];
-	const mediaMessages: SeaTalkMessage[] = [];
+	const mediaList: SeaTalkMediaInfo[] = [];
 
 	for (const { groupEvent } of entries) {
 		const m = groupEvent.message;
@@ -653,27 +643,41 @@ async function processBufferedGroupEvents(
 				break;
 			case "image":
 			case "file":
-			case "video":
-				mediaMessages.push(m);
+			case "video": {
+				const media = await resolveInboundMedia({
+					message: m,
+					client,
+					mediaAllowHosts,
+					log,
+				});
+				if (media) mediaList.push(media);
 				break;
-			case "combined_forwarded_chat_history":
-				log(
-					`seatalk[${accountId}]: skipping combined_forwarded_chat_history in group ${groupId}`,
-				);
+			}
+			case "combined_forwarded_chat_history": {
+				const fwd = m.combined_forwarded_chat_history?.content;
+				if (fwd) {
+					const result = await resolveForwardedMessages(fwd, resolveCtx);
+					mediaList.push(...result.media);
+					textParts.push(
+						result.lines.length > 0
+							? `[Forwarded messages]\n${result.lines.join("\n")}`
+							: "[Forwarded messages]",
+					);
+				}
 				break;
+			}
 		}
 	}
 
-	const mediaList: SeaTalkMediaInfo[] = [];
-	for (const m of mediaMessages) {
-		const media = await resolveInboundMedia({ message: m, client, log });
-		if (media) mediaList.push(media);
-	}
-
 	const quotedMessageId = first.groupEvent.message.quoted_message_id;
 	let quotedText: string | null = null;
 	if (quotedMessageId) {
-		const quoted = await resolveQuotedMessage({ client, quotedMessageId, log });
+		const quoted = await resolveQuotedMessage({
+			client,
+			quotedMessageId,
+			mediaAllowHosts,
+			log,
+		});
 		if (quoted) {
 			quotedText = quoted.text;
 			mediaList.push(...quoted.media);
@@ -721,18 +725,18 @@ async function processBufferedGroupEvents(
 			{ sessionKey: route.sessionKey, contextKey: `seatalk:group:${groupId}:${messageId}` },
 		);
 
+		const sentAt = first.groupEvent.message.message_sent_time;
+		const messageTimestamp = sentAt ? new Date(sentAt * 1000) : new Date();
+
 		const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
 		const body = core.channel.reply.formatAgentEnvelope({
 			channel: "SeaTalk",
 			from: employeeCode,
-			timestamp: new Date(),
+			timestamp: messageTimestamp,
 			envelope: envelopeOptions,
 			body: `${senderName}: ${messageText}`,
 		});
 
-		const account = resolveSeaTalkAccount({ cfg, accountId });
-		const seatalkCfg = account.config;
-
 		const metadata: Record<string, string> = { groupId };
 		if (threadId) metadata.threadId = threadId;
 		if (quotedMessageId) metadata.quotedMessageId = quotedMessageId;
@@ -753,7 +757,7 @@ async function processBufferedGroupEvents(
 			Surface: "seatalk" as const,
 			MessageSid: messageId,
 			MessageThreadId: threadId || undefined,
-			Timestamp: Date.now(),
+			Timestamp: sentAt ? sentAt * 1000 : Date.now(),
 			WasMentioned: wasMentioned,
 			CommandAuthorized: true,
 			OriginatingChannel: "seatalk" as const,
@@ -771,6 +775,21 @@ async function processBufferedGroupEvents(
 
 		const replyThreadId = threadId || undefined;
 
+		const groupCoalescingEnabled = seatalkCfg?.outboundCoalescing !== false;
+		const sendGroupText = (text: string) =>
+			sendGroupTextMessage(client, groupId, text, 1, replyThreadId);
+		const chunkGroupText = (text: string, limit: number) =>
+			core.channel.text.chunkMarkdownText(text, limit);
+		const groupCoalescer = groupCoalescingEnabled
+			? createOutboundCoalescer({
+					send: sendGroupText,
+					chunkText: chunkGroupText,
+					maxLength: SEATALK_TEXT_CHUNK_LIMIT,
+					joiner: "\n\n",
+					idleFlushMs: OUTBOUND_COALESCE_IDLE_MS,
+				})
+			: null;
+
 		const typingResult = core.channel.reply.createReplyDispatcherWithTyping({
 			humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
 			deliver: async (payload) => {
@@ -778,16 +797,18 @@ async function processBufferedGroupEvents(
 				if (!reply.hasText && !reply.hasMedia) return;
 
 				if (reply.hasText) {
-					await sendGroupTextMessage(
-						client,
-						groupId,
-						reply.trimmedText,
-						1,
-						replyThreadId,
-					);
+					if (groupCoalescer) {
+						groupCoalescer.append(reply.trimmedText);
+					} else {
+						const chunks = chunkGroupText(reply.trimmedText, SEATALK_TEXT_CHUNK_LIMIT);
+						for (const chunk of chunks) {
+							await sendGroupText(chunk);
+						}
+					}
 				}
 
 				if (reply.hasMedia) {
+					if (groupCoalescer) await groupCoalescer.flush();
 					await deliverMediaReplies({
 						mediaUrls: reply.mediaUrls,
 						client,
@@ -823,6 +844,10 @@ async function processBufferedGroupEvents(
 			);
 		} finally {
 			typingResult.markDispatchIdle();
+			if (groupCoalescer) {
+				await typingResult.dispatcher.waitForIdle();
+				await groupCoalescer.flush();
+			}
 		}
 	} catch (err) {
 		error(`seatalk[${accountId}]: failed to dispatch group message: ${String(err)}`);

package/src/channel.ts

@@ -1,5 +1,6 @@
 import type { ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
-import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/core";
+import { createPairingPrefixStripper } from "openclaw/plugin-sdk/channel-pairing";
+import { DEFAULT_ACCOUNT_ID, PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/core";
 import {
 	listSeaTalkAccountIds,
 	resolveDefaultSeaTalkAccountId,
@@ -8,6 +9,7 @@ import {
 import { resolveSeaTalkClient } from "./client.js";
 import { seatalkOutbound } from "./outbound.js";
 import { probeSeaTalk } from "./probe.js";
+import { sendTextMessage } from "./send.js";
 import { seatalkSetupWizard } from "./setup-surface.js";
 import { looksLikeEmail, looksLikeSeaTalkId, normalizeSeaTalkTarget } from "./targets.js";
 import type { ResolvedSeaTalkAccount, SeaTalkConfig } from "./types.js";
@@ -26,6 +28,17 @@ const meta = {
 export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
 	id: "seatalk",
 	meta,
+	pairing: {
+		idLabel: "employeeCode",
+		normalizeAllowEntry: createPairingPrefixStripper(/^(seatalk|st):/i),
+		notifyApproval: async ({ cfg, id }) => {
+			const accountId = resolveDefaultSeaTalkAccountId(cfg);
+			const account = resolveSeaTalkAccount({ cfg, accountId });
+			const client = resolveSeaTalkClient(account);
+			if (!client) return;
+			await sendTextMessage(client, id, PAIRING_APPROVED_MESSAGE, 1);
+		},
+	},
 	capabilities: {
 		chatTypes: ["direct", "group"],
 		polls: false,
@@ -49,12 +62,13 @@ export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
 				relayUrl: { type: "string" },
 				webhookPort: { type: "integer", minimum: 1 },
 				webhookPath: { type: "string" },
-				dmPolicy: { type: "string", enum: ["open", "allowlist"] },
+				dmPolicy: { type: "string", enum: ["open", "allowlist", "pairing"] },
 				allowFrom: { type: "array", items: { type: "string" } },
 				groupPolicy: { type: "string", enum: ["disabled", "allowlist", "open"] },
 				groupAllowFrom: { type: "array", items: { type: "string" } },
 				groupSenderAllowFrom: { type: "array", items: { type: "string" } },
 				processingIndicator: { type: "string", enum: ["typing", "off"] },
+				mediaAllowHosts: { type: "array", items: { type: "string" } },
 				tools: {
 					type: "object",
 					properties: {
@@ -78,7 +92,7 @@ export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
 							relayUrl: { type: "string" },
 							webhookPort: { type: "integer", minimum: 1 },
 							webhookPath: { type: "string" },
-							dmPolicy: { type: "string", enum: ["open", "allowlist"] },
+							dmPolicy: { type: "string", enum: ["open", "allowlist", "pairing"] },
 							allowFrom: { type: "array", items: { type: "string" } },
 							groupPolicy: {
 								type: "string",
@@ -87,6 +101,7 @@ export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
 							groupAllowFrom: { type: "array", items: { type: "string" } },
 							groupSenderAllowFrom: { type: "array", items: { type: "string" } },
 							processingIndicator: { type: "string", enum: ["typing", "off"] },
+							mediaAllowHosts: { type: "array", items: { type: "string" } },
 						},
 					},
 				},
@@ -183,7 +198,7 @@ export const seatalkPlugin: ChannelPlugin<ResolvedSeaTalkAccount> = {
 			const dmPolicy = seatalkCfg?.dmPolicy ?? "allowlist";
 			if (dmPolicy !== "open") return [];
 			return [
-				`- SeaTalk[${account.accountId}]: dmPolicy="open" allows any subscriber to message the bot. Set channels.seatalk.dmPolicy="allowlist" + channels.seatalk.allowFrom to restrict senders.`,
+				`- SeaTalk[${account.accountId}]: dmPolicy="open" allows any subscriber to message the bot. Set channels.seatalk.dmPolicy to "allowlist" or "pairing" to restrict senders.`,
 			];
 		},
 	},

package/src/client.ts

@@ -3,6 +3,7 @@ import type { SeaTalkTokenInfo } from "./types.js";
 const BASE_URL = "https://openapi.seatalk.io";
 const HTTP_TIMEOUT_MS = 10_000;
 const TOKEN_REFRESH_MARGIN_S = 600;
+const RATE_LIMIT_RETRY_DELAYS_MS = [10_000, 60_000];
 
 export class SeaTalkClient {
 	private appId: string;
@@ -93,11 +94,13 @@ export class SeaTalkClient {
 		path: string,
 		body?: unknown,
 		retry = true,
+		rateLimitAttempt = 0,
 	): Promise<T> {
 		const token = await this.getAccessToken();
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), HTTP_TIMEOUT_MS);
 
+		let xRid: string | undefined;
 		try {
 			const res = await fetch(`${BASE_URL}${path}`, {
 				method,
@@ -109,7 +112,7 @@ export class SeaTalkClient {
 				signal: controller.signal,
 			});
 
-			const xRid = res.headers.get("x-rid") ?? undefined;
+			xRid = res.headers.get("x-rid") ?? undefined;
 
 			if (!res.ok) {
 				throw Object.assign(
@@ -126,10 +129,17 @@ export class SeaTalkClient {
 			}
 
 			if (data.code === 101) {
-				throw Object.assign(new Error("SeaTalk rate limit exceeded"), {
-					code: 101,
-					xRid,
-				});
+				if (rateLimitAttempt < RATE_LIMIT_RETRY_DELAYS_MS.length) {
+					const delay = RATE_LIMIT_RETRY_DELAYS_MS[rateLimitAttempt];
+					await new Promise((r) => setTimeout(r, delay));
+					return this.apiCall<T>(method, path, body, retry, rateLimitAttempt + 1);
+				}
+				throw Object.assign(
+					new Error(
+						`SeaTalk rate limit exceeded after ${rateLimitAttempt + 1} attempts (x-rid: ${xRid})`,
+					),
+					{ code: 101, xRid },
+				);
 			}
 
 			if (data.code !== 0) {
@@ -142,6 +152,11 @@ export class SeaTalkClient {
 			}
 
 			return data;
+		} catch (err) {
+			if (xRid && err instanceof Error && !err.message.includes("x-rid:")) {
+				err.message += ` (x-rid: ${xRid})`;
+			}
+			throw err;
 		} finally {
 			clearTimeout(timeout);
 		}

package/src/config-schema.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 export { z };
 
-const DmPolicySchema = z.enum(["open", "allowlist"]);
+const DmPolicySchema = z.enum(["open", "allowlist", "pairing"]);
 const GatewayModeSchema = z.enum(["webhook", "relay"]);
 const GroupPolicySchema = z.enum(["disabled", "allowlist", "open"]);
 const ProcessingIndicatorSchema = z.enum(["typing", "off"]);
@@ -32,6 +32,8 @@ export const SeaTalkAccountConfigSchema = z
 		groupAllowFrom: z.array(z.string()).optional(),
 		groupSenderAllowFrom: z.array(z.string()).optional(),
 		processingIndicator: ProcessingIndicatorSchema.optional(),
+		mediaAllowHosts: z.array(z.string()).optional(),
+		outboundCoalescing: z.boolean().optional(),
 	})
 	.strict();
 
@@ -51,6 +53,8 @@ export const SeaTalkConfigSchema = z
 		groupAllowFrom: z.array(z.string()).optional(),
 		groupSenderAllowFrom: z.array(z.string()).optional(),
 		processingIndicator: ProcessingIndicatorSchema.optional().default("typing"),
+		mediaAllowHosts: z.array(z.string()).optional(),
+		outboundCoalescing: z.boolean().optional().default(true),
 		tools: SeaTalkToolsConfigSchema.optional(),
 		accounts: z.record(z.string(), SeaTalkAccountConfigSchema.optional()).optional(),
 	})

package/src/inbound-resolve.ts

@@ -0,0 +1,147 @@
+import { sendMediaWithLeadingCaption } from "openclaw/plugin-sdk/reply-payload";
+import type { SeaTalkClient } from "./client.js";
+import { resolveInboundMedia } from "./media.js";
+import { sendMediaToTarget } from "./send.js";
+import type { SeaTalkMediaInfo, SeaTalkMessage } from "./types.js";
+
+export type MessageResolveContext = {
+	client: SeaTalkClient;
+	mediaAllowHosts?: string[] | null;
+	log: (msg: string) => void;
+};
+
+function formatSenderPrefix(data: Record<string, unknown>): string {
+	const sender = data.sender as { email?: string; employee_code?: string } | undefined;
+	const sentTime = data.message_sent_time as number | undefined;
+	const parts: string[] = [];
+	if (sender?.email) parts.push(sender.email);
+	else if (sender?.employee_code) parts.push(sender.employee_code);
+	if (sentTime) parts.push(new Date(sentTime * 1000).toISOString());
+	return parts.length > 0 ? `[${parts.join(" ")}] ` : "";
+}
+
+function toSeaTalkMessage(data: Record<string, unknown>): SeaTalkMessage {
+	const tag = data.tag as SeaTalkMessage["tag"];
+	return {
+		message_id: (data.message_id as string) ?? "",
+		tag,
+		text: data.text as SeaTalkMessage["text"],
+		image: data.image as SeaTalkMessage["image"],
+		file: data.file as SeaTalkMessage["file"],
+		video: data.video as SeaTalkMessage["video"],
+		combined_forwarded_chat_history:
+			data.combined_forwarded_chat_history as SeaTalkMessage["combined_forwarded_chat_history"],
+	};
+}
+
+export async function resolveMessageContent(
+	data: Record<string, unknown>,
+	ctx: MessageResolveContext,
+): Promise<{ text: string; media: SeaTalkMediaInfo[] }> {
+	const tag = data.tag as string | undefined;
+	const media: SeaTalkMediaInfo[] = [];
+
+	if (tag === "text") {
+		const textObj = data.text as { plain_text?: string; content?: string } | undefined;
+		return { text: textObj?.plain_text ?? textObj?.content ?? "", media };
+	}
+
+	if (tag === "image" || tag === "file" || tag === "video") {
+		const resolved = await resolveInboundMedia({
+			message: toSeaTalkMessage(data),
+			client: ctx.client,
+			mediaAllowHosts: ctx.mediaAllowHosts,
+			log: ctx.log,
+		});
+		if (resolved) {
+			media.push(resolved);
+			return { text: resolved.placeholder, media };
+		}
+		return { text: `<media:${tag}>`, media };
+	}
+
+	if (tag === "combined_forwarded_chat_history") {
+		const fwd = (data.combined_forwarded_chat_history as { content?: unknown[] } | undefined)
+			?.content;
+		if (fwd) {
+			const result = await resolveForwardedMessages(fwd, ctx);
+			media.push(...result.media);
+			return {
+				text:
+					result.lines.length > 0
+						? `[Forwarded messages]\n${result.lines.join("\n")}`
+						: "[Forwarded messages]",
+				media,
+			};
+		}
+		return { text: "[Forwarded messages]", media };
+	}
+
+	return { text: `<unsupported:${tag ?? "unknown"}>`, media };
+}
+
+export async function resolveForwardedMessages(
+	content: unknown[],
+	ctx: MessageResolveContext,
+): Promise<{ lines: string[]; media: SeaTalkMediaInfo[] }> {
+	const lines: string[] = [];
+	const media: SeaTalkMediaInfo[] = [];
+	for (const item of content) {
+		if (Array.isArray(item)) {
+			const nested = await resolveForwardedMessages(item, ctx);
+			lines.push(...nested.lines);
+			media.push(...nested.media);
+			continue;
+		}
+		if (!item || typeof item !== "object") continue;
+
+		const rec = item as Record<string, unknown>;
+		const prefix = formatSenderPrefix(rec);
+		const result = await resolveMessageContent(rec, ctx);
+		media.push(...result.media);
+		if (result.text) lines.push(`${prefix}${result.text}`);
+	}
+	return { lines, media };
+}
+
+export async function resolveQuotedMessage(params: {
+	client: SeaTalkClient;
+	quotedMessageId: string;
+	mediaAllowHosts?: string[] | null;
+	log: (msg: string) => void;
+}): Promise<{ text: string; media: SeaTalkMediaInfo[] } | null> {
+	const { client, quotedMessageId, mediaAllowHosts, log } = params;
+	try {
+		const data = await client.getMessageByMessageId(quotedMessageId);
+		const senderObj = data.sender as { employee_code?: string; email?: string } | undefined;
+		const senderCode = senderObj?.employee_code ?? "unknown";
+		const sender = senderObj?.email ? `${senderCode} (${senderObj.email})` : senderCode;
+
+		const result = await resolveMessageContent(data, { client, mediaAllowHosts, log });
+		return { text: `[Quoted from ${sender}: ${result.text}]`, media: result.media };
+	} catch (err) {
+		log(`seatalk: failed to resolve quoted message ${quotedMessageId}: ${String(err)}`);
+		return null;
+	}
+}
+
+export async function deliverMediaReplies(params: {
+	mediaUrls: string[];
+	client: SeaTalkClient;
+	to: string;
+	threadId?: string;
+	isGroup: boolean;
+	log: (msg: string) => void;
+}): Promise<void> {
+	const { mediaUrls, client, to, threadId, isGroup, log } = params;
+	await sendMediaWithLeadingCaption({
+		mediaUrls,
+		caption: "",
+		send: async ({ mediaUrl }) => {
+			await sendMediaToTarget({ client, to, mediaUrl, threadId, isGroup });
+		},
+		onError: async ({ error, mediaUrl }) => {
+			log(`seatalk: failed to send media ${mediaUrl}: ${String(error)}`);
+		},
+	});
+}

package/src/media.ts

@@ -15,13 +15,42 @@ const MAX_OUTBOUND_RAW_BYTES = 3.75 * 1024 * 1024; // ~3.75MB raw → 5MB base64
 const SMALL_FILE_THRESHOLD = 10 * 1024 * 1024; // 10MB
 const MAX_INBOUND_SAVE_BYTES = 250 * 1024 * 1024; // 250MB
 
+const DEFAULT_MEDIA_ALLOWED_HOSTS = ["openapi.seatalk.io"] as const;
+
+export function resolveMediaAllowedHosts(configured?: string[] | null): Set<string> {
+	const raw = configured && configured.length > 0 ? configured : [...DEFAULT_MEDIA_ALLOWED_HOSTS];
+	return new Set(raw.map((h) => h.trim().toLowerCase()).filter(Boolean));
+}
+
+function gateInboundMediaUrl(
+	urlString: string,
+	allowedHosts: Set<string>,
+): { ok: true; hostname: string } | { ok: false; detail: string } {
+	let parsed: URL;
+	try {
+		parsed = new URL(urlString);
+	} catch {
+		return { ok: false, detail: "invalid URL" };
+	}
+	if (parsed.protocol !== "https:") {
+		return { ok: false, detail: `only https allowed (got ${parsed.protocol})` };
+	}
+	const hostname = parsed.hostname.toLowerCase();
+	if (!allowedHosts.has(hostname)) {
+		return { ok: false, detail: `host not in allowlist (${hostname})` };
+	}
+	return { ok: true, hostname };
+}
+
 export async function resolveInboundMedia(params: {
 	message: SeaTalkMessage;
 	client: SeaTalkClient;
+	mediaAllowHosts?: string[] | null;
 	log?: (msg: string) => void;
 }): Promise<SeaTalkMediaInfo | null> {
-	const { message, client, log } = params;
+	const { message, client, log, mediaAllowHosts } = params;
 	const core = getSeatalkRuntime();
+	const allowedHosts = resolveMediaAllowedHosts(mediaAllowHosts);
 
 	let url: string | undefined;
 	let filename: string | undefined;
@@ -46,6 +75,13 @@ export async function resolveInboundMedia(params: {
 
 	if (!url) return null;
 
+	const gate = gateInboundMediaUrl(url, allowedHosts);
+	if (!gate.ok) {
+		log?.(`seatalk: rejected inbound ${message.tag} media before download: ${gate.detail}`);
+		return null;
+	}
+	log?.(`seatalk: inbound ${message.tag} media url host=${gate.hostname}`);
+
 	const MAX_RETRY = 1;
 
 	for (let attempt = 0; attempt <= MAX_RETRY; attempt++) {
@@ -57,12 +93,15 @@ export async function resolveInboundMedia(params: {
 				(!contentType || contentType === "application/octet-stream") &&
 				result.buffer.length < SMALL_FILE_THRESHOLD
 			) {
-				contentType = await core.media.detectMime({ buffer: result.buffer });
+				const detected = await core.media.detectMime({ buffer: result.buffer });
+				if (detected) {
+					contentType = detected;
+				}
 			}
 
 			const saved = await core.channel.media.saveMediaBuffer(
 				result.buffer,
-				contentType,
+				contentType ?? "application/octet-stream",
 				"inbound",
 				MAX_INBOUND_SAVE_BYTES,
 				filename,

package/src/outbound-coalescer.ts

@@ -0,0 +1,84 @@
+export type OutboundCoalescer = {
+	append: (text: string) => void;
+	flush: () => Promise<void>;
+	hasBuffered: () => boolean;
+};
+
+export function createOutboundCoalescer(params: {
+	send: (text: string) => Promise<void>;
+	chunkText: (text: string, limit: number) => string[];
+	maxLength: number;
+	joiner: string;
+	idleFlushMs?: number;
+}): OutboundCoalescer {
+	const { send, chunkText, maxLength, joiner, idleFlushMs } = params;
+
+	let buffer = "";
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let sendChain: Promise<void> = Promise.resolve();
+
+	const clearIdleTimer = () => {
+		if (!idleTimer) return;
+		clearTimeout(idleTimer);
+		idleTimer = undefined;
+	};
+
+	const sendBuffered = () => {
+		if (!buffer) return;
+		const text = buffer;
+		buffer = "";
+		const chunks = text.length > maxLength ? chunkText(text, maxLength) : [text];
+		const doSend = async () => {
+			for (const chunk of chunks) {
+				await send(chunk);
+			}
+		};
+		// Use rejection handler to recover from prior failures so the chain never stays broken.
+		sendChain = sendChain.then(doSend, doSend);
+		// Prevent unhandled-rejection warnings when triggered by idle timer.
+		sendChain.catch(() => {});
+	};
+
+	const scheduleIdleFlush = () => {
+		if (!idleFlushMs || idleFlushMs <= 0) return;
+		clearIdleTimer();
+		idleTimer = setTimeout(() => {
+			idleTimer = undefined;
+			sendBuffered();
+		}, idleFlushMs);
+	};
+
+	const append = (text: string) => {
+		if (!text) return;
+		clearIdleTimer();
+
+		if (!buffer) {
+			buffer = text;
+			scheduleIdleFlush();
+			return;
+		}
+
+		const next = `${buffer}${joiner}${text}`;
+		if (next.length > maxLength) {
+			sendBuffered();
+			buffer = text;
+			scheduleIdleFlush();
+			return;
+		}
+
+		buffer = next;
+		scheduleIdleFlush();
+	};
+
+	const flush = async () => {
+		clearIdleTimer();
+		sendBuffered();
+		await sendChain;
+	};
+
+	return {
+		append,
+		flush,
+		hasBuffered: () => buffer.length > 0,
+	};
+}

package/src/types.ts

@@ -64,6 +64,7 @@ export type SeaTalkMessage = {
 	image?: { content: string };
 	file?: { content: string; filename: string };
 	video?: { content: string };
+	combined_forwarded_chat_history?: { content: unknown[] };
 };
 
 export type SeaTalkMediaInfo = {