API Telegram

Telegram

Telegram oferuje dwa rodzaje API: Bot API umożliwia tworzenie programów korzystających z botów i protokołu HTTPs, natomiast Telegram API i TDLib pozwalają budować niestandardowych klientów Telegram i oferują znacznie więcej możliwości niż Bot API.

sgcWebSockets obsługuje TDLib za pośrednictwem biblioteki tdjson, co oznacza, że można zbudować własnego klienta Telegram. TDLib zajmuje się wszystkimi szczegółami implementacji sieciowej, szyfrowaniem i lokalnym przechowywaniem danych. TDLib obsługuje wszystkie funkcje Telegram.

Zalety TDLib (Telegram Database Library)

• Wieloplatformowy: może być używany w systemach Windows, Android, iOS, MacOS, Linux...

• Łatwość użycia: do komunikacji między aplikacją a Telegram używane są wiadomości JSON.

• Wysoka wydajność: W Telegram Bot API każda instancja TDLib obsługuje ponad 24 000 botów.

• Consistent: TDLib gwarantuje, że wszystkie aktualizacje zostaną dostarczone we właściwej kolejności.

• Niezawodność: TDLib pozostaje stabilny przy wolnych i zawodnych połączeniach internetowych.

• Secure: Wszystkie lokalne dane są szyfrowane przy użyciu klucza szyfrowania podanego przez użytkownika.

• W pełni asynchroniczny: Żądania do TDLib nie blokują się nawzajem. Odpowiedzi są wysyłane, gdy są dostępne.

Konfiguracja

Windows

TDLib wymaga innych bibliotek firm trzecich: OpenSSL i ZLib. Biblioteki te muszą być wdrożone razem z biblioteką tdjson.

* Wersje Windows wymagają VCRuntime, który można pobrać od firmy Microsoft: https://www.microsoft.com/en-us/download/details.aspx?id=52685. Jeśli problem nadal występuje po instalacji, należy skopiować następujące biblioteki DLL do folderu, w którym znajduje się aplikacja: VCRUNTIME140.dll i VCRUNTIME140_1.dll.

Skopiuj następujące biblioteki do tego samego katalogu, w którym znajduje się aplikacja:

OSX64

Wdróż bibliotekę libtdjson.dylib na urządzeniu i możesz ustawić lokalizację biblioteki za pomocą SetTDJsonPath, na przykład:

Jeśli wdrożenie następuje do katalogu „Contents\MacOS\", należy ustawić ścieżkę w folderze TPath.GetDirectoryName(ParamStr(0)).

OSXARM64

Wdróż bibliotekę libtdjson.dylib na urządzeniu i możesz ustawić lokalizację biblioteki za pomocą SetTDJsonPath, na przykład:

Jeśli wdrożenie następuje do katalogu „Contents\MacOS\", należy ustawić ścieżkę w folderze TPath.GetDirectoryName(ParamStr(0)).

Linux64

Wdróż bibliotekę libtdjson.so na urządzeniu i ustaw ścieżkę biblioteki, wywołując metodę SetTDJsonPath.

Android

Należy wdrożyć bibliotekę libtdjsonandroid.so na urządzeniu. Przykład: jeśli wdrażana jest biblioteka Android64, należy ustawić RemotePath w Project/Deployment na "library\lib\arm64-v8a\". Dla wersji Android32 należy ustawić RemotePath na "library\lib\armeabi-v7a\".

iOS64

Skopiuj bibliotekę libtdjson.a do następujących katalogów:

• C:\Program Files (x86)\Embarcadero\Studio\<IDE Version>\lib\iosDevice64\debug

• C:\Program Files (x86)\Embarcadero\Studio\<IDE Version>\lib\iosDevice64\release

Tworzenie aplikacji Telegram

Aby uzyskać identyfikator API i opracować własną aplikację korzystającą z Telegram API, należy wykonać następujące czynności:

• Zarejestruj się w Telegram za pomocą dowolnej aplikacji.

