API Telegram
Fare clic qui per visualizzare questa pagina nel contesto completo

API Telegram

Telegram

 

Telegram offre due tipi di API: la Bot API, che consente di creare programmi che utilizzano bot e HTTPS come protocollo, e la Telegram API e TDLib, che permettono di creare client Telegram personalizzati ed è molto più potente della Bot API.

 

sgcWebSockets supporta TDLib tramite la libreria tdjson, il che significa che è possibile costruire il proprio client Telegram. TDLib si occupa di tutti i dettagli di implementazione di rete, crittografia e archiviazione dati locale. TDLib supporta tutte le funzionalità di Telegram.

 

Vantaggi di TDLib (Telegram Database Library)

 

 

Configurazione

Windows

 

TDLib richiede altre librerie di terze parti: OpenSSL e ZLib. Queste librerie devono essere distribuite insieme alla libreria tdjson.

 

* Le versioni Windows richiedono VCRuntime, scaricabile da Microsoft: https://www.microsoft.com/en-us/download/details.aspx?id=52685. Se il problema persiste dopo l'installazione, provare a copiare le seguenti dll nella stessa cartella dell'applicazione: VCRUNTIME140.dll e VCRUNTIME140_1.dll.

 

Copiare le seguenti librerie nella stessa directory in cui si trova l'applicazione:

 

Windows 32 Windows 64
tdjson.dll tdjson.dll
libcrypto-1_1.dll libcrypto-1_1-x64.dll
libssl-1_1.dll libssl-1_1-x64.dll
zlib1.dll zlib1.dll

 

 

OSX64

 

Distribuire la libreria libtdjson.dylib sul dispositivo e impostare il percorso della libreria tramite SetTDJsonPath, ad esempio:

 

Se si esegue il deploy in "Contents\MacOS\", è necessario impostare il percorso nella cartella TPath.GetDirectoryName(ParamStr(0)).

 

OSXARM64

 

Distribuire la libreria libtdjson.dylib sul dispositivo e impostare il percorso della libreria tramite SetTDJsonPath, ad esempio:

 

Se si esegue il deploy in "Contents\MacOS\", è necessario impostare il percorso nella cartella TPath.GetDirectoryName(ParamStr(0)).

 

Linux64

 

Distribuire la libreria libtdjson.so sul dispositivo e impostare il percorso della libreria chiamando il metodo SetTDJsonPath.

 

Android

 

Distribuire la libreria libtdjsonandroid.so sul dispositivo. Esempio: se si distribuisce una libreria Android64, impostare RemotePath in Project/Deployment su "library\lib\arm64-v8a\". Se è Android32, impostare RemotePath su "library\lib\armeabi-v7a\"

 

iOS64

 

Copiare la libreria libtdjson.a nelle seguenti directory:

 

 

Creazione dell'applicazione Telegram

Per ottenere un ID API e sviluppare la propria applicazione utilizzando l'API Telegram, è necessario seguire questi passaggi:

 

 

Questi valori devono essere impostati nella proprietà Telegram.API del componente Telegram. Per autenticarsi, è possibile farlo come utente o come bot; ci sono 2 proprietà che è possibile impostare per accedere a Telegram:

 

 

È possibile configurare i seguenti parametri:

 

 

Facoltativamente, è possibile configurare il percorso in cui si trova la libreria tdjson utilizzando il metodo SetTDJsonPath. Basta passare il percorso prima di avviare una nuova sessione Telegram.

 

Una volta configurato il componente Telegram, è possibile impostare la proprietà Active su true e il programma tenterà di connettersi a Telegram.

 

Codice di esempio


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;

 

Authorization

