このパッケージには 2 つのメッセージングクライアントが含まれています。WhatsApp Business Cloud と、公式 TDLib 上の Telegram です。WhatsApp は純粋な HTTPS で配布するものが何もないため、より短い手順で済みます。このページではまず WhatsApp のテキストメッセージを送信し、その後 Telegram に追加で必要なものを説明します。
コンポーネント 1 つ、Meta アプリの値 2 つ、そして API のレスポンスを文字列として返すメソッド呼び出し 1 つです。
TsgcWhatsApp_Client は SGC Social パレットページにあり、sgcLibs.pas で TsgcWhatsApp_Client_Base の公開ラッパーとして宣言されています。
WhatsAppOptions.PhoneNumberId と WhatsAppOptions.Token で、どちらも Meta の開発者アプリから取得します。送信にはそれ以外は必要ありません。
SendMessageText(aTo, aMessage) は、Meta Graph API の生のレスポンス本文である string を返します。これをログに記録すれば、送信が受け付けられたかどうかをすぐに確認できます。
TsgcTDLib_Telegram は公式の TDLib をラップしているため、実行ファイルと同じ場所にネイティブライブラリが必要です。これが唯一の追加手順で、プラットフォームごとのファイル名は下の表に記載しています。
エディションの列は、各クライアントを制御する define と、それが Source/sgcVer.inc の何行目にあるかを示しています。
| 項目 | 内容 |
|---|---|
| IDE | Delphi 7 から RAD Studio 13、および C++Builder 2007 から 13。 |
| uses 句 | パレットのクラスには sgcLibs を使用します。デモではオプションとメッセージの型のために sgcLib_WhatsApp_Client を追加しています。 |
| WhatsApp のエディション | SGC_WHATSAPP は 728 行目、727 行目から 758 行目までの {$IFDEF SGC_EDT_PRO} ブロックの最初の行で定義されています。つまり Professional 以上です。 |
| Telegram のエディション | SGC_TELEGRAM は 677、680、683、687、691、694 行目で定義されており、すべて 675 行目から 724 行目までの {$IFDEF SGC_EDT_STD} ブロック内にあります。それぞれがプラットフォームでガードされているため 6 行あります。つまり Standard 以上で、そこに列挙されているプラットフォームが対象です。 |
| エディション（単独パッケージ） | sgcSocial 製品は 860 行目で SGC_PACK_SOCIAL を定義し、968 行目から 971 行目の独自ブロックで、969 行目に SGC_TELEGRAM、970 行目に SGC_WHATSAPP を定義します。ライブラリの残りの部分を含まない、同じ 2 つのクライアントです。 |
| WhatsApp のプラットフォーム | ネイティブへの依存はなく、プラットフォームガードもありません。Meta Graph API への HTTPS 通信なので、TLS バックエンドがあるすべてのターゲットで動作します。 |
| Telegram のプラットフォーム | バイナリと同じ場所に TDLib JSON ライブラリが必要です。Windows では tdjson.dll、macOS 64 ビットでは libtdjson.dylib、Linux 64 ビットと Lazarus Linux では libtdjson.so、Android では libtdjsonandroid.so です。iOS 64 では、ライブラリは実行時に読み込まれる代わりに libtdjson.a として静的にリンクされます。 |
WhatsApp Business Cloud のテスト用番号、永続トークン、電話番号 ID はすべて Meta の開発者コンソールから取得します。コンポーネントがそれらを作成することはありません。
sgcSocial は sgcWebSockets のインストーラーに含まれており、単独のパッケージとしても提供されています。どちらでもインストールの手順は同じです。
ダウンロードしたファイルをフォルダーに展開します。以下ではこのフォルダーを {$DIR} と呼びます。
ツール、オプション、ライブラリの順に開きます。{$DIR}\source と、お使いの IDE 用の lib フォルダー（たとえば {$DIR}\libD13\$(Platform)）を追加します。
{$DIR}\Packages\ の下で、お使いの IDE バージョン用のパッケージグループを開きます。最初に実行時の .dpk をコンパイルし、次にデザイン時の dcl をインストールします。
SGC Social というページが表示されます。Standard ビルドには TsgcTDLib_Telegram が含まれます。Professional 以上では TsgcWhatsApp_Client も含まれます。
お使いのプラットフォーム用の TDLib JSON ライブラリを、実行ファイルと同じ場所にコピーします。同梱の Telegram デモのフォルダーには、Windows に必要な一式として tdjson.dll、libcrypto-3.dll、libssl-3.dll、zlib1.dll が入っています。
電話番号 ID とトークンを設定し、SendMessageText を呼び出して、Graph API から返されたレスポンスを読み取ります。
uses
Classes, SysUtils,
// sgc
sgcLibs, sgcLib_WhatsApp_Client;
procedure TFRMWhatsApp.btnSendMessageClick(Sender: TObject);
begin
whatsapp.WhatsAppOptions.PhoneNumberId := '1234567890';
whatsapp.WhatsAppOptions.Token := GetToken;
// returns the raw Graph API response body, so log it:
// a rejected send comes back in there, not as an exception
DoLog('Message Sent: ' + whatsapp.SendMessageText(
'+34600000000', 'Hello from Delphi'));
end;これが送信経路のすべてです。他に設定するものはなく、サーバーを起動しておく必要もありません。SendMessageImage、SendMessageDocument、SendMessageLocation、SendMessageContact、SendMessageInteractiveButtons、SendMessageTemplate も同じ形です。
procedure TFRMWhatsApp.FormCreate(Sender: TObject);
begin
// ... using neAsynchronous to update the memo control
// ... in production set the value neNoSync
whatsapp.NotifyEvents := neAsynchronous;
// the component hosts the Meta webhook itself
whatsapp.StartServer;
end;
procedure TFRMWhatsApp.whatsappMessageReceived(Sender: TObject;
const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean);
begin
if aMessage.Messages.Count > 0 then
begin
DoLog(aMessage.Messages._Message[0].Text.Body);
aMarkAsRead := True;
end;
end;受信は任意です。StopServer でリスナーを再び停止でき、OnBeforeSubscribe は、var Accept: Boolean パラメーターを通じて Meta の検証リクエストを受け入れるか拒否するかを決める場所です。
uses
Classes, SysUtils,
// sgc
sgcLibs, sgcLib_Telegram;
procedure TFRMSGCTelegram.btnStartClick(Sender: TObject);
begin
// The one thing no other component in the library needs:
// TDLib is a native library, so say where it is when it is
// not already beside the executable.
SetTDJsonPath(ExtractFilePath(ParamStr(0)));
sgcTelegram.Telegram.API.ApiId := GetApiId;
sgcTelegram.Telegram.API.ApiHash := GetApiHash;
sgcTelegram.Telegram.PhoneNumber := '+34600000000';
sgcTelegram.Active := True;
end;代わりにボットとしてサインインする場合は、PhoneNumber を空にして Telegram.BotToken を設定します。そこからの認可はイベント駆動です。OnAuthorizationStatus、OnAuthenticationCode、OnAuthenticationPassword が、TDLib が次に必要とするものを尋ねます。
最初の 2 つのタブは、同梱のデモ Demos\50.Other\05.WhatsApp\FWhatsApp.pas から、フォームコントロールをリテラルに置き換えたものです。そのデモの送信ボタンは実際には SendMessageLocation を呼び出します。ここに示したテキストの呼び出しは、同じファイルの SendMessageText の経路です。Telegram のタブは、ライブラリ内の他のすべてのコンポーネントと異なる 1 行を示しています。
2 段階の確認があります。送信呼び出しが返すものと、その後にウェブフックが伝えるものです。
SendMessageText は Graph API のレスポンス本文を string として返します。ログに記録してください。Meta からのエラーは例外ではなくその本文で届くため、何も起きていないように見える送信でも、その説明がたいていそこにあります。
OnMessageSentメッセージのその後の状況を、不明から送信済み、配信済み、既読へと遷移するステータス値で報告します。ステータスはインバウンドのコールバックとして届くため、ウェブフックサーバーが動作している必要があります。
OnMessageReceivedprocedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean)。aMarkAsRead を設定するとメッセージを確認済みにでき、送信者の画面に青いチェックマークが表示されます。
注目すべきは OnConnectionStatus と OnAuthorizationStatus の 2 つです。TDLib は複数のステップでサインインするため、ステータスイベントがその手順のどこにいるかを確実に知る唯一の方法です。
最初の送信が失敗する原因のほとんどは、6 つの問題のいずれかです。
TsgcWhatsApp_Client は SGC_WHATSAPP が定義されている場合のみコンパイルされ、それは Professional ブロック内の 728 行目で行われます。Standard ビルドでは Telegram は使えますが、WhatsApp は使えません。
WhatsApp では、ユーザーが先にメッセージを送ったときに開くカスタマーサービスウィンドウの内側でのみ、自由形式のテキストメッセージが許可されています。その外では、承認済みのテンプレートを送信する必要があり、それは SendMessageText ではなく SendMessageTemplate です。
戻り値を読み取ってください。SendMessageText は Graph API の生のレスポンスを文字列として返し、デモはそれを直接ログに記録しています。Meta からのエラーはその本文で返ってきます。
Meta コンソールの一時トークンは有効期間が短いものです。サンプルを卒業する前に、システムユーザー用の永続トークンを生成してください。
TDLib が見つかりませんでした。コンポーネントは実行時に dlopen または LoadLibrary で読み込み、失敗すると例外を発生させます。ファイルを実行ファイルの隣に置くか、SetTDJsonPath で検索パスを設定してください。
デモはフォームを直接操作できるように NotifyEvents := neAsynchronous を設定しており、そのコメントにも、本番環境では neNoSync を使い、UI スレッドへのマーシャリングは自分で行うよう書かれています。
作業が向かいやすい 4 つの方向があり、いずれも同じパッケージの中にあります。
画像、ドキュメント、位置情報、連絡先、インタラクティブなボタンメッセージ、承認済みテンプレートには、それぞれ同じコンポーネントに専用の送信メソッドがあります。
コンポーネント自体でウェブフックのエンドポイントをホストできます。StartServer で起動し、OnBeforeSubscribe で検証ハンドシェイクを受け入れるか拒否し、OnMessageReceived が受信した各メッセージを渡します。
TDLib は公式の Telegram クライアントが使用しているのと同じライブラリであるため、コンポーネントはボット API だけでなく、ユーザーアカウント、チャット、メディア、スポンサーメッセージにも対応します。
リファレンスページには、すべてのメソッドとイベントが記載されています。デモプロジェクトはダウンロードに含まれており、Demos\50.Other の下にあります。
リファレンス、WhatsApp クライアント
TsgcWhatsApp_Client のすべての送信メソッド、オプション、イベント。
|
開く | |
リファレンス、Telegram クライアント
TsgcTDLib_Telegram の認可、チャット、メッセージ、メディア。
|
開く | |
| TsgcWhatsApp_Client コンポーネントのページ すべての送信メソッドとイベントがあり、Telegram クライアントへのリンクもあります。 | 開く | |
| 体験版のダウンロード 製品版と同じインストーラーで、期間限定です。 | 開く | |
| オンラインヘルプ 自動生成されたリファレンスで、常に最新リリースに対応しています。 | 開く | |
| ユーザーマニュアル (PDF) ライブラリ内のすべてのコンポーネントを網羅した完全なマニュアルです。 | 開く |
関連資料：WhatsApp コンポーネント、WhatsApp でローカルファイルを送信する、Telegram クライアント、プロキシ経由の Telegram。各製品にはそれぞれクイックスタートがあり、はじめにのページに一覧があります。
TsgcWhatsApp_Client です。sgcLibs.pas で、sgcLib_WhatsApp_Client.pas で宣言され送信メソッドを持つ TsgcWhatsApp_Client_Base の公開ラッパーとして宣言されています。WhatsAppOptions.PhoneNumberId と WhatsAppOptions.Token を設定してから、SendMessageText を呼び出します。
sgcVer.inc の 728 行目で定義されている SGC_WHATSAPP で制御されます。これは 727 行目から 758 行目までの SGC_EDT_PRO ブロックの最初の行で、Professional 以上です。Telegram は SGC_TELEGRAM で制御され、675 行目から 724 行目の SGC_EDT_STD ブロック内の 677 行目から 694 行目で、プラットフォームごとに 1 回ずつ、計 6 回定義されます。そのため Telegram は 1 段階下のエディションから使えます。単独の sgcSocial パッケージは、860 行目の SGC_PACK_SOCIAL を通じて両方を有効にし、968 行目から 971 行目のそのブロックは、プラットフォームガードなしで両方を定義します。
string で、Meta Graph API の生のレスポンス本文です。完全なシグネチャは function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string です。同梱のデモは戻り値を直接ログに記録しており、拒否された送信は例外ではなく本文で返ってくるため、Meta からのエラーを確認する最速の方法です。
StartServer を呼び出すと、Meta のウェブフックを自分で待ち受けます。OnBeforeSubscribe で検証リクエストを受け入れるか拒否でき、OnMessageReceived は受信した各メッセージと、確認済みにするために設定できる var aMarkAsRead フラグを渡します。StopServer で停止します。送信にはこれらは一切不要です。
tdjson.dll、macOS 64 ビットでは libtdjson.dylib、Linux 64 ビットと Lazarus Linux では libtdjson.so、Android では libtdjsonandroid.so です。iOS 64 は例外で、ライブラリは libtdjson.a として静的にリンクされます。見つからない場合、コンポーネントは初回の使用時に例外を発生させます。SetTDJsonPath で別のフォルダーを指定できます。
SendMessageImage、SendMessageDocument、SendMessageLocation、SendMessageContact、SendMessageInteractiveButtons、およびオーバーロードされた SendMessageTemplate です。MarkMessageRead は受信メッセージを既読にします。
NotifyEvents := neAsynchronous を設定しており、そのコメントにも、本番環境では neNoSync を使うよう書かれています。neNoSync ではイベントがワーカースレッドで発生します。これはサービスにとっては高速で正しい動作ですが、UI に触れる処理はすべて自分でマーシャリングする必要があります。
sgcVer.inc の 860 行目の SGC_PACK_SOCIAL で、968 行目から 971 行目のそのブロックが両方のクライアントを定義します。