sgcSocial w pięć minut

W tym pakiecie są dwaj klienci komunikatorów: WhatsApp Business Cloud i Telegram na oficjalnym TDLib. WhatsApp to krótsza droga, ponieważ jest to czyste HTTPS bez niczego do wdrożenia, więc ta strona najpierw wysyła wiadomość tekstową WhatsApp, a potem mówi, czego dodatkowo potrzebuje Telegram.

WhatsApp Business Cloud API
Telegram na oficjalnym TDLib
WhatsApp od Professional, Telegram od Standard
W skrócie

Czego potrzebuje pierwsza wiadomość

Jeden komponent, dwie wartości z twojej aplikacji Meta i jedno wywołanie metody, które zwraca odpowiedź API jako tekst.

Komponent

TsgcWhatsApp_Client na stronie palety SGC Social, zadeklarowany w sgcLibs.pas jako opublikowana nakładka na TsgcWhatsApp_Client_Base.

Dwie potrzebne wartości

WhatsAppOptions.PhoneNumberId i WhatsAppOptions.Token, obie pobrane z twojej aplikacji deweloperskiej Meta. Do wysyłania nic więcej nie jest wymagane.

Wywołanie

SendMessageText(aTo, aMessage) zwraca string, czyli surową treść odpowiedzi z Meta Graph API. Zapisz ją w logu, a od razu zobaczysz, czy wysyłka została przyjęta.

Telegram jest inny

TsgcTDLib_Telegram opakowuje oficjalny TDLib, więc potrzebuje natywnej biblioteki obok twojego pliku wykonywalnego. To jedyny dodatkowy krok, a tabela poniżej podaje nazwę pliku dla każdej platformy.

Zanim zaczniesz

Wymagania i edycje

Kolumna edycji to define, który ogranicza każdego klienta, wraz z linią w Source/sgcVer.inc, w której się znajduje.

Co Wartość
IDE Od Delphi 7 do RAD Studio 13 oraz od C++Builder 2007 do 13.
Klauzula uses sgcLibs dla klas palety. Demo dodaje sgcLib_WhatsApp_Client dla opcji i typów wiadomości.
Edycja WhatsApp SGC_WHATSAPP jest zdefiniowany w linii 728, pierwszej linii wewnątrz bloku {$IFDEF SGC_EDT_PRO}, który biegnie od linii 727 do linii 758. Czyli Professional i wyższe.
Edycja Telegram SGC_TELEGRAM jest zdefiniowany w liniach 677, 680, 683, 687, 691 i 694, wszystkich wewnątrz bloku {$IFDEF SGC_EDT_STD}, który biegnie od linii 675 do linii 724. Sześć linii, ponieważ każda jest ograniczona platformą. Czyli Standard i wyższe, na wymienionych tam platformach.
Edycja, samodzielny pakiet Produkt sgcSocial definiuje SGC_PACK_SOCIAL w linii 860, a jego własny blok w liniach 968 do 971 definiuje SGC_TELEGRAM w linii 969 i SGC_WHATSAPP w linii 970. Ci sami dwaj klienci, bez reszty biblioteki.
Platformy WhatsApp Brak natywnej zależności i brak warunku platformy. To HTTPS do Meta Graph API, więc działa każdy cel, który ma zaplecze TLS.
Platformy Telegram Wymaga biblioteki TDLib JSON obok pliku binarnego: tdjson.dll w systemie Windows, libtdjson.dylib w macOS 64 bit, libtdjson.so w Linuksie 64 bit i w Lazarus Linux, libtdjsonandroid.so na Androidzie. W iOS 64 biblioteka jest linkowana statycznie jako libtdjson.a, zamiast ładowana w czasie działania.

Testowy numer WhatsApp Business Cloud, stały token i identyfikator numeru telefonu pochodzą z konsoli deweloperskiej Meta. Komponent żadnego z nich nie tworzy za ciebie.

Krok 1

Zainstaluj i znajdź stronę palety

sgcSocial jest dostarczany w instalatorze sgcWebSockets, a także jako osobny pakiet. Instalacja wygląda w obu przypadkach tak samo.

