API Telegram

Telegram は 2 種類の API を提供しています。Bot API はボットを作成し HTTPS をプロトコルとして使用するプログラムを作成できます。Telegram API と TDLib はカスタム Telegram クライアントを構築でき、Bot API よりはるかに強力です。

sgcWebSockets は tdjson ライブラリを通じて TDLib をサポートしています。これにより、独自の Telegram クライアントを構築できます。TDLib はネットワーク実装の詳細、暗号化、ローカルデータストレージをすべて処理します。TDLib はすべての Telegram 機能をサポートしています。

TDLib (Telegram Database Library) の利点

クロスプラットフォーム: Windows、Android、iOS、MacOS、Linux などで使用できます。
使いやすさ: アプリケーションと Telegram 間の通信に JSON メッセージを使用します。
高パフォーマンス： Telegram Bot API では、各 TDLib インスタンスが 24,000 以上のボットを処理します。
Consistent： TDLib はすべての更新が正しい順序で配信されることを保証します。
Reliable: TDLibは、低速で信頼性の低いインターネット接続でも安定しています。
Secure: すべてのローカルデータは、ユーザー提供の暗号化キーを使用して暗号化されます。
完全非同期: TDLib へのリクエストはお互いをブロックしません。レスポンスは利用可能になったときに送信されます。

設定

Windows

TDLibは他のサードパーティライブラリを必要とします: OpenSSLとZLib。これらのライブラリはtdjsonライブラリと一緒にデプロイする必要があります。

* Windows バージョンは VCRuntime が必要です。Microsoft からダウンロードできます: https://www.microsoft.com/en-us/download/details.aspx?id=52685。インストール後も問題が続く場合は、アプリケーションと同じフォルダーに次の DLL をコピーしてみてください: VCRUNTIME140.dll および VCRUNTIME140_1.dll。

次のライブラリをアプリケーションと同じディレクトリにコピーしてください:

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

ライブラリ libtdjson.dylib をデバイスにデプロイすると、SetTDJsonPathを使用してライブラリの場所を設定できます。例:

"Contents\MacOS\" にデプロイする場合は、TPath.GetDirectoryName(ParamStr(0)) フォルダーにパスを設定する必要があります。

OSXARM64

ライブラリ libtdjson.dylib をデバイスにデプロイすると、SetTDJsonPathを使用してライブラリの場所を設定できます。例:

"Contents\MacOS\" にデプロイする場合は、TPath.GetDirectoryName(ParamStr(0)) フォルダーにパスを設定する必要があります。

Linux64

デバイスに libtdjson.so ライブラリをデプロイし、SetTDJsonPath メソッドを呼び出してライブラリパスを設定します。

Android

デバイスにライブラリ libtdjsonandroid.so をデプロイします。例: Android64 ライブラリをデプロイする場合は、Project/Deployment の RemotePath を "library\lib\arm64-v8a\" に設定します。Android32 の場合は、RemotePath を "library\lib\armeabi-v7a\" に設定します。

iOS64

ライブラリ libtdjson.a を次のディレクトリにコピーしてください：

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

Telegram アプリケーションの作成

Telegram API を使用して独自のアプリケーションを開発するための API id を取得するには、以下の手順を実行する必要があります。

任意のアプリケーションを使用して Telegram にサインアップします。
Telegram コアにログインしてください: https://my.telegram.org。
API 開発ツールにアクセスしてフォームに入力します。
基本的なアドレスのほか、ユーザー認証に必要な api_id と api_hash パラメータも取得できます。
現時点では、各番号には 1 つの api_id のみを接続できます。

これらの値は Telegram コンポーネントの Telegram.API プロパティに設定する必要があります。認証するには、ユーザーまたはボットとして認証できます。Telegram にログインするために設定できる 2 つのプロパティがあります。

PhoneNumber: ユーザーとしてログインする場合は、電話番号（国際コード付き）を設定する必要があります。例: +34699123456
BotToken:ボットとしてログインする場合は、Telegramから提供されたトークンをこのプロパティに設定します。
DatabaseDirectory: tdlib データベースの場所を指定できます。空のままにすると、デフォルトの設定が使用されます。

以下のパラメータを設定できます：

ApplicationVersion：アプリケーションバージョン、例：1.0
DeviceModel：デバイスモデル、例：desktop
LanguageCode：ユーザー言語コード、例：en。
SystemVersion: オペレーティングシステムのバージョン。例: windows。

オプションで、SetTDJsonPathメソッドを使用して、tdjsonライブラリが置かれているパスを設定できます。新しいtelegramセッションを開始する前にパスを渡すだけです。

