Telegram API

Telegram 提供两种 API，一种是 Bot API，允许您使用机器人和 HTTPS 作为协议创建程序；另一种是 Telegram API 和 TDLib，允许您构建自定义 Telegram 客户端，功能远比 Bot API 强大。

sgcWebSockets 通过 tdjson 库支持 TDLib，这意味着您可以构建自己的 Telegram 客户端。TDLib 处理所有网络实现细节、加密和本地数据存储。TDLib 支持所有 Telegram 功能。

TDLib（Telegram 数据库库）优势

跨平台：可在 Windows、Android、iOS、MacOS、Linux 等平台上使用。
易于使用：使用 JSON 消息在应用程序与 Telegram 之间进行通信。
高性能：在 Telegram Bot API 中，每个 TDLib 实例可处理超过 24000 个机器人。
一致性：TDLib 保证所有更新将按正确顺序传递。
可靠性：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 库，请在项目/部署中将 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 应用程序

若要获取 API id 并使用 Telegram API 开发自己的应用程序，您需要执行以下操作：

使用任意应用程序注册 Telegram。
登录您的 Telegram 核心：https://my.telegram.org。
前往 API 开发工具并填写表单。
您将获得基本地址以及用户授权所需的 api_id 和 api_hash 参数。
目前每个号码只能连接一个 api_id。

这些值必须设置在 Telegram 组件的 Telegram.API 属性中。为了进行身份验证，您可以作为用户或机器人进行认证，有 2 个属性可用于登录 Telegram：

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;

授权

库可以调用两个事件，分别用于获取认证码（通过 Telegram 应用程序而非短信发送）或提供密码。

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 事件检查授权状态，每次授权状态发生变化时都会调用此事件。Status 的部分值包括：

authorizationStateWaitTdlibParameters
authorizationStateWaitEncryptionKey
authorizationStateWaitPhoneNumber
authorizationStateWaitCode
authorizationStateLoggingOut
authorizationStateClosed
authorizationStateReady

连接状态

连接启动后，您可以通过 OnConnectionStatus 事件检查连接状态，该事件在每次连接状态发生变化时调用。Status 的部分值如下：

connectionStateConnecting
connectionStateUpdating
connectionStateReady

主要方法

TsgcTDLib_Telegram API 组件支持多种 Telegram 方法，以下列出最常用的方法。

方法	参数	描述
SendTextMessage	aChatId：将发送消息的聊天 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：可选按钮（仅限 Bot）。	编辑消息的文本（或游戏消息的文本）
AddChatMember	aChatId：要发送消息的聊天 ID aUserId：用户的标识符。 aForwardLimit：要转发给新成员的聊天中较早消息的数量；最多 100 条。对于超级群组和频道忽略此项。	向聊天添加新成员。成员不能被添加到私密或秘密聊天中。成员在聊天状态与服务器同步之前不会被添加。
AddChatMembers	aChatId：将发送消息的聊天 Id aUserIds：要添加到聊天中的用户标识符。	向聊天添加多个新成员。目前此选项仅适用于超级群组和频道。此选项不能用于加入聊天。在聊天状态与服务器同步之前，成员不会被添加。
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：从该聊天 ID 开始返回聊天记录 aLimit：返回聊天记录的最大数量。	返回有序的聊天列表。聊天按 (order, chat_id) 对降序排序（以 Bot 身份登录时不可使用）
GetChat	aChatId：聊天标识符	根据标识符返回聊天的相关信息
GetChatHistory	aChatId：聊天标识符 aFromMessageId：从此消息 ID 开始获取历史记录；使用 0 从最新消息开始获取结果。 aOffset：指定 0 以从 from_message_id 精确获取结果，或指定最多 -99 的负偏移量以额外获取一些较新的消息。 aLimit：返回的最大消息数	返回聊天中的消息，消息按时间倒序排列
GetUser	aUserId：用户标识符	通过用户标识符返回用户信息。
AddProxyHTTP	aServer：代理的服务器名称。 aPort：代理端口号。 aUserName：用于登录的用户名；可以为空。 aPassword：登录密码；可为空。 aHTTPOnly：若代理仅支持 HTTP 请求而不支持通过 HTTP CONNECT 方法建立透明 TCP 连接，则传入 true。	为网络请求添加 HTTP 代理服务器。可以在授权之前调用。
AddProxyMTProto	aServer：代理的服务器名称。 aPort：代理端口号。 aSecret：以十六进制编码的代理密钥。	为网络请求添加 MTProto 代理服务器。可以在授权之前调用。
AddProxySocks5	aServer：代理的服务器名称。 aPort：代理端口号。 aUserName：用于登录的用户名；可以为空。 aPassword：登录密码；可为空。	为网络请求添加 Socks5 代理服务器。可以在授权之前调用。
EnableProxy	aId: 代理的 ID	启用代理。一次只能启用一个代理。可以在授权之前调用。
DisableProxy		禁用当前启用的代理。可在授权之前调用。
RemoveProxy	aId: 代理的 ID	移除代理服务器。可在授权之前调用。
GetProxies		返回当前设置的代理列表。可以在授权之前调用。
getChatSponsoredMessage	aChatId: 聊天的 ID	返回在聊天中显示的赞助消息；仅适用于频道聊天。如果聊天中没有赞助消息，则返回 404 错误。
ViewMessage	aSponsorChatId：赞助商聊天的 ID aMessageId：消息的 ID	通知 TDLib 用户正在查看消息。许多有用的活动取决于消息当前是否正在被查看。
注销		从 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

此事件在收到新的赞助消息时调用（在调用方法 getChatSponsoredMessage 之后）

SponsorChatId：赞助商聊天标识符。
MessageId：消息标识符。
Text：消息文本。

OnNewChat

当收到新的聊天时调用此事件。

ChatId：聊天标识符。
ChatType：聊天类型（chatTypeSupergroup、chatTypePrivate……）
Title：聊天名称。
SuperGroupId：如果是超级群组，则为群组 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;