1. Rozpakuj

Rozpakuj pobrany plik do folderu, który poniżej nazywamy {$DIR}.

2. Ścieżka biblioteki

Tools, Options, Library. Dodaj {$DIR}\source oraz folder lib dla swojego IDE, na przykład {$DIR}\libD13\$(Platform).

3. Zbuduj pakiety

Otwórz grupę pakietów dla swojej wersji IDE w {$DIR}\Packages\. Najpierw skompiluj uruchomieniowy .dpk, a potem zainstaluj ten czasu projektowania z prefiksem dcl.

4. Sprawdź paletę

Pojawia się strona o nazwie SGC Social. W kompilacji Standard zawiera TsgcTDLib_Telegram. W Professional i wyższych zawiera także TsgcWhatsApp_Client.

5. Tylko dla Telegrama, dołącz TDLib

Skopiuj bibliotekę TDLib JSON dla swojej platformy obok pliku wykonywalnego. Dostarczane demo Telegrama ma w folderze tdjson.dll razem z libcrypto-3.dll, libssl-3.dll i zlib1.dll, czyli zestaw potrzebny w systemie Windows.

QuickStart

Wyślij wiadomość WhatsApp w około dziesięciu linijkach

Ustaw identyfikator numeru telefonu i token, wywołaj SendMessageText i odczytaj odpowiedź, którą odesłało Graph API.

FWhatsApp.pas 
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;

To cała ścieżka wysyłania. Nic więcej nie trzeba konfigurować i nie musi działać żaden serwer. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons i SendMessageTemplate mają ten sam kształt.

FWhatsApp.pas 
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;

Odbieranie jest opcjonalne. StopServer ponownie zamyka nasłuch, a w OnBeforeSubscribe przyjmujesz lub odrzucasz żądanie weryfikacji Meta przez parametr var Accept: Boolean.

uTelegram.pas 
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;

Aby zalogować się jako bot, zostaw PhoneNumber puste i ustaw Telegram.BotToken. Stąd autoryzacja jest sterowana zdarzeniami: OnAuthorizationStatus, OnAuthenticationCode i OnAuthenticationPassword proszą cię o to, czego TDLib potrzebuje dalej.

Pierwsze dwie karty to dostarczane demo Demos\50.Other\05.WhatsApp\FWhatsApp.pas, z kontrolkami formularza zastąpionymi literałami. Przycisk wysyłania w tym demie wywołuje w rzeczywistości SendMessageLocation; pokazane tu wywołanie tekstowe to ścieżka SendMessageText z tego samego pliku. Karta Telegram pokazuje jedną linijkę, która różni się od każdego innego komponentu w bibliotece.

Krok 2

Sprawdź, czy wiadomość została przyjęta

Dwa poziomy dowodu: co zwraca wywołanie wysyłki i co potem mówi webhook.

Wartość zwracana

SendMessageText zwraca treść odpowiedzi Graph API jako string. Zapisz ją w logu. Błąd od Meta przychodzi w tej treści, a nie jako wyjątek, więc wysyłka, która wydaje się nic nie robić, zwykle ma tam swoje wyjaśnienie.

OnMessageSent

Raportuje, co później stało się z wiadomością, przez wartość statusu przechodzącą od nieznanego do wysłanego, dostarczonego i przeczytanego. Wymaga uruchomionego serwera webhooka, ponieważ status przychodzi jako wywołanie zwrotne.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Ustaw aMarkAsRead, aby potwierdzić wiadomość, co powoduje niebieskie ptaszki na ekranie nadawcy.

Telegram

OnConnectionStatus i OnAuthorizationStatus to dwa zdarzenia do obserwowania. TDLib loguje się w kilku krokach, więc zdarzenia statusu są jedynym niezawodnym sposobem, by wiedzieć, w którym miejscu tej sekwencji jesteś.

Typowe problemy

Co zwykle idzie nie tak za pierwszym razem

Sześć problemów odpowiada za niemal każdą nieudaną pierwszą wysyłkę.

Komponentu nie ma na palecie

