Telegram doručování nahrávek hovorů

Cílem je rozšířit současný systém doručování nahrávek hovorů o doručování přes Telegram.

Současná politika doručování zůstává zachovaná: zákazník si v nastavení určuje cíle doručení a systém po dokončeném doručení nahrávku smaže podle pravidel rozesílacího skriptu.

Telegram nebude fungovat jako e-mailová adresa. Zákazník si musí Telegram cíl nejdříve jednorázově spárovat přes našeho Telegram bota. Výsledkem spárování bude uložené Telegram chat_id v databázi.

Do stávajícího pole pro doručování nahrávek se potom bude moci přidat interní URI ve tvaru tel://300169.

Číslo 300169 znamená linku, u které byl Telegram cíl vytvořen. Toto URI není veřejná Telegram adresa, ale interní odkaz na uložený Telegram cíl zákazníka.

Příklad použití:

• zákazník vytvoří Telegram cíl u linky 300169
• systém uloží chat_id získané od Telegramu
• u jiné linky stejného zákazníka lze použít tel://300169
• rozesílací skript podle tel://300169 najde uložený chat_id
• nahrávka se odešle do daného Telegram chatu nebo skupiny

Telegram cíl může být soukromý chat nebo skupina. Zákazník si při párování zvolí, kam bota připojí. Rozesílací skript později už nemusí řešit, zda jde o soukromý chat nebo skupinu, protože používá pouze uložený chat_id.

Je potřeba vytvořit samostatného Telegram bota pro doručování nahrávek hovorů zákazníkům.

Navržený název bota: @OdorikCallRecordingsBot

Bot má sloužit pouze pro zákaznické doručování nahrávek. Neměl by být míchán s interními monitoring boty ani s jinými účely.

Bot bude používaný pro dvě věci:

• spárování Telegram chatu nebo skupiny se zákaznickou linkou
• pozdější odesílání nahrávek do uloženého chat_id

Token bota musí být uložen bezpečně a nesmí se zapisovat do běžných logů.

future code

Do současného systému doručování se přidá nový typ cíle: tel://300169.

Význam:

• tel:// znamená interní Telegram transport
• 300169 je linka, u které byl Telegram cíl vytvořen
• tel://300169 není veřejná Telegram adresa
• tel://300169 je interní alias na uložený Telegram chat_id

Vyhledávání tel://300169 musí být omezené na stejného zákazníka. Nesmí se hledat globálně jen podle čísla linky.

Praktický příklad:

• linka 300169 vytvoří Telegram cíl
• linka 405277 může používat tel://300169
• nahrávka z linky 405277 se odešle do Telegram cíle vytvořeného u linky 300169

Tím zákazník nemusí párovat stejný Telegram chat znovu pro každou svoji linku.

future code

Web při kliknutí na připojení Telegramu vygeneruje jednorázový párovací token.

Token bude použit v odkazu na Telegram bota a bude určovat, ke kterému zákazníkovi a ke které lince se má příchozí Telegram chat_id uložit.

Tabulka má sloužit pouze pro dočasné párování.

Potřebné údaje:

• token
• customer_id
• owner_line
• požadovaný typ cíle private nebo group
• čas vytvoření
• čas expirace
• čas použití
• použité chat_id
• použité user_id

Požadavky na token:

• musí být jednorázový
• musí časově expirovat
• musí být vázaný na konkrétního zákazníka
• musí být vázaný na konkrétní linku
• po úspěšném použití se nesmí dát použít znovu

Token nesmí být trvalý identifikátor Telegram cíle.

future code

Telegram cíl má být samostatný doručovací cíl zákazníka.

Nemá jít jen o přímou vazbu linka → chat_id, protože jeden Telegram cíl může zákazník chtít použít u více svých linek.

Telegram cíl se vytvoří u konkrétní linky. Tato linka potom slouží jako alias pro použití v URI tel://.

Potřebné údaje:

• customer_id
• owner_line
• alias
• chat_id
• user_id
• chat_type
• title
• username
• first_name
• enabled
• created_at
• verified_at
• last_error

Pravidlo:

• jeden zákazník a jedna owner_line mohou mít maximálně jeden aktivní Telegram cíl
• více linek stejného zákazníka může používat stejný Telegram cíl přes tel://owner_line
• Telegram cíl může být soukromý chat, skupina nebo supergroup

Tím platí, že každá linka může mít maximálně jeden vlastní Telegram cíl, ale zároveň jiné linky stejného zákazníka mohou tento cíl použít.

future code

Serverová část bude přijímat příchozí zprávy od Telegramu.

Produkčně má smysl použít webhook. Telegram při kliknutí zákazníka na párovací odkaz pošle našemu serveru update s informací o chatu a zprávě.