Telegram コンポーネントを設定したら、Active プロパティを true に設定するとプログラムは 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.ApplicationVersion := '1.0';
oTelegram.DeviceModel := 'Desktop';
oTelegram.LanguageCode := 'en';
oTelegram.SystemVersion := 'Windows';
oTelegram.Active := true;

認証

認証コード（SMS ではなく Telegram アプリケーション内で配信）を取得するため、またはパスワードを提供するためにライブラリから呼び出される 2 つのイベントがあります。

OnAuthenticationCode

このイベントは、Telegram が Telegram アプリケーションに認証コードを送信し、ユーザーがそのコードをコピーしてこのイベントの Code 引数に設定する必要があるときに呼び出されます。


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

Android では、inputbox はスレッドをロックしないため、Code パラメーターでユーザーが入力した値を返す代わりに、SetAuthenticationCode メソッドを使用してコード値を設定してください。


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

このイベントは、Telegram がユーザーにパスワードの設定を要求するときに呼び出されます。

認可ステータス

認可が開始されると、OnAuthorizationStatus イベントで認可のステータスを確認できます。このイベントは認可のステータスに変化があるたびに呼び出されます。ステータスの値の例:

authorizationStateWaitTdlibParameters
authorizationStateWaitEncryptionKey
authorizationStateWaitPhoneNumber
authorizationStateWaitCode
authorizationStateLoggingOut
authorizationStateClosed
authorizationStateReady

接続ステータス

接続が開始されると、接続のステータスを OnConnectionStatus イベントで確認できます。このイベントは接続のステータスが変化するたびに呼び出されます。Status の値の例:

connectionStateConnecting
connectionStateUpdating
connectionStateReady

主要メソッド

TsgcTDLib_Telegram APIコンポーネントはいくつかのTelegramメソッドをサポートしています。以下に最もよく使用されるものを示します。