• Zaloguj się do rdzenia Telegram: https://my.telegram.org.

• Przejdź do narzędzi deweloperskich API i wypełnij formularz.

• Zostaną uzyskane podstawowe adresy, a także parametry api_id i api_hash wymagane do autoryzacji użytkownika.

• Na chwilę obecną każdy numer może mieć podłączony tylko jeden api_id.

Wartości te należy ustawić we właściwości Telegram.API komponentu Telegram. W celu uwierzytelnienia można zalogować się jako użytkownik lub jako bot; dostępne są 2 właściwości, które można ustawić, aby zalogować się do Telegrama:

• PhoneNumber: w przypadku logowania jako użytkownik należy podać numer telefonu (z kodem kierunkowym kraju), na przykład: +34699123456

• BotToken: jeśli logujesz się jako bot, ustaw tutaj swój token (zgodnie z informacją od Telegrama).

• DatabaseDirectory: umożliwia określenie lokalizacji bazy danych tdlib. Pozostaw puste, aby użyć domyślnej konfiguracji.

Można skonfigurować następujące parametry:

• ApplicationVersion: wersja aplikacji, przykład: 1.0

• DeviceModel: model urządzenia, przykład: desktop

• LanguageCode: kod języka użytkownika, przykład: en.

• SystemVersion: wersja systemu operacyjnego, przykład: windows.

Opcjonalnie można skonfigurować ścieżkę, w której znajduje się biblioteka tdjson, używając metody SetTDJsonPath. Wystarczy przekazać ścieżkę przed rozpoczęciem nowej sesji Telegram.

Po skonfigurowaniu komponentu Telegram można ustawić właściwość Active na true, a program podejmie próbę połączenia z Telegram.

Przykładowy kod

oTelegram := TsgcTDLib_Telegram.Create(nil);
oTelegram.Telegram.API.ApiHash := 'your api hash';
oTelegram.Telegram.API.ApiId := 'your api id';
oTelegram.PhoneNumber := 'your phone number';
oTelegram.ApplicationVersion := '1.0';
oTelegram.DeviceModel := 'Desktop';
oTelegram.LanguageCode := 'en';
oTelegram.SystemVersion := 'Windows';
oTelegram.Active := true;

Autoryzacja

Istnieją dwa zdarzenia, które mogą być wywoływane przez bibliotekę w celu uzyskania kodu uwierzytelniającego (dostarczanego w aplikacji Telegram, nie SMS-em) lub podania hasła.

OnAuthenticationCode

To zdarzenie jest wywoływane, gdy Telegram wyśle kod autoryzacyjny do aplikacji Telegram i użytkownik musi skopiować ten kod i wprowadzić go w argumencie Code tego zdarzenia.

procedure OnAuthenticationCode(Sender: TObject; var Code: string);
begin
  Code := InputBox('Telegram Code', 'Introduce code', '');
end;

W systemie Android pole wprowadzania tekstu nie blokuje wątku, dlatego zamiast zwracać wartość wprowadzoną przez użytkownika w parametrze Code, należy użyć metody SetAuthenticationCode do ustawienia wartości kodu.

procedure OnAuthenticationCode(Sender: TObject; var Code:string);
begin
  InputBox('Telegram', 'Introduce Telegram Code', '',
    procedure(const AResult: TModalResult; const AValue: string)
    begin
      sgcTelegram.SetAuthenticationCode(AValue);
    end
    );
end;

OnAuthenticationPassword

To zdarzenie jest wywoływane, gdy Telegram wymaga od użytkownika ustawienia hasła.

Stan autoryzacji

Po rozpoczęciu autoryzacji można sprawdzać jej status w zdarzeniu OnAuthorizationStatus, wywoływanym za każdym razem, gdy nastąpi zmiana statusu autoryzacji. Niektóre wartości parametru Status to:

• authorizationStateWaitTdlibParameters
• authorizationStateWaitEncryptionKey
• authorizationStateWaitPhoneNumber
• authorizationStateWaitCode
• authorizationStateLoggingOut
• authorizationStateClosed
• authorizationStateReady

