Communitygithub.com

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Richte Telegram-Bot-Benachrichtigungen für erfolgreiche Zahlungen vom Sepay-Webhook in einem Next.js-Projekt ein.

Was ist MKT.LANDINGPAGE.SKILLS?

Dieses Skill automatisiert die Einrichtung von Echtzeit-Telegram-Benachrichtigungen für erfolgreiche Zahlungseingänge, die über den Sepay-Webhook in einem Next.js-Projekt erfasst werden. Es richtet einen Telegram-Bot ein, der den Eigentümer oder das Vertriebsteam sofort benachrichtigt, sobald ein Kunde eine Überweisung tätigt, und zwar mit Details wie Name, Telefonnummer, Betrag und Produkt. Das Skill erkennt automatisch vorhandene Sepay-Webhook-Routen im Projekt, erstellt eine wiederverwendbare Hilfsfunktion `sendTelegramNotification()` in `lib/telegram.ts` und integriert diese parallel zu bestehenden E-Mail-Autorespondern (z. B. Resend) unter Verwendung von `Promise.allSettled`. Dadurch wird sichergestellt, dass ein Fehler beim Telegram-Versand die 200er-Antwort an Sepay nicht blockiert, was wiederum verhindert, dass Sepay den Webhook erneut sendet und doppelte Benachrichtigungen verursacht. Das Skill enthält eine Schritt-für-Schritt-Anleitung zum Erstellen eines Telegram-Bots über @BotFather, zum Abrufen von Token und Chat-ID, zum Definieren eines anpassbaren Nachrichtenformats und zum Aktualisieren der Umgebungsvariablen. Es unterstützt sowohl Einzelchat- als auch Gruppenbenachrichtigungen und bewältigt verschiedene Szenarien, z. B. das Fehlen eines Lead-Speichers, indem es einen Raw-Modus für einfache Sepay-Payload-Benachrichtigungen anbietet.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lexuanthanhhy/MKT.LANDINGPAGE.SKILLS/tree/main/.claude/skills/biz-telegram-payment-notify

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Biz Telegram Payment Notify — Realtime-Alarm bei Sepay-Zahlungseingang

Dieses Skill richtet eine Telegram-Bot-Benachrichtigung in Ihren bestehenden Sepay-Webhook in einem Next.js-Projekt ein. Immer wenn ein Kunde erfolgreich Geld auf Ihr mit Sepay verbundenes Bankkonto überweist, sendet der Bot eine Echtzeitnachricht an den Chat des Eigentümers (oder an die Vertriebsgruppe) — mit Name, Telefonnummer, Betrag, Produkt und Zeitstempel.

Philosophie: E-Mail-Autoresponder für Kunden (Resend) und Telegram-Benachrichtigungen für den Eigentümer bedienen zwei unterschiedliche Akteure. E-Mail ist formell für den Kunden. Telegram ist ein "Ping" für den Eigentümer — Sie sind unterwegs, öffnen Telegram und sehen sofort die neue Bestellung, ohne in 100 anderen E-Mails in Gmail suchen zu müssen. Latenz Telegram < 2 Sekunden vs. E-Mail 30-60 Sekunden.

Warum Telegram und nicht Slack/Discord/Zalo: Telegram-Bot-Setup in 5 Minuten (1 Token + 1 Chat-ID), kein Workspace/Server-Admin nötig, kostenlose unbegrenzte Nachrichten, Push-Benachrichtigungen leistungsstärker als E-Mail, native Apps auf iOS/Android/Desktop. Slack benötigt einen Workspace + Einladung. Discord benötigt einen Server + Berechtigungseinrichtung. Zalo OA benötigt ein verifiziertes Geschäftskonto (3-7 Tage Genehmigung) + monatliche Gebühren für aktive Nutzer. Telegram ist der Weg des geringsten Widerstands für Eigentümer-seitige Benachrichtigungen.

Ausgabe: Code-Patch + Bot-Setup-Anleitung Schritt für Schritt + Umgebungsvariablen-Liste + Testplan mit 3 Stufen. Das Skill testet NICHT selbst das Senden von Telegram — es fordert den Benutzer auf, zuerst Bot-Token und Chat-ID einzufügen, da diese Anmeldeinformationen Eigentum des Benutzers sind.


Wann dieses Skill verwenden

  • Der Benutzer hat gerade den Sepay-Webhook eingerichtet und möchte in Echtzeit auf Telegram benachrichtigt werden, wenn ein Kunde Geld überweist.
  • Der Benutzer hat bereits einen /api/payment-success (oder ähnlich), der E-Mails mit Resend verarbeitet, und möchte nun eine Telegram-Benachrichtigung PARALLEL hinzufügen — ohne eine neue Route zu erstellen und ohne Logik zu duplizieren.
  • Der Benutzer sagt "benachrichtigen Sie mich bei neuen Bestellungen" und der Kontext ist eine Verkaufs-Landingpage mit Sepay-Integration.

Verwenden Sie dieses Skill NICHT, wenn:

  • Der Benutzer Slack/Discord-Benachrichtigungen wünscht → anderer Anwendungsfall.
  • Der Benutzer einen Zalo OA Bot wünscht → erfordert ein verifiziertes Geschäftskonto + andere Kostenstruktur.
  • Der Benutzer noch keinen Sepay-Webhook eingerichtet hat (noch kein Bankkonto mit Sepay verbunden, noch keinen Endpunkt zum Empfangen von Webhooks) → dieses Skill richtet Sepay nicht von Grund auf neu ein, es wird nur in den vorhandenen Webhook eingebunden.
  • Der Benutzer nur E-Mail-Benachrichtigungen für den Eigentümer wünscht → biz-email-setup hat bereits E-Mail B (Eigentümer-Benachrichtigung).