メソッド	パラメータ	説明
SendTextMessage	aChatId: メッセージの送信先となるChatのId aText: メッセージのテキスト。 InlineKeyboard：オプションのボタン（ボットのみ）。	チャットにテキストメッセージを送信します
SendRichTextMessage	aChatId: メッセージを送信するチャットのID aText: メッセージのテキスト。 InlineKeyboard：オプションのボタン（ボットのみ）。	チャットにリッチテキストメッセージを送信します。 Markdown構文: 太字: bold 斜体: __italic__ 取り消し線: --strike-- 下線: ~~underline~~ コード: ##code##
SendDocumentMessage	aChatId: メッセージを送信するチャットの ID aFilePath: ドキュメントの完全なファイルパス aInlineKeyboard: オプションのボタン (ボットのみ)。	チャットにドキュメントを送信します。
SendPhotoMessage	aChatId: メッセージを送信するチャットのIdです aFilePath: 写真のフルファイルパスです Width: 写真の幅。 Height: 写真の幅。 InlineKeyboard：オプションのボタン（ボットのみ）。	チャットに写真を送信します。
SendVideoMessage	aChatId: メッセージを送信するチャットの ID aFilePath: 動画の完全ファイルパス aWidth: 動画の幅。 Height: ビデオの幅。 aDuration: 動画の長さ（秒単位）。 aInlineKeyboard: オプションのボタン (ボットのみ)。	チャットにビデオを送信します。
SendInvoiceMessage	aChatId: メッセージを送信するチャットの ID aInvoice: メッセージのテキスト。 aInlineKeyboard: オプションのボタン (ボットのみ)。	請求書を送信します（ボットかつプライベートチャンネルでのみ利用可能）。
EditTextMessage	aChatId: メッセージを送信するチャットのID aMessageId: 変更するメッセージのID Text: メッセージのテキスト。 InlineKeyboard：オプションのボタン（ボットのみ）。 ShowKeyboard: オプションボタン（ボットのみ）。	メッセージのテキスト(またはゲームメッセージのテキスト)を編集します
AddChatMember	aChatId:メッセージを送信するチャットのID。 aUserId:ユーザーの識別子。 aForwardLimit:新しいメンバーに転送するチャットの以前のメッセージ数。最大100件。スーパーグループとチャンネルでは無視されます。	チャットに新しいメンバーを追加します。メンバーはプライベートまたはシークレットチャットには追加できません。チャットの状態がサーバーと同期されるまで、メンバーは追加されません。
AddChatMembers	aChatId: メッセージが送信されるChatのId aUserIds: チャットに追加されるユーザーの識別子。	チャットに複数の新しいメンバーを追加します。現在このオプションはスーパーグループとチャンネルのみ利用できます。このオプションはチャットへの参加には使用できません。チャンネルのメンバーが200人を超えている場合、メンバーを追加することはできません。チャットの状態がサーバーと同期されるまで、メンバーは追加されません。
GetChatMember	aChatId: チャット識別子。 aUserId: ユーザー識別子。	チャットの特定のメンバーに関する情報を返します。
GetBasicGroupFullInfo	aGroupId: 基本グループ識別子	識別子によってベーシックグループの完全な情報を返します。
GetSupergroupMembers	aSuperGroupId: スーパーグループまたはチャンネルの識別子。 aSupergroupMembersFilter: 返すユーザーの種類。デフォルトは null。 aOffset: スキップするユーザーの数。 aLimit: 返されるユーザーの最大数。最大200人。	スーパーグループまたはチャンネルのメンバーまたは禁止されたユーザーに関する情報を返します。
JoinChatByInviteLink	aLink: インポートする招待リンク；	可能であれば、招待リンクを使用して現在のユーザーをチャットに追加します。チャット状態がサーバーと同期されるまで、新しいメンバーは追加されません。
CreateNewSecretChat	aUserId: ユーザーの識別子。	新しいシークレットチャットを作成します。
CreateNewBasicGroupChat	aUserIds: チャットに追加するユーザーの識別子。 aTitle: 新しい基本グループのタイトル。	新しい基本グループを作成します
CreateNewSupergroupChat	aTitle: 新しいスーパーグループのタイトル aIsChannel: True の場合、チャンネルチャットが作成されます。 aDescription: チャットの説明。	新しいスーパーグループまたはチャンネルを作成します。
CreatePrivateChat	aUserId: ユーザーの識別子。 aForce: trueの場合、ネットワークリクエストなしでチャットが作成されます。この場合、チャットのタイプ、タイトル、写真を除くすべての情報が正しくない可能性があります	指定したユーザーに対応する既存のチャットを返します。
GetChats	aOffsetOrder: チャットを返す起点となるチャット順序 aOffsetChatId: チャットを返す起点となるチャット識別子 aLimit: 返されるチャットの最大数です。	チャットの順序付きリストを返します。チャットはペア（order, chat_id）で降順にソートされます（ボットとしてログインされている場合は使用できません）
GetChat	aChatId: チャット識別子	識別子でチャットに関する情報を返します。
GetChatHistory	aChatId: チャット識別子 aFromMessageId: 履歴を取得する開始メッセージの識別子。最後のメッセージから結果を取得するには 0 を使用します。 aOffset: from_message_id からの結果を正確に取得するには 0 を指定し、追加の新しいメッセージを取得するには最大 99 までの負のオフセットを指定します。 aLimit：返されるメッセージの最大数	チャットのメッセージを返します。メッセージは逆時系列順で返されます
GetUser	aUserId：ユーザー識別子	識別子によってユーザーに関する情報を返します。
AddProxyHTTP	aServer: プロキシのサーバー名。 aPort: プロキシポートの番号。 aUserName: ログイン用のユーザー名。空でもかまいません。 aPassword: ログイン用のパスワード。空でも可。 aHTTPOnly: プロキシが HTTP リクエストのみをサポートし、HTTP CONNECT メソッドによる透過的な TCP 接続をサポートしない場合は True を渡します。	ネットワークリクエスト用のHTTPプロキシサーバーを追加します。認可の前に呼び出すことができます。
AddProxyMTProto	aServer: プロキシのサーバー名。 aPort：プロキシポートの番号。 aSecret： 16 進数エンコードのプロキシシークレット。	ネットワークリクエスト用 MTProto プロキシサーバーを追加します。認可前に呼び出し可能です。
AddProxySocks5	aServer: プロキシのサーバー名。 aPort: プロキシポートの番号。 aUserName: ログイン用のユーザー名。空でもかまいません。 aPassword: ログイン用のパスワードです。空でも構いません。	ネットワークリクエスト用のSocks5プロキシサーバーを追加します。認証前に呼び出すことができます。
EnableProxy	aId: プロキシのID	プロキシを有効にします。一度に有効にできるプロキシは 1 つだけです。認可前に呼び出し可能です。
DisableProxy		現在有効なプロキシを無効にします。認可の前に呼び出すことができます。
RemoveProxy	aId: プロキシのID	プロキシサーバーを削除します。認証前に呼び出すことができます。
GetProxies		現在設定されているプロキシのリストを返します。認証前に呼び出すことができます。
getChatSponsoredMessage	aChatId: チャットのID	チャットに表示されるスポンサーメッセージを返します（チャンネルチャットのみ）。チャットにスポンサーメッセージがない場合は 404 エラーを返します。
ViewMessage	aSponsorChatId: スポンサーチャットの ID。 aMessageId: メッセージの ID	ユーザーがメッセージを閲覧中であることを TDLib に通知します。多くの有用な動作は、メッセージが現在表示されているかどうかによって異なります。
Logout		Telegram からのログアウト。
TDLibSend	aRequest: JSON リクエスト。	JSON プロトコルで任意のリクエストを送信します。