Stan połączenia

Po rozpoczęciu połączenia można sprawdzić jego status za pomocą zdarzenia OnConnectionStatus, które jest wywoływane za każdym razem, gdy zmienia się stan połączenia. Przykładowe wartości Status:

• connectionStateConnecting
• connectionStateUpdating
• connectionStateReady

Główne metody

Komponent API TsgcTDLib_Telegram obsługuje kilka metod Telegrama; poniżej przedstawiono najczęściej używane.

Przykład wysyłania wiadomości tekstowej

oTelegram := TsgcTDLib_Telegram.Create(nil);
oTelegram.Telegram.API.ApiHash := 'your api hash';
oTelegram.Telegram.API.ApiId := 'your api id';
oTelegram.PhoneNumber := 'your phone number';
oTelegram.Active := true;
...
oTelegram.SendTextMessage('1234', 'My First Message from sgcWebSockets');

Przykład: wysyłanie odpowiedzi „metoda nie zaimplementowana"

Dowolną wiadomość JSON można wysłać za pomocą metody TDLibSend, na przykład w celu dołączenia do czatu Telegram.

oTelegram := TsgcTDLib_Telegram.Create(nil);
oTelegram.Telegram.API.ApiHash := 'your api hash';
oTelegram.Telegram.API.ApiId := 'your api id';
oTelegram.PhoneNumber := 'your phone number';
oTelegram.Active := true;
...
oTelegram.TDLibSend('{"@type": "joinChat", "chat_id": "1234"}');

Zdarzenia

OnBeforeReadEvent

Zdarzenie jest wywoływane, gdy komponent API Telegram odbierze wiadomość JSON, która nie została jeszcze przetworzona. Należy ustawić właściwość Handled na True, jeśli zdarzenie jest przetwarzane ręcznie lub nie ma być obsługiwane przez komponent. Zdarzenia można również używać do rejestrowania wszystkich wiadomości.

OnMessageText

Zdarzenie wywoływane po odebraniu nowej wiadomości tekstowej; należy odczytać parametr MessageText, aby uzyskać dostęp do właściwości tekstu wiadomości.

• ChatId: identyfikator czatu.
• MessageId: Identyfikator wiadomości.
• SenderUserId: Identyfikator nadawcy.
• Text: Treść wiadomości.

OnMessageDocument

Zdarzenie jest wywoływane po odebraniu nowej wiadomości dokumentu. Dostęp do właściwości dokumentu można uzyskać przez MessageDocument.

• ChatId: identyfikator czatu.
• MessageId: Identyfikator wiadomości.
• SenderUserId: Identyfikator nadawcy (odczytaj SenderChat i SenderUser z tdlib 1.7.+).
• FileName: Nazwa dokumentu.
• DocumentId: Identyfikator dokumentu.
• LocalPath: pełna ścieżka do lokalnego pliku, jeśli istnieje.
• MimeType: Typ MIME dokumentu.
• Size: Rozmiar dokumentu.
• RemoteDocumentId: Identyfikator dokumentu zdalnego.

OnMessagePhoto

Zdarzenie jest wywoływane po odebraniu nowej wiadomości ze zdjęciem. Dostęp do właściwości zdjęcia uzyskuje się za pośrednictwem obiektu MessagePhoto.

• ChatId: identyfikator czatu.
• MessageId: Identyfikator wiadomości.
• SenderUserId: Identyfikator nadawcy (odczytaj SenderChat i SenderUser z tdlib 1.7.+).
• PhotoId: identyfikator zdjęcia.
• LocalPath: pełna ścieżka do lokalnego pliku, jeśli istnieje.
• Size: Rozmiar zdjęcia.
• RemotePhotoId: Zdalny identyfikator zdjęcia.

OnVideoPhoto

To zdarzenie jest wywoływane po odebraniu nowej wiadomości wideo. Dostęp do MessageVideo umożliwia odczyt właściwości wideo.