Gesamtworkflow (6 Phasen)

Phase 0: VORHANDENE Sepay-Webhook-Route erkennen (Pfad + Framework + Handler-Struktur)
       ↓
Phase 0.5: Lead-Speicher erkennen (lib/leads-kv.ts von /biz-setup-sepay-payment)
           → vorhanden: Echten KV-Lookup verwenden
           → nicht vorhanden: 2 Optionen anbieten (Raw-Mode ODER zuerst /biz-setup-sepay-payment ausführen)
       ↓
Phase 1: BENUTZER ANLEITEN, Telegram-Bot zu erstellen (BotFather → Token → Chat-ID)
       ↓ [GATE — warten auf Benutzereingabe von Token + Chat-ID]
       ↓
Phase 2: NACHRICHTENFORMAT ENTWERFEN → Vorschau anzeigen → Bestätigung einholen
       ↓
Phase 3: CODE EINBINDEN (lib/telegram.ts Helper + Integration in Webhook-Handler + Umgebungsvariablen)
       ↓
Phase 4: TESTPLAN (curl Bot direkt → simulierte Sepay-Payload → Produktionsüberprüfung)

Phase 1 und Phase 4 haben ein Gate, das auf den Benutzer wartet, da manuelle Benutzereingriffe erforderlich sind (Token abrufen, Produktion überprüfen). Phase 0/0.5/2/3 führt das Skill automatisch aus.


Phase 0 — Vorhandenen Sepay-Webhook erkennen

Dieses Skill wird in den vorhandenen Webhook eingebunden, es wird KEINE neue Route erstellt. Zuerst muss der Handler lokalisiert werden.

Webhook-Route suchen — grep mit gängigen Schlüsselwörtern:

# Im Projektstammverzeichnis
grep -r "sepay" --include="*.ts" --include="*.js" --include="*.tsx" -l
grep -r "transferAmount\|transferType\|payment-success\|payment-webhook" --include="*.ts" --include="*.js" -l

3 häufige Szenarien:

SzenarioVorhandener PfadAktion
Benutzer verwendet Pipeline biz-email-setupapp/api/payment-success/route.ts (oder pages/api/payment-success.ts) mit vorhandenem Resend, der sendCustomerEmail + sendOwnerEmail aufruftsendTelegramNotification in dieselbe Promise.allSettled einbinden
Benutzer hat Sepay-spezifische Routeapp/api/sepay-webhook/route.ts oder app/api/webhook/sepay/route.tsNach dem Parsen + Validieren der Sepay-Payload einbinden (Zweig transferType === 'in')
Keine Route gefunden—STOPP. Benutzer informieren: "Ich habe keine Webhook-Route für Sepay gefunden. Bitte richten Sie zuerst den Sepay-Webhook ein (Bankkonto mit Sepay verbinden → Webhook-URL auf Ihre Domain erstellen) und kommen Sie dann zurück, damit ich Telegram einbinden kann. Oder wenn der Webhook unter einem anderen Endpunkt-Namen liegt, teilen Sie mir bitte den Pfad mit."

Vorhandenen Handler lesen, um die Struktur zu verstehen:

  • Authentifiziert er die Sepay-Anfrage? (Authorization-Header Apikey oder HMAC)
  • Führt er eine Deduplizierung basierend auf id oder referenceCode durch? (Sepay wiederholt den Vorgang bei non-200 → Deduplizierung erforderlich, um doppelte Benachrichtigungen zu vermeiden)
  • Führt er einen Lead-Lookup basierend auf content durch (Transfernachricht enthält Bestell-ID)?
  • Antwortformat an Sepay: { success: true } oder einfaches 200 OK?

Wenn der aktuelle Handler noch keine Deduplizierung durchführt — den Benutzer warnen, aber NICHT blockieren. Das Skill bindet nur Telegram ein, die Deduplizierung ist ein Anliegen der Zahlungslogik. Dem Benutzer vorschlagen, bei Bedarf eine separate Deduplizierung hinzuzufügen.


Phase 0.5 — Lead-Speicher erkennen (KRITISCH)

Der Sepay-Webhook sendet nur content (Text, den der Kunde bei der Überweisung eingefügt hat) + transferAmount + referenceCode. Sepay kennt den Kunden NICHT — es muss ein lokaler Speicher basierend auf content (enthält Bestell-ID) durchsucht werden.

Das Skill überprüft 3 Dinge:

# 1. Prüfen, ob Lead-Speicher-Helper existiert
test -f lib/leads-kv.ts || test -f lib/leads-kv.js && echo "Lead-Speicher: ✓"

# 2. Prüfen, ob Vercel KV Umgebungsvariablen vorhanden sind
grep -E "KV_REST_API_URL|KV_REST_API_TOKEN" .env.local && echo "KV Umgebungsvariablen: ✓"

# 3. Prüfen, ob @vercel/kv installiert ist
grep '"@vercel/kv"' package.json && echo "KV Paket: ✓"

3 Szenarien:

SzenarioAktion
Alle 3 ✓ — Lead-Speicher bereitMit Phase 1 fortfahren, getLeadByOrderId() aus lib/leads-kv.ts im Webhook-Handler verwenden
1+ fehlt — noch nicht eingerichtetSTOPP, Benutzer nach 2 Optionen fragen (siehe unten)

Wenn etwas fehlt, den Benutzer fragen:

Ich habe festgestellt, dass Sie noch keinen Lead-Speicher (Vercel KV) haben. Der Sepay-Webhook kennt den Kunden nicht — er hat nur den Überweisungstext + den Betrag. Möchten Sie:

Option 1 — Vollständigen Lead-Speicher über /biz-setup-sepay-payment einrichten (empfohlen):

  • Dieses Skill richtet Vercel KV ein + erstellt das Grundgerüst lib/leads-kv.ts + bindet das Formular ein, um Leads bei der Registrierung zu speichern
  • Kommen Sie dann hierher zurück, damit ich Telegram mit vollständigem Lookup von Name/Telefon/E-Mail des Kunden einbinden kann
  • Die Telegram-Benachrichtigung zeigt dann: "Nguyễn Văn A — 0901234567 — [email protected] — 499K — KI-Agent-Kurs"

Option 2 — Raw-Mode: Sepay-Payload direkt an Telegram senden, ohne Lead-Lookup:

  • Telegram zeigt nur: "Vietcombank — 499.000₫ — Inhalt: DH001 0901234567 — 14:32"
  • Der Eigentümer muss den Kunden anhand des Inhalts erraten und mit dem Resend-E-Mail-Protokoll abgleichen
  • Einfach, sofort ausführbar, aber schlechtere Benutzererfahrung

Welche Option bevorzugen Sie?

Wenn der Benutzer Option 1 wählt → Dieses Skill ANHALTEN, /biz-setup-sepay-payment vorschlagen. Nachdem der Benutzer die Einrichtung abgeschlossen hat → zu diesem Skill zurückkehren.

Wenn der Benutzer Option 2 wählt → Mit Phase 1 fortfahren, Raw-Template verwenden (siehe templates/lib-telegram-raw.ts).


Phase 1 — Benutzer anleiten, Telegram-Bot zu erstellen

Lesen Sie references/telegram-bot-setup.md für eine detaillierte Anleitung mit Text-Screenshots. Zusammenfassung der 3 Schritte für den Benutzer:

Schritt 1 — Neuen Bot über @BotFather erstellen

1. Telegram öffnen (mobil/desktop)
2. Suchen: @BotFather → Start drücken
3. Befehl eingeben: /newbot
4. BotFather fragt nach dem Bot-Namen — Anzeigenamen eingeben (z. B. "Bestellungen Marke X")
5. BotFather fragt nach dem Benutzernamen — Benutzernamen eingeben, der auf "_bot" endet (z. B. marke_x_bestellungen_bot) — muss global eindeutig sein
6. BotFather sendet eine Nachricht mit der Zeile:
   "Use this token to access the HTTP API: 1234567890:AAxxxxxxxxxxxxxxxxxxxxxx"
7. Token kopieren und hier einfügen.

SICHERHEITSHINWEIS: Dieses Token = volle Kontrolle über den Bot. Nicht in Git committen, nicht öffentlich teilen. Bei versehentlichem Leck → zurück zu @BotFather → /token → /revoke, um einen neuen Token zu erstellen.

Schritt 2 — Chat-ID abrufen

1-zu-1-Chat (nur Eigentümer erhält Benachrichtigungen) — empfohlen für Solopreneure:

1. In Telegram suchen: @userinfobot → Start drücken
2. Der Bot sendet eine Nachricht mit "Id: 123456789" — diese Nummer kopieren.
3. Das ist Ihre Chat-ID.

Gruppenchat (Vertriebsteam erhält gemeinsam Benachrichtigungen) — empfohlen für Teams:

1. Neue Telegram-Gruppe erstellen (oder vorhandene Gruppe verwenden)
2. Auf Gruppennamen klicken → Mitglied hinzufügen → nach dem erstellten Bot suchen (unter @marke_x_bestellungen_bot) → Hinzufügen
3. In der Gruppe eingeben: /start@marke_x_bestellungen_bot (oder eine beliebige Nachricht)
4. Browser öffnen und aufrufen:
   https://api.telegram.org/bot<TOKEN>/getUpdates
   (<TOKEN> durch Token aus Schritt 1 ersetzen)
5. In der JSON-Antwort "chat":{"id":-1001234567890,...} suchen — diese Nummer kopieren (Minuszeichen nicht vergessen)
6. Das ist die Chat-ID der Gruppe.

Kanal (1-Wege-Rundfunk, keine Diskussion) — Chat-ID beginnt mit -100. Abrufmethode wie bei Gruppe, aber Bot als Admin des Kanals hinzufügen.

Schritt 3 — Für das Skill einfügen

Auf Benutzereingabe warten:

TELEGRAM_BOT_TOKEN=1234567890:AAxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHAT_ID=123456789

WICHTIGES GATE: NICHT mit Phase 2 fortfahren, bis der Benutzer beide Werte eingefügt hat. Wenn der Benutzer sagt "ich habe sie bereits, von woanders" → trotzdem auf Eingabe warten, da sie in Phase 3 in .env.local eingefügt werden müssen.


Phase 2 — Nachrichtenformat entwerfen

Standardformat auf Vietnamesisch, mobilfreundlich (Telegram rendert HTML):

🎉 <b>NEUE BESTELLUNG</b>

👤 <b>{{name}}</b>
📞 {{phone}}
📧 {{email}}
💰 <b>{{amount}}</b> — {{product_name}}
🕐 {{time_vn}}

🔗 Transaktionscode: <code>{{reference_code}}</code>

Nach dem Einfügen der Variablen:

🎉 NEUE BESTELLUNG

