Upomínky

Přehled

Upomínkový engine automaticky posílá e-maily klientům, kteří svůj sběr podkladů nedokončili. Rytmus nastavíte při volání define_intake a od té chvíle se BriefGate stará o načasování, odstranění duplicit i noční klid. Agent nemusí hlídat e-mailová vlákna ani si pamatovat, že se má připomenout.

Jakmile klient odešle všechny povinné položky, upomínky se samy zastaví.

Rozvrhy

Rozvrh nastavíte při zakládání sběru podkladů:

{
  "project_name": "Bella Cucina Website",
  "client": {"email": "owner@bellacucina.cz"},
  "items": [...],
  "chase_schedule": "default"
}

Rytmus jde po odeslání sběru podkladů změnit — viz Pozdější změna rozvrhu.

Tarify Solo, Studio a Agency mají k dispozici všechny rozvrhy. Tarif Free jen default a off.

Vlastní interval

Když se žádný přednastavený rozvrh nehodí, nastavte chase_schedule na custom a zadejte interval jako číslo plus jednotku:

{
  "project_name": "Bella Cucina Website",
  "client": {"email": "owner@bellacucina.cz"},
  "items": [...],
  "chase_schedule": "custom",
  "chase_interval": 5,
  "chase_interval_unit": "minutes"
}

chase_interval_unit je jedna z hodnot minutes, hours, days; výchozí jsou days. První upomínka dorazí jeden interval po pozvánce a další pak po každém dalším intervalu — 5 days dá za 5, 10 a 15 dní a tak dál.

Meze: nejméně 5 minut, nejvíc 90 dní. Cokoli kratšího než pět minut naráží na limity poštovních providerů a příjemci to připadá jako spam, takže to API odmítne.

Obě pole jsou nepovinná. Samotné chase_schedule: "custom" upomíná každé 3 dny. Poslat kterékoli z nich spolu s přednastaveným rozvrhem skončí chybou 422 — přednastavené rozvrhy mají pevný rytmus a tiché ignorování pole by vás nechalo v domnění, že jste ho změnili.

Na rozdíl od gentle vlastní rytmus víkendy nevynechává.

Pevná denní hodina

Rytmus měřený v celých dnech se dá přišpendlit na místní čas, místo aby se odvíjel od toho, kdy zrovna odešla pozvánka:

{
  "chase_schedule": "custom",
  "chase_interval": 1,
  "chase_interval_unit": "days",
  "chase_at_time": "07:00"
}

Tohle klienta upomene každé ráno v 7:00 v jeho pásmu client.timezone, včetně přechodu na letní čas.

• Hodnota je místní čas ve 24hodinovém formátu HH:MM.
• Vyžaduje interval v celých dnech. Rytmus kratší než den nemůže zároveň mířit na jednu pevnou hodinu, takže API takovou kombinaci odmítne chybou 422.
• Přebíjí noční klid. Když řeknete 7:00, platí 7:00 — upomínka se neodsune na 8:00 jen proto, že se tehdy otevírá výchozí okno.
• Jako každé odeslání nese pár sekund rozptylu, aby vám celá flotila sběrů podkladů nebouchla na poštovní server ve stejnou vteřinu.

Strop upomínek

Sběr podkladů přestane upomínat po max_reminders upomínkách (výchozí 3), označí se jako zaseknutý a spustí webhook intake.stalled, abyste mohli zasáhnout. Rychlý rytmus by tři pokusy spálil během pár minut, takže při zkrácení intervalu strop zvedněte:

{
  "chase_schedule": "custom",
  "chase_interval": 30,
  "chase_interval_unit": "minutes",
  "max_reminders": 12
}

Maximum je 1000. Hodnota "max_reminders": "unlimited" strop úplně zruší — vyplatí se to jen u opravdu otevřeného upomínání, protože sběr podkladů ignorovaný stokrát další e-mail nezachrání a za každý z nich platí reputace vaší odesílací domény.

Pozdější změna rozvrhu

PATCH /v1/intakes/:id umí změnit chase_schedule, chase_interval, chase_interval_unit, chase_at_time, max_reminders a respect_quiet_hours i poté, co byl sběr podkladů už odeslán — nemusíte ho mazat a zakládat znovu, což by klientovi poslalo novou pozvánku a druhý odkaz.

{
  "chase_schedule": "custom",
  "chase_interval": 6,
  "chase_interval_unit": "hours",
  "max_reminders": 12
}

Změna kteréhokoli z těchto polí — nebo client.timezone či due_date, ze kterých výpočet rytmu vychází — zruší všechny upomínky, které ještě čekají ve stavu scheduled, a naplánuje je znovu podle nového nastavení. Upomínky, které už odešly, se tím nevrací zpět a pořád se počítají do max_reminders: snížení stropu po třech z pěti odeslaných upomínek nechá dva pokusy, ne pět.

