API Telegram
Cliquez ici pour afficher cette page dans son contexte complet

API Telegram

Telegram

 

Telegram propose deux types d'API : l'une est la Bot API qui vous permet de créer des programmes utilisant des bots et HTTPS comme protocole. La Telegram API et TDLib vous permettent de créer des clients Telegram personnalisés et sont bien plus puissantes que la Bot API.

 

sgcWebSockets prend en charge TDLib via la bibliothèque tdjson, ce qui signifie que vous pouvez construire votre propre client Telegram. TDLib prend en charge tous les détails d'implémentation réseau, le chiffrement et le stockage des données locales. TDLib supporte toutes les fonctionnalités de Telegram.

 

Avantages de TDLib (Telegram Database Library)

 

 

Configuration

Windows

 

TDLib nécessite d'autres bibliothèques tierces : OpenSSL et ZLib. Ces bibliothèques doivent être déployées avec la bibliothèque tdjson.

 

* Les versions Windows nécessitent VCRuntime, téléchargeable depuis Microsoft : https://www.microsoft.com/en-us/download/details.aspx?id=52685. Si le problème persiste après l'installation, essayez de copier les dll suivantes dans le même dossier que votre application : VCRUNTIME140.dll et VCRUNTIME140_1.dll.

 

Copiez les bibliothèques suivantes dans le même répertoire que votre application :

 

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

 

Déployez la bibliothèque libtdjson.dylib sur votre appareil et vous pouvez définir l'emplacement de la bibliothèque à l'aide de SetTDJsonPath, exemple :

 

si vous déployez vers "Contents\MacOS\", vous devez définir le chemin dans le dossier TPath.GetDirectoryName(ParamStr(0)).

 

OSXARM64

 

Déployez la bibliothèque libtdjson.dylib sur votre appareil et vous pouvez définir l'emplacement de la bibliothèque à l'aide de SetTDJsonPath, exemple :

 

si vous déployez vers "Contents\MacOS\", vous devez définir le chemin dans le dossier TPath.GetDirectoryName(ParamStr(0)).

 

Linux64

 

Déployez la bibliothèque libtdjson.so sur votre appareil et définissez le chemin de la bibliothèque en appelant la méthode SetTDJsonPath.

 

Android

 

Déployez la bibliothèque libtdjsonandroid.so sur votre appareil. Exemple : si vous déployez une bibliothèque Android64, définissez RemotePath dans Project/Deployment sur « library\lib\arm64-v8a\ ». Si c'est Android32, définissez RemotePath sur « library\lib\armeabi-v7a\ »

 

iOS64

 

Copiez la bibliothèque libtdjson.a dans ces répertoires :

 

 

Création de votre application Telegram

Pour obtenir un identifiant d'API et développer votre propre application en utilisant l'API Telegram, vous devez effectuer les opérations suivantes :

 

 

Ces valeurs doivent être définies dans la propriété Telegram.API du composant Telegram. Pour s'authentifier, vous pouvez vous authentifier en tant qu'utilisateur ou en tant que bot ; il y a 2 propriétés que vous pouvez définir pour vous connecter à Telegram :

 

 

Les paramètres suivants peuvent être configurés :

 

 

Optionnellement, vous pouvez configurer le chemin où se trouve la bibliothèque tdjson en utilisant la méthode SetTDJsonPath. Passez simplement le chemin avant de démarrer une nouvelle session Telegram.

 

Une fois le composant Telegram configuré, vous pouvez définir la propriété Active à true et le programme tentera de se connecter à Telegram.

 

Exemple de code


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;

 

Autorisation