👤 Nguyễn Văn A
📞 0901 234 567
📧 [email protected]
💰 499.000₫ — KI-Agent-Kurs
🕐 14:32 14/05/2026

🔗 Transaktionscode: FT26134567890

Vorschau für Benutzer anzeigen, fragen:

  1. Ist dieses Format in Ordnung? Möchten Sie ein Feld hinzufügen/entfernen? (z. B. UTM-Quelle, Bestellnummer des Tages, Zalo-Link des Kunden)
  2. Sind zu viele Emojis vorhanden? (Einige Benutzer bevorzugen Klartext)
  3. Möchten Sie eine Inline-Schaltfläche (CTA) mit Link zum CRM/zu Sheets hinzufügen? (Fortgeschritten — das Skill kann eine Inline-Tastatur hinzufügen)

Formatierungsregeln:

  • HTML-Modus (parse_mode: "HTML") — Telegram unterstützt <b>, <i>, <u>, <code>, <pre>, <a href>. KEINE Unterstützung für <br> — \n verwenden.
  • Betragsformat VN: 499.000₫ (Punkt als Tausendertrennzeichen, mit ₫ am Ende) ODER charmant 499K / 1.99M für eine schönere Darstellung. Aus offer.json voice-Einstellung lesen, falls vorhanden.
  • Telefonformat: 0901 234 567 (3-3-3-Abstand) — einfacher auf dem Handy zu scannen.
  • Zeit VN: HH:mm dd/mm/yyyy — Vietnam-Zeit (UTC+7) einstellen, nicht UTC.
  • Emoji-Spam vermeiden (>5 Emojis/Nachricht → verringert den professionellen Eindruck).

Phase 3 — Code einbinden

3 Änderungen:

3.1 Hilfsfunktion lib/telegram.ts erstellen

templates/lib-telegram.ts (TypeScript) oder templates/lib-telegram.js (vanilla JS) lesen. Inhalt:

// lib/telegram.ts
type TelegramPayload = {
  name: string;
  phone: string;
  email: string;
  amount: number; // VND, Rohzahl (z. B. 499000)
  productName: string;
  referenceCode?: string;
};

export async function sendTelegramNotification(payload: TelegramPayload): Promise<void> {
  const token = process.env.TELEGRAM_BOT_TOKEN;
  const chatId = process.env.TELEGRAM_CHAT_ID;

  if (!token || !chatId) {
    console.error('[telegram] TELEGRAM_BOT_TOKEN oder TELEGRAM_CHAT_ID fehlt');
    return; // Nicht werfen — Telegram-Fehler darf die Zahlungsantwort nicht blockieren
  }

  const text = formatMessage(payload);

  try {
    const res = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: chatId,
        text,
        parse_mode: 'HTML',
        disable_web_page_preview: true,
      }),
    });
    if (!res.ok) {
      const errBody = await res.text();
      console.error(`[telegram] Senden fehlgeschlagen: ${res.status} ${errBody}`);
    }
  } catch (err) {
    console.error('[telegram] Netzwerkfehler:', err);
    // Swallow — Telegram-Fehler soll keinen Sepay-Retry verursachen
  }
}

function formatMessage(p: TelegramPayload): string {
  const amountStr = p.amount.toLocaleString('vi-VN') + '₫';
  const phoneStr = p.phone.replace(/(\d{4})(\d{3})(\d{3})/, '$1 $2 $3');
  const now = new Date().toLocaleString('vi-VN', {
    timeZone: 'Asia/Ho_Chi_Minh',
    day: '2-digit', month: '2-digit', year: 'numeric',
    hour: '2-digit', minute: '2-digit',
  });
  return [
    '🎉 <b>NEUE BESTELLUNG</b>',
    '',
    `👤 <b>${escapeHtml(p.name)}</b>`,
    `📞 ${phoneStr}`,
    `📧 ${escapeHtml(p.email)}`,
    `💰 <b>${amountStr}</b> — ${escapeHtml(p.productName)}`,
    `🕐 ${now}`,
    p.referenceCode ? `\n🔗 Transaktionscode: <code>${escapeHtml(p.referenceCode)}</code>` : '',
  ].filter(Boolean).join('\n');
}