Pokud je sběr podkladů už zaseknutý (viz Strop upomínek výše), samotná změna rytmu upomínání neobnoví — zaseknutý sběr podkladů zůstane zaseknutý, dokud max_reminders nezvýšíte nad počet už odeslaných upomínek, nebo ho nenastavíte na "unlimited". To je zároveň způsob, jak se ze zaseknutí dostat: sběr podkladů zaseknutý při max_reminders: 3 se znovu rozjede, jakmile ho PATCHnete na 5 nebo "unlimited".

Noční klid

Upomínkový engine respektuje pracovní dobu klienta, aby neposílal ve nevhodnou hodinu.

• Upomínky se zadrží, pokud je u klienta místní čas mimo 8:00–19:00.
• Nastavením respect_quiet_hours: false u sběru podkladů budete posílat nepřetržitě. Dává to smysl u záměrně rychlého rytmu, který by jinak přes noc stál.
• Se zapnutým nočním klidem počítá rytmus kratší než den jen čas, kdy je okno otevřené: třicetiminutový interval, který vyprší v 18:50, pokračuje druhý den v 8:05 — místo aby všechny zameškané upomínky spadly na 8:00 najednou.
• Časové pásmo klienta se nastavuje přes client.timezone v define_intake (například "Europe/Prague"). Bez nastavení se použije UTC.
• Rozvrh gentle o víkendech neposílá nikdy.
• Všechny ostatní rozvrhy včetně vlastních posílají i o víkendu.

Když naplánované odeslání spadne do tichého okna, zadrží se do nejbližšího povoleného času — nezruší se.

Co je v upomínkovém e-mailu

Každá upomínka je ušitá na to, co ještě chybí:

• Jen položky, které klient dosud neodeslal (ne ty hotové)
• Shrnutí postupu („zbývají 3 z 8 položek, přibližně 6 minut“)
• Přímý odkaz do portálu (jediný stálý magic link sběru podkladů, jehož platnost tohle odeslání prodlouží — bez přihlašování)
• Vaše jméno a váš branding — v placených tarifech zmizí patička „Powered by BriefGate“

E-mail je psaný z vaší perspektivy, ne z perspektivy BriefGate. Klient vidí profesionální připomenutí od vás, ne od nástroje třetí strany.

Na sdílené odesílací doméně pole Od pořád ukazuje „Vaše jméno via BriefGate“ — platí to na každém tarifu, placené nevyjímaje. Jediný způsob, jak „BriefGate“ z pole Od úplně dostat, je tarif Studio nebo Agency s ověřenou vlastní odesílací doménou (níž).

Vlastní doména pro odesílání (Studio a Agency)

V tarifu Studio nebo Agency si nastavíte vlastní odesílací doménu (třeba intake@vasefirma.cz), takže klient uvidí v poli Od vaši doménu a jen vaše jméno, bez „via BriefGate“. Stránka nastavení účtu ukáže DNS záznamy k přidání a sama je ověřuje. Kompletní návod je v kapitole Vlastní domény.

Dokud vlastní doména nastavená není, odesílá se z intake@briefgate.dev, s vaším jménem před ní („Vaše jméno via BriefGate“).

Ruční upomínka

Odeslat upomínku okamžitě mimo rozvrh:

Přes MCP:

send_chase(intake_id: "int_01J3K...", channel: "email")

Přes REST:

POST /v1/intakes/:id/chase

{
  "channel": "email"
}

channel má výchozí hodnotu email; na tarifech se zapnutým SMS jde poslat i sms.

Rozvrh se tím neresetuje — naplánované upomínky pokračují po té ruční podle plánu. Počítá se ale do max_reminders: ruční odeslání je jedna z upomínek, která může naplnit strop a sběr podkladů zaseknout, stejně jako ta naplánovaná.

Ruční upomínka má rate limit: nejvýš 1 za hodinu na sběr podkladů a 20 za hodinu na účet.

Průběh eskalace

Když doručování e-mailů opakovaně selhává, dá to engine agentovi vědět:

1. E-mail klienta se natvrdo odrazí (nebo se opakovaně odráží dočasně bez jediného doručení) → spustí se webhook chase.bounced a BriefGate na tu adresu přestane posílat
2. Sběr podkladů vyčerpá povolený počet upomínek, aniž by byl dokončen → spustí se webhook intake.stalled se seznamem missing_items
3. Agent dostane intake.stalled a může eskalovat jinak (upozornit člověka, změnit stav projektu a podobně)

Pole missing_items v intake.stalled přesně říká, které položky ještě chybí, takže to můžete předat tomu, kdo eskalaci řeší.

Víc lidí na straně klienta