TsgcWhatsApp_Client jest kompilowany tylko wtedy, gdy zdefiniowano SGC_WHATSAPP, co dzieje się w linii 728 wewnątrz bloku Professional. W kompilacji Standard dostajesz Telegram, a nie WhatsApp.

Wysyłka zwraca błąd dotyczący szablonu

WhatsApp dopuszcza swobodną wiadomość tekstową tylko w oknie obsługi klienta, które otwiera się, gdy użytkownik napisze do ciebie pierwszy. Poza nim musisz wysłać zatwierdzony szablon, czyli SendMessageTemplate, a nie SendMessageText.

Nic nie dociera i nie jest zgłaszany żaden błąd

Odczytaj wartość zwracaną. SendMessageText zwraca surową odpowiedź Graph API jako tekst, a demo zapisuje ją bezpośrednio w logu. Błąd od Meta wraca w tej treści.

Token wygasa po dniu

Tymczasowy token w konsoli Meta jest krótkotrwały. Wygeneruj stały token dla użytkownika systemowego, zanim zostawisz przykład za sobą.

Telegram zgłasza błąd biblioteki przy starcie

Nie znaleziono TDLib. Komponent ładuje go w czasie działania przez dlopen lub LoadLibrary i zgłasza wyjątek, gdy się to nie uda. Umieść plik obok pliku wykonywalnego albo ustaw ścieżkę wyszukiwania przez SetTDJsonPath.

Zdarzenia wywoływane w złym wątku

Demo ustawia NotifyEvents := neAsynchronous, aby mogło bezpośrednio dotykać formularza, a jego własny komentarz mówi, by w produkcji użyć neNoSync i samodzielnie przekazywać wywołania do wątku interfejsu.

Zgłęb temat

Poza pierwszą wiadomością

Cztery kierunki, w które zwykle idzie praca, wszystkie w tym samym pakiecie.

Bogatsze wiadomości WhatsApp

Obrazy, dokumenty, lokalizacje, kontakty, wiadomości z interaktywnymi przyciskami i zatwierdzone szablony mają każde własną metodę wysyłania w tym samym komponencie.

Dokumentacja WhatsApp

Odbieraj, nie tylko wysyłaj

Komponent może sam hostować punkt końcowy webhooka. StartServer go uruchamia, OnBeforeSubscribe przyjmuje lub odrzuca uzgadnianie weryfikacji, a OnMessageReceived przekazuje ci każdą przychodzącą wiadomość.

Dokumentacja WhatsApp

Pełne aplikacje Telegram, nie tylko boty

TDLib to ta sama biblioteka, której używają oficjalni klienci Telegrama, więc komponent sięga do kont użytkowników, czatów, multimediów i wiadomości sponsorowanych, a nie tylko do API botów.

Dokumentacja Telegram

Status dostarczenia

OnMessageSent raportuje postęp wysłanej wiadomości przez stany zdefiniowane przez API: nieznany, wysłany, dostarczony i przeczytany.

Dokumentacja WhatsApp

Zasoby

Dokumentacja, dema i materiały

Strony referencyjne opisują każdą metodę i zdarzenie. Projekty demo znajdują się w pobranym pakiecie, w Demos\50.Other.

Dokumentacja, klient WhatsApp Każda metoda wysyłania, opcja i zdarzenie TsgcWhatsApp_Client. Otwórz
Dokumentacja, klient Telegram Autoryzacja, czaty, wiadomości i multimedia w TsgcTDLib_Telegram. Otwórz
Strona komponentu TsgcWhatsApp_Client Każda metoda wysyłania i zdarzenie, z odnośnikiem do klienta Telegram. Otwórz
Pobierz wersję próbną Ten sam instalator co w wersji produkcyjnej, z ograniczeniem czasowym. Otwórz
Pomoc online Generowana dokumentacja, zawsze zgodna z bieżącym wydaniem. Otwórz
Podręcznik użytkownika (PDF) Pełny podręcznik obejmujący każdy komponent biblioteki. Otwórz

Powiązane lektury: komponent WhatsApp, wysyłanie plików lokalnych przez WhatsApp, klient Telegram i Telegram za proxy. Każdy produkt ma własny szybki start, wymieniony na stronie pierwszych kroków.