function escapeHtml(s: string): string {
  return s.replace(/[<>&]/g, c => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' }[c]!));
}

Warum Fehler schlucken: Sepay wiederholt den Webhook, wenn ein non-200 empfangen wird. Wenn ein Telegram-Timeout/-Ausfall den Webhook zum Absturz bringt → Sepay wiederholt → jeder Wiederholungsversuch sendet erneut eine E-Mail + protokolliert die Zahlung erneut → der Benutzer erhält 5 E-Mails + 5 Telegram-Benachrichtigungen für eine einzige Bestellung. Telegram ist ein Best-Effort-Seitenkanal, kein kritischer Pfad.

3.2 In Sepay-Webhook-Handler einbinden

Den vorhandenen Handler lesen, die Stelle für die Zahlungsabwicklung finden (nach dem Parsen der Sepay-Payload + Validierung transferType === 'in'). Hinzufügen:

// app/api/payment-success/route.ts (oder ähnlich)
import { sendTelegramNotification } from '@/lib/telegram';
import { sendCustomerEmail, sendOwnerEmail } from '@/lib/resend'; // falls vorhanden

export async function POST(req: Request) {
  const payload = await req.json();

  // [Vorhanden] Sepay-Authentifizierung validieren + Payload parsen
  if (payload.transferType !== 'in') {
    return Response.json({ success: true }); // ausgehende Überweisung ignorieren
  }

  // [Vorhanden] Lead anhand des Inhalts (enthält Bestell-ID) oder referenceCode suchen
  const lead = await lookupLeadByTransferContent(payload.content);

  // [NEU] 3 Seiteneffekte parallel ausführen — Telegram-Fehler blockiert E-Mail nicht
  await Promise.allSettled([
    sendCustomerEmail(lead),
    sendOwnerEmail(lead),
    sendTelegramNotification({
      name: lead.name,
      phone: lead.phone,
      email: lead.email,
      amount: payload.transferAmount,
      productName: lead.productName,
      referenceCode: payload.referenceCode,
    }),
  ]);

  return Response.json({ success: true });
}

Grund für die Verwendung von Promise.allSettled anstelle von Promise.all:

  • Promise.all lehnt ab, wenn IRGENDEIN Promise fehlschlägt → der Handler wirft einen Fehler → Sepay erhält 500 → Wiederholung → doppelte E-Mail.
  • Promise.allSettled wartet, bis alle Promises abgeschlossen sind (egal ob aufgelöst oder abgelehnt), ohne einen Fehler zu werfen. So kann Telegram fehlschlagen, ohne die 200er-Antwort an Sepay zu blockieren.

3.3 Umgebungsvariablen aktualisieren

# .env.local
# --- ZU HINZUFÜGEN ---
TELEGRAM_BOT_TOKEN=dein_bot_token_hier
TELEGRAM_CHAT_ID=deine_chat_id_hier
# --- ENDE ---

# Bestehende Variablen bleiben erhalten
SEPAY_API_KEY=
RESEND_API_KEY=
KV_REST_API_URL=
KV_REST_API_TOKEN=

.gitignore aktualisieren (bestätigen, dass .env.local bereits vorhanden ist; falls nicht, hinzufügen).

Benutzer daran erinnern, die Werte aus Schritt 1 einzufügen und die Umgebungsvariablen auf der Produktionsplattform (Vercel/Netlify) zu konfigurieren.


Phase 4 — Testplan

Stufe 1: Direkter Telegram-Bot-Test

# Testen Sie den Bot direkt mit dem Token (unabhängig von der App)
curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "<CHAT_ID>",
    "text": "🧪 Testbenachrichtigung von Ihrem Next.js-Skill",
    "parse_mode": "HTML"
  }'

Erwartet: Nachricht in Telegram-Chat erhalten. Wenn nicht → Token/Chat-ID prüfen, ob der Benutzer den Bot gestartet hat.

Stufe 2: Simulierte Sepay-Payload

# Sepay-Webhook-Payload simulieren
curl -X POST http://localhost:3000/api/payment-success \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "referenceCode": "TEST_REF",
    "transferAmount": 499000,
    "transferType": "in",
    "content": "DH001 0901234567"
  }'

Erwartet:

  • 200 OK Antwort
  • Telegram-Nachricht empfangen (korrektes Format)
  • Resend-E-Mail gesendet (falls konfiguriert)
  • Keine Fehler in der Serverkonsole (außer möglicher Telegram-Warnungen)

Stufe 3: Produktionsüberprüfung

# Echte Zahlung tätigen (oder Sepay-Dashboard verwenden, um eine Testzahlung zu simulieren)
# Überprüfung:
# 1. Telegram-Benachrichtigung innerhalb von 3 Sekunden nach Zahlungseingang
# 2. Informationen korrekt (Name, Telefon, Betrag, Produkt)
# 3. Sepay erhält 200 (keine Wiederholungen)
# 4. Vorhandener E-Mail-Flow funktioniert weiterhin
# 5. Prüfen, ob keine doppelten Nachrichten gesendet werden

Fehlerbehebung

ProblemUrsacheLösung
Keine Telegram-BenachrichtigungFalscher Token/Chat-IDsendMessage API direkt mit curl testen (Stufe 1)
Doppelte BenachrichtigungenSepay wiederholt aufgrund von non-200Prüfen, ob Promise.allSettled verwendet wird KEIN Promise.all
Telegram sagt "chat not found"Bot wurde vom Benutzer nicht gestartetBenutzer muss /start in 1-zu-1 Chat oder Bot zur Gruppe hinzufügen
Fehler „Cannot find module '@/lib/telegram'"Pfad falschRelativen Pfad prüfen, ggf. zu ../../lib/telegram korrigieren
Keine E-Mail gesendetResend-KonfigurationsproblemDie E-Mail-Pipeline im Log prüfen (nicht Teil dieses Skills)

Dateien, die dieses Skill erstellt/ändert

DateiAktionBeschreibung
lib/telegram.tsERSTELLTHilfsfunktion zum Senden von Telegram-Benachrichtigungen
app/api/payment-success/route.ts (oder ähnlich)GEÄNDERTsendTelegramNotification parallel zu E-Mails eingebunden
.env.localGEÄNDERTTELEGRAM_BOT_TOKEN und TELEGRAM_CHAT_ID hinzugefügt

Ausgelagerte Kompetenzen