Některé podklady patří firmě, ne jednomu člověku, a poslat je může kterýkoli ze dvou jednatelů. Sběr podkladů proto může být adresovaný až pěti lidem, kteří sdílejí jeden portálový odkaz:

{
  "client": {
    "email": "prvni@bellacucina.cz",
    "name": "Marek",
    "also_notify": [{ "email": "druha@bellacucina.cz", "name": "Jana" }]
  }
}

Pozvánku, každou upomínku i stejný odkaz dostanou všichni ze seznamu. Kdo ho otevře první, může dodat všechno; ostatní pak vidí, co je hotové, místo aby je to žádalo znovu.

Každý dostane vlastní zprávu. Adresa jednoho se neobjeví v kopii druhého, každý je osloven svým jménem a každá adresa má vlastní stav doručování — mrtvá adresa tedy zastaví poštu jen tomu člověku a nikomu jinému.

Přidat nebo odebrat někoho později jde přes POST /v1/intakes/:id/recipients a DELETE /v1/intakes/:id/recipients/:email. Přidání samo o sobě nic neodešle: nový člověk se zahrne od příští upomínky, nebo mu jednu pošlete hned přes send_chase. Hlavního klienta takhle odebrat nejde — je to adresa, pro kterou sběr podkladů vznikl.

Zpracování odrazů

Ne každý odraz znamená mrtvou adresu, proto se BriefGate nejdřív podívá, co přesně poskytovatel e-mailu nahlásil:

Případ „odraz po doručení" je běžný a snadno se špatně vyloží: server klienta zprávu přijme a pravidlo pro přeposílání nebo karanténní brána za ním pošle o pár sekund později hlášení o selhání doručení. Ten člověk přitom e-mail ve schránce má. Kdyby se to bralo jako mrtvá adresa, potichu by se zrušily všechny upomínky u sběru podkladů.

Kdykoli se adresa vyřadí, BriefGate:

1. Spustí webhook chase.bounced
2. Označí tuhle adresu u tohohle sběru podkladů jako odraženou
3. Zastaví všechny další upomínkové e-maily na tuto adresu (kvůli ochraně reputace odesílatele)

Zastaví se jen ta jedna adresa. U sběru podkladů adresovaného víc lidem se ostatním upomíná dál — v obsahu webhooku najdete recipient a still_chasing, takže poznáte, který z těch dvou případů nastal. Webhook se spustí i u odrazu, který adresu nevyřadil (still_chasing: true, navíc bounce_type a delivered_before), takže zlobící schránku uvidíte dřív, než z ní bude mrtvá.

Odraženou hlavní adresu už u existujícího sběru podkladů opravit nelze — endpoint na změnu client.email po založení neexistuje. Buď přidejte funkční adresu přes POST /v1/intakes/:id/recipients, nebo založte nový sběr podkladů na položky, které vám stále dluží, a ten starý nechte zarchivovat.

Jazyk

Každý e-mail je psaný v jazyce klienta, který se vybírá v tomto pořadí:

1. client.language na sběru podkladů
2. default_language na účtu (PATCH /v1/account)
3. angličtina

Podporované: cs, sk, pl, de, es, en. Řídí se tím předmět, tělo, tlačítko i formát data — včetně skloňování počtu, které se liší i mezi jazyky, co vypadají podobně. Polština bere 22 jako „few“ a 25 jako „many“, čeština obojí jako „many“.

Vlastní předmět a úvodní text

email_copy nahradí vestavěné texty, buď na účtu (jako výchozí), nebo u jednotlivého sběru podkladů (kde je pole po poli přebije). invite_subject/invite_intro upraví první pozvánku; reminder_subject/reminder_intro upraví samotné upomínkové e-maily — pokud chcete změnit upomínky, nastavte tuhle druhou dvojici:

{
  "email_copy": {
    "invite_subject": "{sender} potřebuje {count} podkladů k projektu {project}",
    "invite_intro": "Dobrý den, {client}. Pro {project} potřebujeme ještě pár věcí — zabere to zhruba {minutes} minut.",
    "reminder_subject": "Upomínka: {sender} pořád potřebuje {count} podkladů k projektu {project}",
    "reminder_intro": "Dobrý den, {client}. Jen připomínáme — {project} pořád čeká na pár věcí (zabere to zhruba {minutes} minut)."
  }
}

Zástupné symboly: {sender}, {project}, {client}, {count}, {minutes}, {due}. Cokoli jiného se odmítne chybou 422 místo doslovného vypsání — překlep typu {prjoekt} v e-mailu si nikdo nevšimne dřív, než ho klient přečte.

Rozvržení, tlačítko i patička zůstávají beze změny. Hodnoty se escapují všude, kde text končí uvnitř HTML, takže název projektu nemůže do e-mailu propašovat značky.