• ChatId: identyfikator czatu.
• MessageId: Identyfikator wiadomości.
• SenderUserId: Identyfikator nadawcy (odczytaj SenderChat i SenderUser z tdlib 1.7.+).
• VideoId: Identyfikator zdjęcia.
• LocalPath: pełna ścieżka do lokalnego pliku, jeśli istnieje.
• Width: szerokość obrazu wideo.
• Height: wysokość obrazu wideo.
• Duration: czas trwania wideo w sekundach.
• Size: Rozmiar wideo.
• RemoteVideoId: Zdalny identyfikator zdjęcia.

OnMessageSponsored

To zdarzenie jest wywoływane po odebraniu nowej sponsorowanej wiadomości (po wywołaniu metody getChatSponsoredMessage)

• SponsorChatId: Identyfikator czatu sponsora.
• MessageId: Identyfikator wiadomości.
• Text: Treść wiadomości.

OnNewChat

To zdarzenie jest wywoływane po odebraniu nowego czatu.

• ChatId: identyfikator czatu.
• ChatType: Typ czatu (chatTypeSupergroup, chatTypePrivate...)
• Title: Nazwa czatu.
• SuperGroupId: Identyfikator grupy, jeśli jest to SuperGrupa.
• IsChannel: zwraca informację, czy jest to kanał, czy nie.

OnNewCallbackQuery

To zdarzenie jest wywoływane po odebraniu nowego przychodzącego zapytania zwrotnego; tylko dla botów.

• Id: Unikalny identyfikator zapytania.
• SenderUserId: Identyfikator użytkownika, który wysłał zapytanie.
• ChatId: identyfikator czatu, w którym zostało wysłane zapytanie.
• MessageId: Identyfikator wiadomości, z której pochodzi zapytanie.
• ChatInstance: Identyfikator jednoznacznie odpowiadający czatowi, do którego wysłano wiadomość.
• PayloadData: ładunek z ogólnego przycisku wywołania zwrotnego.
  • Data: Dane dołączone do przycisku wywołania zwrotnego.

OnEvent

Zdarzenie to jest wywoływane, gdy komponent API odbierze nowe zdarzenie. Może być używane do przetwarzania zdarzeń niezaimplementowanych przez komponent API.

• Zdarzenie: Nazwa zdarzenia (zdarzenia takie jak: updateOption, updateUser...)
• Text: pełna wiadomość JSON

OnException

To zdarzenie jest wywoływane, gdy podczas przetwarzania danych Telegram API wystąpi wyjątek.

Właściwości

MyId: zwraca identyfikator bieżącego użytkownika.

Pełny przykład kodu

Zapoznaj się z poniższym przykładem kodu, który pokazuje, jak połączyć się z Telegram API, poprosić użytkownika o wprowadzenie kodu (jeśli jest to wymagane przez Telegram API), wysłać wiadomość po nawiązaniu połączenia oraz rejestrować odbierane wiadomości tekstowe.

oTelegram := TsgcTDLib_Telegram.Create(nil);
oTelegram.Telegram.API.ApiHash := 'your api hash';
oTelegram.Telegram.API.ApiId := 'your api id';
oTelegram.PhoneNumber := 'your phone number';
oTelegram.ApplicationVersion := '1.0';
oTelegram.DeviceModel := 'Desktop';
oTelegram.LanguageCode := 'en';
oTelegram.SystemVersion := 'Windows';
oTelegram.Active := true;
procedure OnAuthenticationCode(Sender: TObject; var Code: string);
begin
  Code := InputBox('Telegram Code', 'Introduce code', '');
end;
procedure OnMessageText(Sender: TObject; MessageText: TsgcTelegramMessageText);
begin
  Log('Message Received: ' + MessageText.Text);
end;
procedure OnConnectionStatus(Sender: TObject; const Status: string);
begin
  if Status = 'connectionStateReady' then
    oTelegram.SendTextMessage('1234', 'Hello Telegram!');
end;