BereichGrund
Sepay-Webhook-Setup von Grund aufDieses Skill bindet nur in vorhandene Webhooks ein, es erstellt keine neuen
Lead-Speicher-Einrichtung (Vercel KV)Separates Skill /biz-setup-sepay-payment oder Raw-Mode verwenden
E-Mail-VorlagenanpassungVorhandener Resend-Flow bleibt unverändert
Zahlungs-DeduplizierungAnliegen der Zahlungslogik, nicht Teil von Telegram-Benachrichtigungen

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Best practices for Remotion - Video creation in React

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Scaffold trang `/admin` CRM-style trực quan vào Next.js project (Supabase backend) — KHÔNG còn variant Vercel KV. Layout 1CRM-inspired: sidebar 3 tab (Tổng quan / Khách hàng / Email marketing) + popup nhập mã đăng nhập. **Tab Tổng quan**: 4 KPI cards (Tổng leads / Đã thanh toán / Tỷ lệ chuyển đổi / Doanh thu) có delta arrow vs kỳ trước, line chart leads+paid+revenue theo ngày dùng `recharts`, donut trạng thái paid/pending/expired, period selector pill 7d/30d/90d, list 5 thanh toán gần nhất. **Tab Khách hàng**: bảng leads + search + filter trạng thái + filter ngày + CSV export. **Tab Email marketing**: form soạn chiến dịch (tên + tiêu đề + body chọn định dạng **văn bản thường HOẶC HTML** + placeholder `{{name}}` + audience 4 loại all/paid/pending/last_days + tên người gửi) — có nút **Xem trước** mở modal iframe render đúng email thật (text → auto convert + wrap khung; HTML fragment → wrap khung, HTML đầy đủ giữ nguyên) → gửi bulk qua SMTP (reuse `nodemailer` của `biz-email-setup` — KHÔN

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Deploy landing page / website (React, Next.js, Vite, static HTML) lên Vercel — tự kiểm tra Vercel CLI hoặc Vercel MCP đã cài chưa, nếu chưa thì cài qua npm/pnpm và hướng dẫn user authenticate (vercel login), tự detect framework (Next.js / Vite / CRA / static), auto-generate vercel.json khi cần, chạy `vercel --prod`, trả về live URL + inspect URL + hướng dẫn custom domain. USE WHEN user says 'deploy lên vercel', 'đẩy landing page lên vercel', 'publish website', 'go live', 'deploy nextjs', 'deploy react', 'deploy vite', 'tạo URL live', 'đưa lên production', 'biz-deploy-vercel', 'host landing page', 'vercel deploy', 'ship lên vercel', 'đẩy code lên vercel'. Skill này áp dụng cho cả case dùng Vercel CLI lẫn Vercel MCP server.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Setup SMTP-based email auto-responder cho landing page bán hàng — tự động gửi email sau khi user điền form (tên/SĐT/email), KHÔNG cố định vào provider nào. Skill này (1) hỏi user chọn SMTP provider (Gmail/Google Workspace, Resend SMTP, SendGrid, Mailgun, Brevo, Zoho, hoặc SMTP custom của hosting VN) và detect Next.js stack đang dùng, (2) đọc context từ `offer.json` + `conversion-copy.md` (từ `/biz-offer-alex-hormozi`) HOẶC đọc trực tiếp Next.js project đã build qua `ui-ux-pro-max` (file `app/page.tsx`) HOẶC đọc HTML landing page đã deploy để hiểu offer, dream outcome, mechanism, bonus. Lưu ý: skill `biz-sales-page-layout` đã DEPRECATED 2026-05-14 — pipeline mới skip layout/copy.json, (3) **draft 2 email**: email A — auto-responder gửi cho lead (warm welcome + deliver lead magnet/booking confirm/payment link tuỳ offer type), email B — notification gửi cho owner (lead alert + thông tin liên hệ), (4) **show draft cho user duyệt và chỉnh sửa** trước khi wire vào code, (5) cài `nodemailer`

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Cài chatbot AI dạng floating widget góc dưới phải vào project Next.js có sẵn (App Router hoặc Pages Router), responsive đầy đủ web + tablet + mobile, gọi LLM qua OpenRouter (mặc định google/gemini-3-flash-preview, có thể đổi sang anthropic/claude-sonnet-4.6), streaming response, RENDER MARKDOWN trong assistant bubble (bold / list / link / code) qua react-markdown + remark-gfm — KHÔNG hiện raw **bold** dạng text — có knowledge base từ FAQ + tài liệu sản phẩm/khóa học do user cung cấp để chatbot tự động trả lời khách hàng, và TỰ ĐỘNG EXTRACT + LƯU LEAD (tên + SĐT + email) vào Upstash Redis/Vercel KV dưới namespace `chat-lead:{phone}` khi user cung cấp đầy đủ thông tin trong chat — dedupe theo SĐT, TTL 90 ngày, fire-and-forget không block stream. Skill tự detect số lượng project Next.js — nếu có nhiều hơn 1 sẽ hỏi user chọn project nào để cài; tự detect TypeScript/JS, App Router/Pages Router, Tailwind/CSS module, KV/Upstash availability (skip auto-save nếu chưa có); tự install react-markd

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Đóng gói offer **không thể chối từ** (grand slam offer) theo phương pháp Alex Hormozi ($100M Offers) — nhận input pains/gains/customer jobs theo Value Proposition Design (Osterwalder 2014) + sản phẩm/dịch vụ, rồi sinh ra: (1) markdown report tiếng Việt đầy đủ Value Equation scoring + Core Offer + 3-4 Bonus stack + Guarantee + Urgency + Pricing, (2) offer.json structured cho pipeline downstream (`ui-ux-pro-max` build sales page production-ready), (3) conversion copy block (headline + subheadline + CTA) sẵn sàng paste landing page. 2 input mode: (B) user paste sẵn pains + gains + product, (C) user chỉ có sản phẩm — skill phỏng vấn theo VPD framework để surface pain/gain trước. Bonus stack mode hybrid: skill brainstorm 5-7 candidate có justification value rồi user pick/chỉnh 3-4 cái. Tiếng Việt thuần (xưng anh/chị), giá VND charm pricing (X99K), 3-tier decoy structure. USE WHEN user says 'đóng gói offer', 'tạo offer', 'thiết kế offer Hormozi', 'grand slam offer', 'value stack', 'offer sta

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Nâng cấp copy sales page tiếng Việt — biến copy có sẵn (từ `offer.json` + `conversion-copy.md` của `/biz-offer-alex-hormozi`, HOẶC từ Next.js project đã build qua `ui-ux-pro-max`, HOẶC user paste block copy bất kỳ) thành **copy chất lượng cao chốt đơn**: headline punchy hơn, pain agitation đau hơn, mechanism rõ hơn, benefit cụ thể hơn, FAQ xử lý đúng objection của thị trường VN, CTA mạnh hơn. Skill này có 3 INTENSITY LEVEL: (1) **Polish** — light edit + power word + sửa nhịp; (2) **Conversion-optimized** — rewrite 5 block critical + tạo A/B variants cho hero/CTA; (3) **Sales-letter** — long-form story-driven full rewrite kèm P.S.. Mỗi section áp dụng đúng formula thuyết phục (PAR cho pain, BAB cho solution, FEP cho benefit, PVEN cho final CTA, Star-Chain-Hook cho testimonial). Output gồm 4 file: `copy-upgraded.md`, `copy-variants.md` (A/B test bank — 3 hero + 3 CTA + 3 final-CTA), `copy-changes.md` (diff Trước/Sau + lý do), `copy.json` (structured downstream). Giọng văn tiếng Việt thuầ

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

⚠️ DEPRECATED (2026-05-14) — Skill này KHÔNG còn trong pipeline chuẩn. Quy trình mới đã bỏ bước wireframe markdown trung gian: sau `/biz-offer-alex-hormozi` đi THẲNG sang `ui-ux-pro-max` để build Next.js sales page production-ready (có design language nhất quán: style + palette + font pairing, không phải Tailwind defaults). Lý do deprecate: wireframe markdown làm thêm 1 bước trung gian không tạo giá trị — `ui-ux-pro-max` đọc trực tiếp `offer.json` đã đầy đủ anchor + core + bonus + guarantee + urgency + pricing rồi ra HTML production luôn. Chỉ dùng skill này KHI user EXPLICITLY yêu cầu wireframe markdown để review/in/share trước khi build code (rare case). KHÔNG trigger trên các keyword 'tạo sales page', 'tạo landing page bán hàng' nữa — những keyword đó giờ trigger `ui-ux-pro-max`.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

End-to-end Sepay VietQR payment infrastructure cho landing page Next.js — guide user setup Sepay account + bank linking + scaffold đầy đủ payment flow trong project. Skill này xử lý 7 phase: (0) detect Next.js stack + **HỎI user chọn lead store backend** (Vercel KV hoặc Supabase Free Postgres — default recommend Supabase do free tier rộng hơn ~50× + có SQL + admin UI), (1) GUIDE user đăng ký Sepay account tại my.sepay.vn + link bank account VN (Vietcombank/Techcombank/MB/ACB/VPBank/BIDV/...) + lấy API key + setup webhook URL trên Sepay dashboard, (2A nếu chọn KV) setup Vercel KV (install `@vercel/kv` + KV namespace + 4 env vars KV_*), (2B nếu chọn Supabase) setup Supabase project (tạo project tại Singapore region + chạy migration SQL tạo 4 bảng leads/phone_index/order_counter/webhook_dedup với pg_cron TTL cleanup + RLS deny-all + lấy SUPABASE_URL + SUPABASE_SERVICE_ROLE_KEY + Vercel Cron ping `/api/health` mỗi 6 ngày chống auto-pause), (3) scaffold `lib/leads-store.ts` (thin re-export

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Convert a single MP3 voiceover file into a single HeyGen avatar lip-sync MP4 video. Single-purpose — no planning, no SRT, no chunking, no Remotion compositing. Hybrid path — REST upload (helper script) + HeyGen MCP for video creation, because the post-2026 MCP no longer exposes an asset-upload tool. Reads avatar look pool (`HEYGEN_AVATAR_LOOKS`) from `.env` and HeyGen API key (`HEYGEN_API_KEY`) for the upload step. USE WHEN user says "tạo video heygen từ mp3", "mp3 to heygen", "heygen mp4 từ audio", "convert mp3 sang heygen video", "tạo avatar video từ file mp3", "lip sync mp3 heygen", "biến mp3 thành video heygen", or any time the user has exactly one MP3 file and wants exactly one HeyGen avatar MP4 out.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Demand-side market research cho digital product / service ở Việt Nam — đo cầu thật + WTP + channel-market fit + defensibility qua keyword volume, marketplace sales (Shopee/Unica/Edumall/Gitiho/KyNa), community signal (FB groups, TikTok hashtag, Zalo OA), competitor pricing, unit economics — không phải macro PESTEL. Output: keyword portfolio + Niche Score 100 điểm 7-dimension có evidence + go/no-go decision + falsification protocol. Force triangulate ≥3 sources cho mỗi claim quan trọng. USE WHEN user says 'nghiên cứu thị trường', 'market research', 'validate niche', 'keyword research', 'demand validation', 'niche có nên làm không', 'có ai làm chưa', 'thị trường đủ lớn không', 'có lời không', 'chọn ngách', 'kiểm tra cầu'. Cũng trigger khi user mô tả 1 ý tưởng kinh doanh cụ thể và muốn check feasibility. Skill này KHÔNG fit: high-ticket transactional sale (BĐS, ô tô), B2B enterprise (sales cycle 6+ tháng), hyper-local geo micro-market (1 toà nhà, 1 phường). KHÔNG làm: macro PESTEL/Porter

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Transcribe an MP3 voiceover into an SRT subtitle file and a word-level segments JSON using local OpenAI Whisper. Input is a single MP3 path; output is `<stem>.srt` + `<stem>_segments.json` written next to the MP3 (or to a custom output dir). USE WHEN the user says 'extract srt from mp3', 'trích srt từ mp3', 'transcribe voiceover', 'tạo file srt và segments', 'whisper transcribe', 'bóc transcript có timestamp', 'extract voiceover segments', 'tách SRT từ audio', or any time a downstream skill (plan-short-video-edit, heygen-remotion-short-video-editor) needs an SRT + word-level segments JSON from a voiceover MP3 and one does not already exist.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Convert Vietnamese/English script text to MP3 voiceover using ElevenLabs TTS API. Calls POST /v1/text-to-speech/{voice_id}, streams audio bytes, writes MP3 directly. Locked to Hoang's brand voice ID by default. USE WHEN user says 'tạo mp3 elevenlabs', 'elevenlabs tts', 'eleven labs voice', 'text to speech elevenlabs', 'tạo voiceover elevenlabs', 'đọc text bằng elevenlabs', 'tts elevenlabs to mp3', 'eleven labs script to mp3', 'voiceover bằng elevenlabs', 'giọng elevenlabs'.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

End-to-end orchestrator: **script → final MP4 16:9 (1920×1080) podcast-keynote**.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

End-to-end short-video pipeline — từ kịch bản (Việt/Anh) ra MP4 TikTok/Reels 9:16 hoàn chỉnh. Orchestrator 3 phase ghép skill có sẵn — (1) TTS provider chọn được giữa `mkt-elevenlabs-tts-to-mp3` (default, voice của Hoàng) hoặc `mkt-video-script-to-mp3` (MiniMax speech-2.8-hd), (2) checkpoint user duyệt MP3, (3) `heygen-mp3-to-mp4` lip-sync avatar HeyGen, (4) delegate Phase 3 packaging cho sub-agent `mkt-full-video-phase3-packager` (transcribe + scene outline + checkpoint + fan-out N scene writers parallel + scaffold + preview Studio). API key + voice ID cho cả 2 provider lưu ở `.env`. USE WHEN user nói "tạo full video từ script", "script to tiktok video", "pipeline full video heygen + hyperframe", "tạo video từ kịch bản đến mp4", "elevenlabs heygen hyperframe full pipeline", "minimax heygen pipeline", "kịch bản ra video tiktok", hoặc có sẵn 1 script + (optional) ảnh b-roll và muốn ra MP4 9:16 đóng gói có captions, SFX, b-roll.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Build a TikTok/Reels/YouTube **landscape 16:9 (1920×1080)** short video from a pre-recorded talking-head MP4 using HyperFrames — transcribe Vietnamese audio, scaffold a complete preview-ready 1920×1080 project with a slide pane (1200px) on the left and a floating avatar frame on the right, GSAP timeline có SPLIT↔PIP transitions (slide full-screen + avatar PIP corner thumbnail), breathing yoyo zoom + beat-driven punch-in trên avatar, 5 scene compositions kiểu "tier-row" pattern (post-stack hook / chats-stack problem / hero-orb solution / counter-row recap / terminal-row CTA), optional cream-paper editorial infographic image slots với `<img onerror>` fallback, 6 SFX wired tại scene boundaries, **NO captions** (giọng avatar là spine). USE WHEN user nói "edit video 16:9 từ HeyGen MP4", "scaffold project landscape", "podcast keynote editor", "talking head + slide editor", "build hyperframes 1920×1080", "tạo project 16:9 từ avatar mp4", "scaffold 16:9 hyperframes", "hyperframe landscape vide

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Pipeline đóng gói: từ MP4 quay sẵn (talking head 9:16) tới HyperFrames preview project hoàn chỉnh có captions, SFX, zoom hooks, b-roll toàn cảnh có hiệu ứng rich, và CTA finale.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Audit bài Facebook / Reels / YouTube để phát hiện 4 downward drivers (over-branding, over-production, stock imagery, standardized aesthetic) + frequency-over-quality. Mỗi anti-pattern bị drop ~75% performance nếu hiện diện. USE WHEN user says 'audit content', 'check anti pattern', 'content có lỗi gì không', 'kiểm tra over branding', 'vì sao video bị chết', 'vì sao post không ai xem', 'content audit', 'kiểm tra chất lượng content'.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Tìm viral pattern ở ngành khác (bác sĩ, luật sư, tài chính, bất động sản, thủ công) có thể apply cho niche AI/automation của Hoang. Ngách AI educator VN còn ít format được khai thác — cross-industry adaptation là blue ocean. USE WHEN user says 'tìm format ngành khác', 'cross industry research', 'học format từ ngành khác', 'blue ocean format', 'tìm format chưa ai làm', 'adapt format từ niche khác', 'cross industry viral'.

lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

Rewrite CTA kiểu autocratic (Mua ngay! Follow ngay! Đăng ký liền!) sang 3 variants Democratic / Benevolent / Laissez-faire — reach 85% dân số thay vì chỉ 5% (action-based). Áp dụng cho landing page, caption FB, CTA video, email. USE WHEN user says 'rewrite cta', 'sửa cta', 'cta không autocratic', 'viết lại kêu gọi hành động', 'cta cho landing page', 'cta nhẹ nhàng hơn', 'inclusive cta', 'cta democratic benevolent'.

Verwandte Skills