Ci sono due eventi che possono essere chiamati dalla libreria per ottenere un Codice di Autenticazione (consegnato nell'applicazione Telegram, non via SMS) o per fornire una password.

 

OnAuthenticationCode

 

Questo evento viene chiamato quando Telegram invia un Codice di Autorizzazione all'applicazione Telegram e l'utente deve copiare questo codice e impostarlo nell'argomento Code di questo evento.

 


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

 

In Android, inputbox non blocca il thread, quindi invece di restituire il valore immesso dall'utente nel parametro Code, utilizzare il metodo SetAuthenticationCode per impostare il valore del codice.

 


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

 

Questo evento viene chiamato quando Telegram richiede all'utente di impostare una password.

 

 

Stato dell'autorizzazione

Una volta avviata l'autorizzazione, è possibile verificare lo stato tramite l'evento OnAuthorizationStatus; questo evento viene chiamato ogni volta che si verifica un cambiamento di stato nell'autorizzazione. Alcuni valori di Status sono:

 

 

Stato della Connessione

Una volta avviata la connessione, è possibile verificare lo stato della connessione tramite l'evento OnConnectionStatus; questo evento viene chiamato ogni volta che cambia lo stato della connessione. Alcuni valori di Status sono:

 

 

Metodi principali

Il componente API TsgcTDLib_Telegram supporta diversi metodi Telegram; di seguito sono elencati i più utilizzati.

 

Method Parametri Descrizione
SendTextMessage

aChatId: Id della Chat a cui verrà inviato il messaggio aText: Testo del messaggio.

InlineKeyboard: Pulsanti facoltativi (solo bot).

 Invia un messaggio di testo a una chat
SendRichTextMessage

aChatId: Id della chat a cui verrà inviato il messaggio aText: Testo del messaggio.

InlineKeyboard: Pulsanti facoltativi (solo bot).

 Invia un messaggio in formato Rich Text a una Chat. Sintassi Markdown:
  • Grassetto: **bold**
  • Corsivo: __italic__
  • Barrato: --strike--
  • Sottolineato: ~~underline~~
  • Codice: ##code##
SendDocumentMessage aChatId: Id della chat a cui verrà inviato il messaggio aFilePath: percorso completo del file del documento aInlineKeyboard: Pulsanti opzionali (solo bot). Invia un documento a una chat.
SendPhotoMessage

aChatId: Id della chat a cui verrà inviato il messaggio aFilePath: percorso completo del file della foto

Width: larghezza della foto.

Height: larghezza della foto.

InlineKeyboard: Pulsanti facoltativi (solo bot).

 Invia una foto a una chat.
SendVideoMessage

aChatId: Id della Chat a cui verrà inviato il messaggio aFilePath: percorso completo del file del video aWidth: larghezza del video.

Height: larghezza del video.

aDuration: durata del video in secondi.

aInlineKeyboard: Pulsanti opzionali (solo bot).

 Invia un video a una chat.
SendInvoiceMessage

aChatId: Id della chat a cui verrà inviato il messaggio aInvoice: Testo del messaggio.

aInlineKeyboard: Pulsanti opzionali (solo bot).

 Invia una Fattura (disponibile solo quando si è un Bot e nei Canali Privati).
EditTextMessage

aChatId: ID della chat a cui verrà inviato il messaggio

aMessageId: Id del messaggio da modificare

Text: Testo del messaggio.

InlineKeyboard: Pulsanti facoltativi (solo bot).

ShowKeyboard: pulsanti opzionali (solo bot).

 Modifica il testo di un messaggio (o il testo di un messaggio di gioco)
AddChatMember aChatId: Id della chat a cui verrà inviato il messaggio aUserId: Identificatore dell'utente. aForwardLimit: Il numero di messaggi precedenti della chat da inoltrare al nuovo membro; fino a 100. Ignorato per supergruppi e canali. Aggiunge un nuovo membro a una chat. I membri non possono essere aggiunti a chat private o segrete. I membri non verranno aggiunti fino a quando lo stato della chat non sarà sincronizzato con il server.
AddChatMembers aChatId: Id della chat a cui verrà inviato il messaggio aUserIds: Identificatori degli utenti da aggiungere alla chat. Aggiunge più nuovi membri a una chat. Attualmente questa opzione è disponibile solo per supergruppi e canali. Questa opzione non può essere utilizzata per partecipare a una chat. I membri non possono essere aggiunti a un canale se ha più di 200 membri. I membri non verranno aggiunti fino a quando lo stato della chat non sarà sincronizzato con il server.
GetChatMember aChatId: Identificatore Chat. aUserId: Identificatore Utente. Restituisce informazioni su un singolo membro di una chat.
GetBasicGroupFullInfo aGroupId: Identificatore del gruppo di base Restituisce le informazioni complete su un gruppo di base tramite il suo identificatore.
GetSupergroupMembers

aSuperGroupId: Identificatore del supergruppo o del canale.

aSupergroupMembersFilter: Il tipo di utenti da restituire. Per impostazione predefinita null aOffset: Numero di utenti da saltare.

aLimit: Il numero massimo di utenti da restituire; fino a 200.

 Restituisce informazioni sui membri o sugli utenti bannati in un supergruppo o canale.
JoinChatByInviteLink aLink: Link di invito da importare; Utilizza un invite link per aggiungere l'utente corrente alla chat se possibile. Il nuovo membro non verrà aggiunto finché lo stato della chat non sarà stato sincronizzato con il server.
CreateNewSecretChat aUserId: Identificatore dell'utente. Crea una nuova chat segreta.
CreateNewBasicGroupChat aUserIds: Identificatori degli utenti da aggiungere alla chat. aTitle: Titolo del nuovo gruppo di base Crea un nuovo gruppo base
CreateNewSupergroupChat

aTitle: Titolo del nuovo SuperGroup

aIsChannel: True, se deve essere creata una chat di canale. aDescription: Descrizione della chat.

 Crea un nuovo supergruppo o canale.
CreatePrivateChat

aUserId: Identificatore dell'utente.

aForce: Se true, la chat verrà creata senza richiesta di rete. In questo caso tutte le informazioni sulla chat ad eccezione del tipo, del titolo e della foto potrebbero non essere corrette

 Restituisce una chat esistente corrispondente a un determinato utente
GetChats aOffsetOrder: Ordine della chat da cui restituire le chat aOffsetChatId: Identificatore della chat da cui restituire le chat aLimit: Il numero massimo di chat da restituire. Restituisce un elenco ordinato di chat. Le chat sono ordinate per la coppia (order, chat_id) in ordine decrescente (non può essere utilizzato se registrato come Bot)
GetChat aChatId: Identificatore della chat Restituisce informazioni su una chat tramite il suo identificatore
GetChatHistory

aChatId: Identificatore della chat

aFromMessageId: Identificatore del messaggio a partire dal quale deve essere recuperata la cronologia; utilizzare 0 per ottenere i risultati dall'ultimo messaggio.

aOffset: Specificare 0 per ottenere risultati esattamente dal from_message_id oppure un offset negativo fino a 99 per ottenere anche alcuni messaggi più recenti.

aLimit:Il numero massimo di messaggi da restituire

 Restituisce i messaggi di una chat. I messaggi vengono restituiti in ordine cronologico inverso
GetUser aUserId: Identificatore utente Restituisce informazioni su un utente tramite il suo identificatore.
AddProxyHTTP

aServer: Nome del server proxy.

aPort: Numero della porta proxy.

aUserName: Nome utente per l'accesso; può essere vuoto.

aPassword: Password per l'accesso; può essere vuota.

aHTTPOnly: Passare true se il proxy supporta solo richieste HTTP e non supporta connessioni TCP trasparenti tramite il metodo HTTP CONNECT.

 Aggiunge un server proxy HTTP per le richieste di rete. Può essere chiamato prima dell'autorizzazione.
AddProxyMTProto

aServer: Nome del server proxy.

aPort: Numero della porta proxy. aSecret: Il segreto del proxy in codifica esadecimale.

 Aggiunge un server proxy MTProto per le richieste di rete. Può essere chiamato prima dell'autorizzazione.
AddProxySocks5

aServer: Nome del server proxy.

aPort: Numero della porta proxy.

aUserName: Nome utente per l'accesso; può essere vuoto.

aPassword: Password per l'accesso; può essere vuota.

 Aggiunge un server proxy Socks5 per le richieste di rete. Può essere chiamato prima dell'autorizzazione.
EnableProxy aId: ID del proxy Abilita un proxy. È possibile abilitare un solo proxy alla volta. Può essere chiamato prima dell'autorizzazione.
DisableProxy   Disabilita il proxy attualmente abilitato. Può essere chiamato prima dell'autorizzazione.
RemoveProxy aId: ID del proxy Rimuove un server proxy. Può essere chiamato prima dell'autorizzazione.
GetProxies   Restituisce l'elenco dei proxy attualmente configurati. Può essere chiamato prima dell'autorizzazione.
getChatSponsoredMessage aChatId: ID della chat Restituisce il messaggio sponsorizzato da mostrare in una chat; solo per le chat di canale. Restituisce un errore 404 se non è presente alcun messaggio sponsorizzato nella chat.
ViewMessage

aSponsorChatId: ID della Chat sponsor

aMessageId: ID del messaggio

 Informa TDLib che i messaggi vengono visualizzati dall'utente. Molte attività utili dipendono dal fatto che i messaggi vengano attualmente visualizzati o meno
Logout   Disconnessione da Telegram.
TDLibSend aRequest: Richiesta JSON. Invia qualsiasi richiesta nel protocollo JSON.

 

 

Esempio di come inviare un messaggio di testo


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');

Esempio: come inviare un metodo non implementato

 

È possibile inviare qualsiasi messaggio JSON utilizzando il metodo TDLibSend, ad esempio: unirsi a una chat di 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"}');

 

 

Eventi

OnBeforeReadEvent

Questo evento viene chiamato quando un messaggio JSON viene ricevuto dal componente API Telegram e non è ancora stato elaborato. Impostare la proprietà Handled su True se si elabora questo evento manualmente o se non si desidera che l'evento venga elaborato dal componente. È possibile utilizzare questo evento anche per registrare tutti i messaggi.

 

OnMessageText

Questo evento viene chiamato quando è stato ricevuto un nuovo testo di messaggio; legga il parametro MessageText per accedere alle proprietà del testo del messaggio.

 

 

OnMessageDocument

Questo evento viene chiamato quando viene ricevuto un nuovo messaggio documento. Accedere a MessageDocument per ottenere accesso alle proprietà del documento.

 

 

OnMessagePhoto

Questo evento viene generato quando viene ricevuto un nuovo messaggio fotografico. Accedere a MessagePhoto per ottenere le proprietà della foto.

 

 

OnVideoPhoto

Questo evento viene chiamato quando viene ricevuto un nuovo messaggio video. Accedere a MessageVideo per ottenere accesso alle proprietà del video.

 

 

OnMessageSponsored

Questo evento viene chiamato quando viene ricevuto un nuovo messaggio sponsorizzato (dopo aver chiamato il metodo getChatSponsoredMessage)

 

 

OnNewChat

Questo evento viene chiamato quando viene ricevuta una nuova chat.

 

 

OnNewCallbackQuery

Questo evento viene chiamato quando viene ricevuta una nuova callback query in entrata; solo per i bot.

 

 

OnEvent

Questo evento viene chiamato quando un nuovo Evento viene ricevuto dal componente API. Può essere utilizzato per elaborare alcuni eventi non implementati dal componente API.

 

 

OnException

Questo evento viene chiamato se si verifica un'eccezione durante l'elaborazione dei dati dell'API Telegram.

 

Proprietà

MyId: restituisce l'identificatore dell'utente corrente.

 

Esempio di codice completo

Verificare il seguente esempio di codice che mostra come connettersi alla API di Telegram, chiedere all'utente di inserire un Codice (se richiesto dalla API di Telegram), inviare un messaggio quando la connessione è pronta e registrare i messaggi di testo ricevuti.


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;