이 패키지에는 메시징 클라이언트가 두 개 들어 있어요. WhatsApp Business Cloud와 공식 TDLib 기반의 Telegram이에요. WhatsApp은 배포할 것이 없는 순수 HTTPS라서 더 빠르게 시작할 수 있어요. 그래서 이 페이지에서는 먼저 WhatsApp 텍스트 메시지를 보내고, 그다음 Telegram에 추가로 필요한 것을 알려 드려요.
컴포넌트 하나, Meta 앱에서 가져온 값 두 개, 그리고 API 응답을 문자열로 반환하는 메서드 호출 하나가 필요해요.
SGC Social 팔레트 페이지의 TsgcWhatsApp_Client이며, sgcLibs.pas에서 TsgcWhatsApp_Client_Base를 감싼 published 래퍼로 선언되어 있어요.
WhatsAppOptions.PhoneNumberId와 WhatsAppOptions.Token이며, 둘 다 Meta 개발자 앱에서 가져와요. 보내는 데 그 외에는 아무것도 필요 없어요.
SendMessageText(aTo, aMessage)는 Meta Graph API의 원시 응답 본문인 string을 반환해요. 로그로 남기면 전송이 수락되었는지 바로 알 수 있어요.
TsgcTDLib_Telegram은 공식 TDLib을 감싸므로 실행 파일 옆에 네이티브 라이브러리가 필요해요. 추가 단계는 이것 하나뿐이며, 아래 표에 플랫폼별 파일 이름이 나와 있어요.
에디션 열은 각 클라이언트를 제어하는 define이며, Source/sgcVer.inc에서 그 define이 있는 줄 번호도 함께 적었어요.
| 항목 | 값 |
|---|---|
| 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} 블록 안에 있어요. 줄이 여섯 개인 것은 각각이 플랫폼별로 가드되어 있기 때문이에요. 따라서 거기에 나열된 플랫폼에서 Standard 이상이에요. |
| 에디션, 독립 패키지 | sgcSocial 제품은 860번째 줄에서 SGC_PACK_SOCIAL을 정의하고, 968번째 줄부터 971번째 줄까지의 자체 블록이 969번째 줄에서 SGC_TELEGRAM을, 970번째 줄에서 SGC_WHATSAPP을 정의해요. 라이브러리의 나머지 부분 없이 같은 클라이언트 두 개를 쓸 수 있어요. |
| WhatsApp 플랫폼 | 네이티브 의존성도 플랫폼 가드도 없어요. Meta Graph API로 가는 HTTPS이므로 TLS 백엔드가 있는 모든 대상에서 동작해요. |
| Telegram 플랫폼 | 바이너리 옆에 TDLib JSON 라이브러리가 필요해요. Windows에서는 tdjson.dll, 64비트 macOS에서는 libtdjson.dylib, 64비트 Linux와 Lazarus Linux에서는 libtdjson.so, Android에서는 libtdjsonandroid.so예요. iOS 64에서는 런타임에 로드하는 대신 libtdjson.a로 정적 링크해요. |
WhatsApp Business Cloud 테스트 번호, 영구 토큰, 전화번호 ID는 모두 Meta 개발자 콘솔에서 얻어요. 컴포넌트가 대신 만들어 주는 것은 없어요.
sgcSocial은 sgcWebSockets 설치 프로그램에 들어 있고 독립 패키지로도 제공돼요. 어느 쪽이든 설치 방식은 같아요.
다운로드한 파일을 폴더에 압축 해제하세요. 아래에서는 이 폴더를 {$DIR}이라고 불러요.
Tools, Options, Library로 이동해요. {$DIR}\source와 사용하는 IDE의 lib 폴더를 추가하세요. 예를 들면 {$DIR}\libD13\$(Platform)이에요.
{$DIR}\Packages\ 아래에서 IDE 버전에 맞는 패키지 그룹을 여세요. 런타임 .dpk를 먼저 컴파일하고 그다음 디자인 타임 dcl 패키지를 설치해요.
SGC Social 페이지가 나타나요. Standard 빌드에는 TsgcTDLib_Telegram이 들어 있어요. Professional 이상에는 TsgcWhatsApp_Client도 들어 있어요.
플랫폼에 맞는 TDLib JSON 라이브러리를 실행 파일 옆에 복사하세요. 포함된 Telegram 데모 폴더에는 tdjson.dll이 libcrypto-3.dll, libssl-3.dll, zlib1.dll과 함께 들어 있으며, Windows에 필요한 구성이 바로 이거예요.
전화번호 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이 다음에 필요로 하는 것을 요청해요.
처음 두 탭은 포함된 데모 Demos\50.Other\05.WhatsApp\FWhatsApp.pas이며 폼 컨트롤은 리터럴로 바꿨어요. 그 데모의 전송 버튼은 실제로는 SendMessageLocation을 호출하고, 여기에 보인 텍스트 호출은 같은 파일의 SendMessageText 경로예요. Telegram 탭은 라이브러리의 다른 모든 컴포넌트와 다른 단 한 줄을 보여 줘요.
두 단계로 확인해요. 전송 호출이 반환하는 값, 그리고 이후에 웹훅이 알려 주는 내용이에요.
SendMessageText는 Graph API 응답 본문을 string으로 반환해요. 로그로 남기세요. Meta의 오류는 예외가 아니라 그 본문으로 도착하므로, 아무 일도 안 한 것 같은 전송의 설명은 대개 거기에 있어요.
OnMessageSent메시지에 이후 무슨 일이 있었는지 알려 줘요. 상태 값은 unknown에서 sent, delivered, read로 바뀌어요. 상태가 인바운드 콜백으로 도착하므로 웹훅 서버가 실행 중이어야 해요.
OnMessageReceivedprocedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). aMarkAsRead를 설정하면 메시지를 확인 처리하며, 보낸 사람의 화면에 파란 체크 표시가 나타나요.
지켜봐야 할 이벤트는 OnConnectionStatus와 OnAuthorizationStatus예요. TDLib은 여러 단계에 걸쳐 로그인하므로, 그 순서에서 지금 어디에 있는지 알 수 있는 믿을 만한 방법은 상태 이벤트뿐이에요.
실패한 첫 전송은 거의 다 여섯 가지 문제 중 하나가 원인이에요.
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 스레드로 직접 마샬링하라고 적혀 있어요.
작업이 보통 향하는 네 가지 방향이 있고, 모두 같은 패키지 안에 있어요.
컴포넌트가 웹훅 엔드포인트를 직접 호스팅할 수 있어요. StartServer가 시작하고, OnBeforeSubscribe가 검증 핸드셰이크를 수락하거나 거부하며, OnMessageReceived가 들어오는 메시지를 하나씩 전달해요.
TDLib은 공식 Telegram 클라이언트가 쓰는 것과 같은 라이브러리라서, 컴포넌트는 봇 API뿐 아니라 사용자 계정, 채팅, 미디어, 스폰서 메시지에도 접근할 수 있어요.
OnMessageSent는 API가 정의한 상태인 unknown, sent, delivered, read를 통해 보낸 메시지의 진행 상황을 알려 줘요.
레퍼런스 페이지에는 모든 메서드와 이벤트가 문서화되어 있어요. 데모 프로젝트는 다운로드 안의 Demos\50.Other 아래에 있어요.
레퍼런스, WhatsApp 클라이언트
TsgcWhatsApp_Client의 모든 전송 메서드, 옵션, 이벤트.
|
열기 | |
레퍼런스, Telegram 클라이언트
TsgcTDLib_Telegram의 인증, 채팅, 메시지, 미디어.
|
열기 | |
| TsgcWhatsApp_Client 컴포넌트 페이지 모든 전송 메서드와 이벤트, 그리고 여기서 연결되는 Telegram 클라이언트. | 열기 | |
| 체험판 다운로드 정식 버전과 같은 설치 프로그램이며 기간 제한이 있어요. | 열기 | |
| 온라인 도움말 자동 생성된 레퍼런스로, 항상 최신 릴리스와 일치해요. | 열기 | |
| 사용자 설명서 (PDF) 라이브러리의 모든 컴포넌트를 다루는 전체 설명서. | 열기 |
함께 읽어 보세요. WhatsApp 컴포넌트, WhatsApp으로 로컬 파일 보내기, Telegram 클라이언트, 프록시 뒤의 Telegram. 모든 제품에는 각자의 빠른 시작이 있으며, 시작하기 페이지에서 모아 볼 수 있어요.
TsgcWhatsApp_Client예요. sgcLibs.pas에서 TsgcWhatsApp_Client_Base를 감싼 published 래퍼로 선언되어 있고, 전송 메서드를 제공하는 TsgcWhatsApp_Client_Base는 sgcLib_WhatsApp_Client.pas에 선언되어 있어요. 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번째 줄 사이에 플랫폼마다 한 번씩 여섯 번 정의돼요. 그래서 Telegram은 한 단계 낮은 등급부터 시작해요. 독립 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, 64비트 macOS에서는 libtdjson.dylib, 64비트 Linux와 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번째 줄까지의 블록이 두 클라이언트를 모두 정의해요.