Serverová část musí umět zpracovat hlavně příkaz /start TOKEN.

Zpracování:

• přijmout update od Telegramu
• ověřit, že požadavek patří našemu botovi
• z textu zprávy vyčíst TOKEN
• najít TOKEN v databázi párovacích tokenů
• ověřit, že token existuje, není expirovaný a nebyl použitý
• zjistit customer_id a owner_line
• z Telegram update získat chat_id
• uložit chat_id do Telegram cílů
• uložit typ chatu
• uložit název nebo username, pokud jsou dostupné
• označit token jako použitý
• poslat potvrzovací zprávu do Telegramu

Příklad potvrzovací zprávy:

Odorik: Telegram cíl byl připojen k lince 300169. Pro použití u dalších linek použijte tel://300169.

future code

U linky bude možnost připojit Telegram cíl pro nahrávky.

Na webu mají být dvě volby:

• připojit můj Telegram účet
• připojit Telegram skupinu

Podle volby se vygeneruje odkaz na Telegram bota.

Pro soukromý účet se použije varianta start.

Pro skupinu se použije varianta startgroup.

Zákazník si tím sám určí, jestli chce nahrávky dostávat do soukromého chatu nebo do skupiny.

Po kliknutí se otevře Telegram a zákazník provede spárování. Po úspěšném spárování se v systému uloží chat_id.

future code

Po úspěšném spárování se má u linky zobrazit stav Telegram cíle.

Zobrazení má obsahovat:

• informaci, že Telegram cíl je aktivní
• adresu pro použití u dalších linek, například tel://300169
• typ cíle, například soukromý chat nebo skupina
• název skupiny nebo username, pokud je dostupný
• čas ověření

Doporučené akce:

• poslat testovací zprávu
• odpojit Telegram
• připojit znovu
• zobrazit interní URI pro použití u dalších linek

Chat_id není nutné běžně ukazovat zákazníkovi. Pro zákazníka je důležité hlavně tel://300169 a srozumitelný popis cíle.

future code

Pokud má zákazník více linek, nemusí připojovat Telegram znovu u každé linky.

Stačí, aby u další linky použil existující interní URI.

Příklad:

• Telegram cíl vznikl u linky 300169
• u linky 405277 zákazník nastaví tel://300169
• nahrávky z linky 405277 se odešlou do Telegram cíle vytvořeného u linky 300169

Web může zákazníkovi nabídnout seznam jeho existujících Telegram cílů, aby nemusel URI opisovat ručně.

future code

Stávající pole pro cíle doručení zůstane zachované.

Nově se musí rozpoznat položky začínající na tel://.

Rozesílací skript musí u každé položky rozpoznat typ cíle a pro tel:// spustit Telegram transport.

Pro tel://300169 musí rozesílací skript udělat:

• zjistit aktuálního zákazníka
• vzít alias 300169
• najít Telegram cíl podle zákazníka a aliasu
• ověřit, že cíl je aktivní
• vzít uložený chat_id
• odeslat metadata hovoru a nahrávku

Pokud Telegram cíl neexistuje nebo není aktivní, doručení na tento cíl se musí považovat za neúspěšné.

future code

Telegram transport bude další doručovací metoda vedle současných metod.

Musí umět:

• připravit text zprávy
• doplnit metadata hovoru
• připojit nahrávku
• odeslat zprávu a soubor přes Telegram API
• zkontrolovat odpověď Telegramu
• zalogovat výsledek
• předat výsledek do rozhodování o smazání souboru

Doporučený obsah zprávy:

• informace, že jde o nahrávku hovoru z Odoriku
• linka, ze které se nahrávka posílá
• odchozí nebo příchozí číslo, pokud je dostupné
• čas hovoru
• délka hovoru
• případně další údaje, které už dnes rozesílací skript zná

Konkrétní dostupná metadata z aktuálního rozesílacího skriptu:

NELZE URČIT – CHYBÍ DATA

future code

Pro Telegram musí platit, že soubor se nesmí smazat před úspěšným odesláním nahrávky.

Pokud je v poli pro doručení více cílů, je potřeba jasně definovat, kdy se soubor smaže.

Doporučené pravidlo:

• nahrávku smazat až po dokončení všech požadovaných doručení
• pokud některý cíl selže, nahrávku nemazat
• chybu uložit do logu nebo evidence doručení

Jak přesně dnes mazání funguje v produkčním skriptu:

NELZE URČIT – CHYBÍ DATA

future code

Je potřeba ošetřit hlavní chybové stavy.

Příklady chyb:

• URI odkazuje na neexistující Telegram cíl
• Telegram cíl je vypnutý
• zákazník zablokoval bota
• bot byl odebraný ze skupiny
• bot nemá právo psát do skupiny
• skupina byla smazaná
• Telegram API vrací timeout
• Telegram API vrací rate limit
• textová zpráva odešla, ale odeslání souboru selhalo
• soubor je moc velký

Doporučené chování:

• pokud selže odeslání nahrávky, soubor nemazat
• zapsat chybu do logu
• uložit chybu k Telegram cíli jako last_error
• u trvalých chyb označit cíl jako problematický nebo vypnutý

future code

Je potřeba definovat, co se stane, když nahrávku nebude možné přes Telegram odeslat kvůli velikosti souboru.

Doporučené pravidlo pro první verzi:

• pokud Telegram soubor nevezme, doručení se považuje za neúspěšné
• soubor se nemaže
• chyba se zaloguje

Možné budoucí varianty:

• poslat jen upozornění bez přílohy
• poslat odkaz na nahrávku
• zmenšit nebo překódovat nahrávku
• použít jiné technické řešení pro větší soubory

Konkrétní limit a zvolený fallback pro produkci:

NELZE URČIT – CHYBÍ DATA

future code

Na webu u Telegram cíle má být možnost poslat testovací zprávu.

Testovací zpráva ověří:

• že chat_id je stále platné
• že bot má právo do cíle psát
• že zákazník zprávu vidí tam, kde ji očekává
• že Telegram cíl je správně připojený k lince

Příklad testovací zprávy:

Odorik: testovací zpráva pro Telegram cíl linky 300169. Tento cíl lze použít jako tel://300169.

future code

Na webu musí být možnost Telegram cíl odpojit.

Je potřeba rozlišit:

• odpojení od konkrétní linky
• smazání Telegram cíle úplně

Pokud Telegram cíl používá více linek, při smazání je potřeba zobrazit varování.

Příklad varování:

Tento Telegram cíl používá více linek. Smazáním cíle přestanou chodit nahrávky ze všech linek, které používají odpovídající URI.

future code

Je vhodné logovat stav doručení pro každý jednotlivý cíl.

Doporučené údaje:

• identifikace nahrávky
• název souboru
• linka
• cílové URI
• Telegram chat_id
• výsledek doručení
• Telegram message_id, pokud je dostupné
• chybový kód
• chybový text
• čas začátku doručení
• čas konce doručení

Do běžných logů se nesmí zapisovat:

• Telegram bot token
• hesla z jiných URI
• zbytečný obsah citlivých údajů
• obsah nahrávky

future code

Základní bezpečnostní pravidla:

• tel://300169 smí použít jen zákazník, kterému patří daný Telegram cíl
• chat_id se nemá zadávat ručně jako důvěryhodný údaj
• chat_id se má získat přes Telegram bota a párovací token
• párovací token musí být jednorázový
• párovací token musí expirovat
• bot token se nesmí logovat
• Telegram cíl musí jít odpojit
• nahrávka se nesmí smazat před potvrzeným doručením podle pravidel rozesílacího skriptu
• zákazník si sám hlídá členy své Telegram skupiny

Telegram skupina je z pohledu systému jen jeden doručovací cíl. Pokud zákazník chce, aby nahrávky vidělo více lidí, může si je přidat do své Telegram skupiny.

future code

Současné doručování musí zůstat zachované.

Telegram se přidá pouze jako další typ cíle.

Stávající cíle se nemají měnit. Nově přibude pouze rozpoznání tel://.

Výsledné chování:

• běžné e-mailové doručování zůstane stejné
• současné URI doručování zůstane stejné
• pokud se v poli objeví tel://, spustí se Telegram transport
• pokud Telegram transport selže, chyba se řeší stejně jako chyba jiného doručovacího cíle podle pravidel rozesílacího skriptu

future code

První verze musí obsahovat:

• vytvoření bota @OdorikCallRecordingsBot
• serverovou část pro příjem /start TOKEN
• DB tabulku pro párovací tokeny
• DB tabulku pro Telegram cíle
• webové párování soukromého chatu nebo skupiny
• zobrazení tel://owner_line zákazníkovi
• rozšíření pole recording_email o tel://
• rozšíření rozesílacího skriptu o Telegram transport
• ošetření mazání souboru
• ošetření chyb
• logování výsledku doručení
• testovací zprávu
• možnost odpojení Telegram cíle

Princip:

• zákazník vytvoří Telegram cíl u linky 300169
• systém uloží chat_id
• ostatní linky stejného zákazníka mohou používat tel://300169
• rozesílací skript podle tel://300169 najde chat_id
• nahrávka se odešle do Telegramu
• po úspěšném doručení se nahrávka smaže podle pravidel rozesílacího skriptu

future code