FAQ

Pytania o szybki start sgcSocial

TsgcWhatsApp_Client, na stronie palety SGC Social. Jest zadeklarowany w sgcLibs.pas jako opublikowana nakładka na TsgcWhatsApp_Client_Base, który jest zadeklarowany w sgcLib_WhatsApp_Client.pas i zawiera metody wysyłania. Ustaw WhatsAppOptions.PhoneNumberId i WhatsAppOptions.Token, a następnie wywołaj SendMessageText.
WhatsApp jest ograniczony przez SGC_WHATSAPP, zdefiniowany w linii 728 pliku sgcVer.inc, pierwszej linii bloku SGC_EDT_PRO, który biegnie od linii 727 do linii 758. To Professional i wyższe. Telegram jest ograniczony przez SGC_TELEGRAM, zdefiniowany sześć razy w liniach 677 do 694 wewnątrz bloku SGC_EDT_STD, linie 675 do 724, raz na platformę. Telegram zaczyna się więc o jeden poziom niżej. Samodzielny pakiet sgcSocial włącza oba przez SGC_PACK_SOCIAL, linia 860, którego blok w liniach 968 do 971 definiuje je bez warunku platformy.
string, czyli surową treść odpowiedzi z Meta Graph API. Pełna sygnatura to function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. Dostarczane demo zapisuje wartość zwracaną bezpośrednio w logu i to najszybszy sposób, by zobaczyć błąd od Meta, ponieważ odrzucona wysyłka wraca w treści, a nie jako wyjątek.
Serwerem może być sam komponent. Wywołaj StartServer, a sam nasłuchuje webhooka Meta. OnBeforeSubscribe pozwala przyjąć lub odrzucić żądanie weryfikacji, a OnMessageReceived daje ci każdą przychodzącą wiadomość oraz flagę var aMarkAsRead, którą możesz ustawić, by ją potwierdzić. StopServer go zamyka. Wysyłanie nie wymaga niczego z tego.
Natywnej biblioteki TDLib JSON obok pliku wykonywalnego. Komponent ładuje ją w czasie działania i nazywa według platformy: tdjson.dll w systemie Windows, libtdjson.dylib w macOS 64 bit, libtdjson.so w Linuksie 64 bit i w Lazarus Linux oraz libtdjsonandroid.so na Androidzie. Wyjątkiem jest iOS 64, gdzie biblioteka jest linkowana statycznie jako libtdjson.a. Jeśli jej brakuje, komponent zgłasza wyjątek przy pierwszym użyciu. SetTDJsonPath wskazuje inny folder.
Tak, każde ma własną metodę w tym samym komponencie: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons i SendMessageTemplate, która jest przeciążona. MarkMessageRead oznacza przychodzącą wiadomość jako przeczytaną.
Z powodu trybu wątkowania. Dostarczane demo ustawia NotifyEvents := neAsynchronous, aby jego procedury obsługi mogły dotykać kontrolek VCL, a jego własny komentarz mówi, by w produkcji użyć neNoSync. Przy neNoSync zdarzenie jest wywoływane w wątku roboczym, co jest szybsze i poprawne dla usługi, a przekazywanie wszystkiego, co dotyka interfejsu, staje się twoim zadaniem.
Tak. To samodzielny pakiet z dołączonym środowiskiem uruchomieniowym sgcWebSockets Core, a jest też częścią sgcWebSockets od Professional w górę dla WhatsApp i od Standard w górę dla Telegrama. W źródłach droga samodzielna to SGC_PACK_SOCIAL w linii 860 pliku sgcVer.inc, którego blok w liniach 968 do 971 definiuje obu klientów.
Najkorzystniejsza oferta: All-AccessWszystkie produkty eSeGeCe, ze wsparciem Premium w cenie, już od €1,059 rocznie.
Zobacz cennik All-Access

Gotowy pisać do klientów z Delphi?

Pobierz wersję próbną i wyślij swoją pierwszą wiadomość WhatsApp już dziś.

Pobierz bezpłatną wersję próbną Zobacz cennik