Il existe deux événements que la bibliothèque peut appeler afin d'obtenir un code d'authentification (livré dans l'application Telegram, pas par SMS) ou de fournir un mot de passe.

 

OnAuthenticationCode

 

Cet événement est appelé lorsque Telegram envoie un code d'autorisation à l'application Telegram et que l'utilisateur doit copier ce code et le définir dans l'argument Code de cet événement.

 


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

 

Sur Android, la boîte de saisie ne bloque pas le thread ; par conséquent, au lieu de retourner la valeur saisie par l'utilisateur dans le paramètre Code, utilisez la méthode SetAuthenticationCode pour définir la valeur du code.

 


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

 

Cet événement est appelé lorsque Telegram demande à l'utilisateur de définir un mot de passe.

 

 

Statut d'autorisation

Une fois l'autorisation démarrée, vous pouvez vérifier le statut de l'autorisation via l'événement OnAuthorizationStatus ; cet événement est appelé chaque fois qu'il y a un changement de statut d'autorisation. Certaines valeurs de Status sont :

 

 

État de la connexion

Une fois la connexion démarrée, vous pouvez vérifier le statut de la connexion via l'événement OnConnectionStatus ; cet événement est appelé chaque fois qu'il y a un changement de statut de connexion. Quelques valeurs de Status :

 

 

Méthodes principales

Le composant API TsgcTDLib_Telegram prend en charge plusieurs méthodes Telegram ; retrouvez ci-dessous les plus utilisées.

 

Méthode Paramètres Description
SendTextMessage

aChatId : Id du chat auquel le message sera envoyé aText : Texte du message.

InlineKeyboard : Boutons optionnels (bots uniquement).

Envoie un message texte à un chat
SendRichTextMessage

aChatId : Identifiant du chat auquel le message sera envoyé aText : Texte du message.

InlineKeyboard : Boutons optionnels (bots uniquement).

Envoie un message texte enrichi dans un chat. Syntaxe Markdown :
  • Gras : **bold**
  • Italique : __italic__
  • Barré : --strike--
  • Souligné : ~~underline~~
  • Code : ##code##
SendDocumentMessage aChatId : Id du chat auquel le message sera envoyé aFilePath : chemin complet du fichier document aInlineKeyboard : Boutons optionnels (bots uniquement). Envoie un document à un chat.
SendPhotoMessage

aChatId : Identifiant du chat auquel le message sera envoyé aFilePath : chemin complet du fichier photo

Width : largeur de la photo.

Hauteur : largeur de la photo.

InlineKeyboard : Boutons optionnels (bots uniquement).

Envoie une photo dans un chat.
SendVideoMessage

aChatId : Id du Chat auquel le message sera envoyé aFilePath : chemin complet du fichier vidéo aWidth : largeur de la vidéo.

Height : largeur de la vidéo.

aDuration : durée de la vidéo en secondes.

aInlineKeyboard : Boutons optionnels (uniquement pour les bots).

 Envoie une vidéo à un chat.
SendInvoiceMessage

aChatId : Identifiant du chat auquel le message sera envoyé aInvoice : Texte du message.

aInlineKeyboard : Boutons optionnels (uniquement pour les bots).

 Envoie une facture (disponible uniquement lorsqu'il s'agit d'un Bot et dans les canaux privés).
EditTextMessage

aChatId : identifiant du chat auquel le message sera envoyé

aMessageId : Identifiant du message à modifier

Text : Texte du message.

InlineKeyboard : Boutons optionnels (bots uniquement).

ShowKeyboard : Boutons optionnels (bots uniquement).

 Modifie le texte d'un message (ou le texte d'un message de jeu)
AddChatMember aChatId : Identifiant du chat auquel le message sera envoyé aUserId : Identifiant de l'utilisateur. aForwardLimit : Le nombre de messages précédents du chat à transmettre au nouveau membre ; jusqu'à 100. Ignoré pour les supergroupes et les canaux. Ajoute un nouveau membre à un chat. Les membres ne peuvent pas être ajoutés aux chats privés ou secrets. Les membres ne seront pas ajoutés tant que l'état du chat n'aura pas été synchronisé avec le serveur.
AddChatMembers aChatId : Id du chat auquel le message sera envoyé aUserIds : Identifiants des utilisateurs à ajouter au chat. Ajoute plusieurs nouveaux membres à un chat. Actuellement, cette option n'est disponible que pour les supergroupes et les canaux. Cette option ne peut pas être utilisée pour rejoindre un chat. Les membres ne peuvent pas être ajoutés à un canal s'il a plus de 200 membres. Les membres ne seront pas ajoutés tant que l'état du chat n'a pas été synchronisé avec le serveur.
GetChatMember aChatId : Identifiant de chat. aUserId : Identifiant d'utilisateur. Renvoie les informations sur un seul membre d'un chat.
GetBasicGroupFullInfo aGroupId : Identifiant de groupe de base Retourne les informations complètes sur un groupe de base par son identifiant.
GetSupergroupMembers

aSuperGroupId : Identifiant du supergroupe ou du canal.

aSupergroupMembersFilter : Le type d'utilisateurs à retourner. Par défaut null aOffset : Nombre d'utilisateurs à ignorer.

aLimit: Le nombre maximum d'utilisateurs à renvoyer ; jusqu'à 200.

Retourne des informations sur les membres ou les utilisateurs bannis d'un supergroupe ou d'un canal.
JoinChatByInviteLink aLink : lien d'invitation à importer ; Utilise un lien d'invitation pour ajouter l'utilisateur actuel au chat si possible. Le nouveau membre ne sera pas ajouté tant que l'état du chat n'aura pas été synchronisé avec le serveur.
CreateNewSecretChat aUserId : Identifiant de l'utilisateur. Crée un nouveau chat secret.
CreateNewBasicGroupChat aUserIds : Identifiants des utilisateurs à ajouter au chat. aTitle : Titre du nouveau groupe de base Crée un nouveau groupe de base
CreateNewSupergroupChat

aTitle : Titre du nouveau SuperGroupe

aIsChannel : True, si une discussion de canal doit être créée. aDescription : Description de la discussion.

Crée un nouveau supergroupe ou canal.
CreatePrivateChat

aUserId : Identifiant de l'utilisateur.

aForce: Si true, le chat sera créé sans requête réseau. Dans ce cas, toutes les informations sur le chat, à l'exception de son type, de son titre et de sa photo, peuvent être incorrectes

Retourne une discussion existante correspondant à un utilisateur donné
GetChats aOffsetOrder : Ordre de chat à partir duquel retourner les chats aOffsetChatId : Identifiant de chat à partir duquel retourner les chats aLimit : Le nombre maximum de chats à retourner. Renvoie une liste ordonnée de chats. Les chats sont triés par la paire (order, chat_id) par ordre décroissant (ne peut pas être utilisé si connecté en tant que Bot)
GetChat aChatId: Identifiant du chat Retourne des informations sur un chat par son identifiant
GetChatHistory

aChatId : Identifiant du chat

aFromMessageId : Identifiant du message à partir duquel l'historique doit être récupéré ; utilisez 0 pour obtenir les résultats à partir du dernier message.

aOffset : Spécifiez 0 pour obtenir les résultats à partir exactement du from_message_id ou un décalage négatif jusqu'à 99 pour obtenir également quelques messages plus récents.

aLimit:Le nombre maximum de messages à retourner

Retourne les messages d'un chat. Les messages sont retournés dans l'ordre chronologique inverse.
GetUser aUserId : Identifiant utilisateur Retourne des informations sur un utilisateur par son identifiant.
AddProxyHTTP

aServer: Nom du serveur proxy.

aPort : Numéro du port proxy.

aUserName : Nom d'utilisateur pour la connexion ; peut être vide.

aPassword : Mot de passe pour la connexion ; peut être vide.

aHTTPOnly : Passez true si le proxy ne prend en charge que les requêtes HTTP et ne prend pas en charge les connexions TCP transparentes via la méthode HTTP CONNECT.

 Ajoute un serveur proxy HTTP pour les requêtes réseau. Peut être appelé avant l'autorisation.
AddProxyMTProto

aServer: Nom du serveur proxy.

aPort : Numéro du port proxy. aSecret : Le secret du proxy en encodage hexadécimal.

Ajoute un serveur proxy MTProto pour les requêtes réseau. Peut être appelé avant l'autorisation.
AddProxySocks5

aServer: Nom du serveur proxy.

aPort : Numéro du port proxy.

aUserName : Nom d'utilisateur pour la connexion ; peut être vide.

aPassword : Mot de passe pour la connexion ; peut être vide.

Ajoute un serveur proxy Socks5 pour les requêtes réseau. Peut être appelé avant l'autorisation.
EnableProxy aId : identifiant du proxy Active un proxy. Un seul proxy peut être activé à la fois. Peut être appelé avant l'autorisation.
DisableProxy   Désactive le proxy actuellement activé. Peut être appelé avant l'autorisation.
RemoveProxy aId : identifiant du proxy Supprime un serveur proxy. Peut être appelé avant l'autorisation.
GetProxies   Retourne la liste des proxies actuellement configurés. Peut être appelé avant l'autorisation.
getChatSponsoredMessage aChatId : identifiant du chat Retourne le message sponsorisé à afficher dans un chat ; uniquement pour les chats de canaux. Retourne une erreur 404 s'il n'y a pas de message sponsorisé dans le chat.
ViewMessage

aSponsorChatId : Identifiant du chat sponsor

aMessageId : ID du message

 Informe TDLib que des messages sont en cours de consultation par l'utilisateur. De nombreuses activités utiles dépendent du fait que les messages sont actuellement consultés ou non
Déconnexion   Déconnexions de Telegram.
TDLibSend aRequest : Requête JSON. Envoyer n'importe quelle requête au format JSON.

 

 

Exemple d'envoi d'un message texte 


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

Exemple d'envoi d'une méthode non implémentée

 

Vous pouvez envoyer n'importe quel message JSON en utilisant la méthode TDLibSend, exemple : rejoindre un chat 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"}');

 

 