テキストメッセージの送信方法の使用例


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

未実装メソッドの送信方法の例

TDLibSendメソッドを使用して任意のJSONメッセージを送信できます。例: 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"}');

イベント

OnBeforeReadEvent

このイベントは Telegram API コンポーネントが JSON メッセージを受信し、まだ処理されていない場合に呼び出されます。このイベントを手動で処理する場合、またはコンポーネントによってイベントが処理されないようにする場合は、Handled プロパティを True に設定してください。このイベントはすべてのメッセージをログに記録するためにも使用できます。

OnMessageText

このイベントは新しいテキストメッセージが受信されたときに呼び出されます。MessageText パラメータを読み取ってメッセージテキストのプロパティにアクセスします。

ChatId: チャット識別子。
MessageId: メッセージ識別子。
SenderUserId: 送信者の識別子。
Text: メッセージのテキスト。

OnMessageDocument

このイベントは、新しいドキュメントメッセージが受信されたときに呼び出されます。MessageDocument にアクセスしてドキュメントプロパティにアクセスします。

ChatId: チャット識別子。
MessageId: メッセージ識別子。
SenderUserId: 送信者の識別子（tdlib 1.7.+からSenderChatとSenderUserを読み取ります）。
FileName: ドキュメントの名前。
DocumentId：ドキュメント識別子。
LocalPath: 存在する場合のローカルファイルへの完全パス。
MimeType: ドキュメントの MIME タイプ。
Size: ドキュメントのサイズ。
RemoteDocumentId:リモートドキュメント識別子。

OnMessagePhoto

新しい写真メッセージが受信されたときに呼び出されます。写真のプロパティにアクセスするには MessagePhoto にアクセスします。

ChatId: チャット識別子。
MessageId: メッセージ識別子。
SenderUserId: 送信者の識別子（tdlib 1.7.+からSenderChatとSenderUserを読み取ります）。
PhotoId: 写真の識別子。
LocalPath: 存在する場合のローカルファイルへの完全パス。
Size: 写真のサイズ。
RemotePhotoId: リモート写真識別子。

OnVideoPhoto

新しいビデオメッセージを受信したときに呼び出されるイベントです。MessageVideoにアクセスしてビデオプロパティを取得します。

ChatId: チャット識別子。
MessageId: メッセージ識別子。
SenderUserId: 送信者の識別子（tdlib 1.7.+からSenderChatとSenderUserを読み取ります）。
VideoId: 写真の識別子です。
LocalPath: 存在する場合のローカルファイルへの完全パス。
Width: ビデオの幅。
Height: 動画の高さ。
Duration：ビデオの再生時間（秒）。
Size: 動画のサイズ。
RemoteVideoId: リモート写真の識別子。

OnMessageSponsored

このイベントは、新しいSponsoredメッセージが受信されたとき(メソッドgetChatSponsoredMessage)の呼び出し後)に呼び出されます

SponsorChatId: スポンサーチャット識別子。
MessageId: メッセージ識別子。
Text: メッセージのテキスト。

OnNewChat

新しいチャットを受信したときに呼び出されるイベントです。

ChatId: チャット識別子。
ChatType: チャットタイプ（chatTypeSupergroup、chatTypePrivate...）
Title：チャット名。
SuperGroupId: SuperGroupの場合のGroup Id。
IsChannel: チャンネルかどうかを返します。

OnNewCallbackQuery

このイベントは新しい受信コールバッククエリが受信されたときに呼び出されます（ボットのみ）。

Id: 一意のクエリ識別子。
SenderUserId：クエリを送信したユーザーの識別子。
ChatId: クエリが送信されたチャットの識別子。
MessageId: クエリが発信されたメッセージの識別子。
ChatInstance: メッセージが送信されたチャットに一意に対応する識別子。
PayloadData: 汎用コールバックボタンからのペイロード。
- Data: コールバックボタンにアタッチされたデータ。

OnEvent

このイベントは API コンポーネントが新しいイベントを受信したときに呼び出されます。API コンポーネントで実装されていない一部のイベントを処理するために使用できます。

Event：イベント名（例：updateOption、updateUser...）
Text: 完全なJSONメッセージ

OnException

Telegram API データの処理中に例外が発生した場合にこのイベントが呼び出されます。

プロパティ

MyId: 現在のユーザーのユーザー識別子を返します。

完全なコードサンプル

以下のコードサンプルを確認してください。Telegram API への接続方法、（Telegram API が必要な場合に）ユーザーにコードを入力させる方法、接続準備ができたらメッセージを送信する方法、受信したテキストメッセージをログに記録する方法を示しています。


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;