Telegram: improve webhook config guidance and startup fallback

src/config/zod-schema.providers-core.ts

@@ -165,11 +165,37 @@ export const TelegramAccountSchemaBase = z
       .strict()
       .optional(),
     proxy: z.string().optional(),
-    webhookUrl: z.string().optional(),
+    webhookUrl: z
-    webhookSecret: z.string().optional().register(sensitive),
+      .string()
-    webhookPath: z.string().optional(),
+      .optional()
-    webhookHost: z.string().optional(),
+      .describe(
-    webhookPort: z.number().int().positive().optional(),
+        "Public HTTPS webhook URL registered with Telegram for inbound updates. This must be internet-reachable and requires channels.telegram.webhookSecret.",
+      ),
+    webhookSecret: z
+      .string()
+      .optional()
+      .describe(
+        "Secret token sent to Telegram during webhook registration and verified on inbound webhook requests. Telegram returns this value for verification; this is not the gateway auth token and not the bot token.",
+      )
+      .register(sensitive),
+    webhookPath: z
+      .string()
+      .optional()
+      .describe(
+        "Local webhook route path served by the gateway listener. Defaults to /telegram-webhook.",
+      ),
+    webhookHost: z
+      .string()
+      .optional()
+      .describe(
+        "Local bind host for the webhook listener. Defaults to 127.0.0.1; keep loopback unless you intentionally expose direct ingress.",
+      ),
+    webhookPort: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe("Local bind port for the webhook listener. Defaults to 8787."),
     actions: z
       .object({
         reactions: z.boolean().optional(),

src/telegram/webhook.test.ts

@@ -207,6 +207,7 @@ describe("startTelegramWebhook", () => {
     initSpy.mockClear();
     createTelegramBotSpy.mockClear();
     webhookCallbackSpy.mockClear();
+    const runtimeLog = vi.fn();
     const abort = new AbortController();
     const cfg = { bindings: [] };
     const { server } = await startTelegramWebhook({
@@ -216,6 +217,7 @@ describe("startTelegramWebhook", () => {
       config: cfg,
       port: 0, // random free port
       abortSignal: abort.signal,
+      runtime: { log: runtimeLog, error: vi.fn(), exit: vi.fn() },
     });
     expect(createTelegramBotSpy).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -246,6 +248,13 @@ describe("startTelegramWebhook", () => {
         timeoutMilliseconds: 10_000,
       },
     );
+    expect(runtimeLog).toHaveBeenCalledWith(
+      expect.stringContaining("webhook local listener on http://127.0.0.1:"),
+    );
+    expect(runtimeLog).toHaveBeenCalledWith(expect.stringContaining("/telegram-webhook"));
+    expect(runtimeLog).toHaveBeenCalledWith(
+      expect.stringContaining("webhook advertised to telegram on http://"),
+    );
 
     abort.abort();
   });

src/telegram/webhook.ts

@@ -250,7 +250,8 @@ export async function startTelegramWebhook(opts: {
     throw err;
   }
 
-  runtime.log?.(`webhook listening on ${publicUrl}`);
+  runtime.log?.(`webhook local listener on http://${host}:${port}${path}`);
+  runtime.log?.(`webhook advertised to telegram on ${publicUrl}`);
 
   let shutDown = false;
   const shutdown = () => {