Événements

OnBeforeReadEvent

Cet événement est appelé lorsqu'un message JSON est reçu par le composant API Telegram et n'a pas encore été traité. Définissez la propriété Handled sur True si vous traitez cet événement manuellement ou si vous ne souhaitez pas que l'événement soit traité par le composant. Vous pouvez également utiliser cet événement pour journaliser tous les messages.

 

OnMessageText

Cet événement est appelé lorsqu'un nouveau message texte a été reçu ; lisez le paramètre MessageText pour accéder aux propriétés du texte du message.

 

 

OnMessageDocument

Cet événement est appelé lorsqu'un nouveau message Document est reçu. Accédez à MessageDocument pour obtenir les propriétés du document.

 

 

OnMessagePhoto

Cet événement est appelé lorsqu'un nouveau message photo est reçu. Accédez à MessagePhoto pour accéder aux propriétés de la photo.

 

 

OnVideoPhoto

Cet événement est appelé lorsqu'un nouveau message vidéo est reçu. Accédez à MessageVideo pour obtenir les propriétés vidéo.

 

 

OnMessageSponsored

Cet événement est appelé lorsqu'un nouveau message sponsorisé a été reçu (après avoir appelé la méthode getChatSponsoredMessage)

 

 

OnNewChat

Cet événement est appelé lorsqu'un nouveau chat est reçu.

 

 

OnNewCallbackQuery

Cet événement est appelé lorsqu'une nouvelle requête de callback entrante est reçue ; pour les bots uniquement.

 

 

OnEvent

Cet événement est appelé lorsqu'un nouvel événement est reçu par le composant API. Il peut être utilisé pour traiter certains événements non implémentés par le composant API.

 

 

OnException

Cet événement est appelé s'il y a une exception lors du traitement des données de l'API Telegram.

 

Propriétés

MyId : retourne l'identifiant d'utilisateur de l'utilisateur actuel.

 

Exemple de code complet

Consultez l'exemple de code suivant qui montre comment se connecter à l'API Telegram, demander à l'utilisateur de saisir un Code (si requis par l'API Telegram), envoyer un message lorsque la connexion est prête et journaliser les messages texte reçus. 


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;