sgcSocial in fünf Minuten

Dieses Paket enthält zwei Messaging-Clients: WhatsApp Business Cloud und Telegram auf der offiziellen TDLib. WhatsApp ist der kürzere Weg, denn es ist reines HTTPS und nichts muss ausgeliefert werden. Diese Seite sendet daher zuerst eine WhatsApp-Textnachricht und sagt dir danach, was Telegram zusätzlich braucht.

WhatsApp Business Cloud API
Telegram auf der offiziellen TDLib
WhatsApp ab Professional, Telegram ab Standard
Auf einen Blick

Was die erste Nachricht benötigt

Eine Komponente, zwei Werte aus deiner Meta-App und ein Methodenaufruf, der die API-Antwort als String zurückgibt.

Komponente

TsgcWhatsApp_Client auf der Palettenseite SGC Social, deklariert in sgcLibs.pas als veröffentlichter Wrapper um TsgcWhatsApp_Client_Base.

Die zwei Werte, die du brauchst

WhatsAppOptions.PhoneNumberId und WhatsAppOptions.Token, beide aus deiner Meta-Entwickler-App. Mehr ist zum Senden nicht erforderlich.

Der Aufruf

SendMessageText(aTo, aMessage) liefert einen string, den rohen Antwort-Body der Meta Graph API. Protokolliere ihn, und du siehst sofort, ob der Versand akzeptiert wurde.

Telegram ist anders

TsgcTDLib_Telegram kapselt die offizielle TDLib und braucht daher die native Bibliothek neben deiner ausführbaren Datei. Das ist der eine zusätzliche Schritt, und die Tabelle unten nennt die Datei je Plattform.

Bevor du startest

Voraussetzungen und Editionen

Die Editionsspalte nennt das Define, das jeden Client steuert, samt der Zeile in Source/sgcVer.inc, in der es steht.

Was Wert
IDE Delphi 7 bis RAD Studio 13 sowie C++Builder 2007 bis 13.
Uses-Klausel sgcLibs für die Palettenklassen. Die Demo ergänzt sgcLib_WhatsApp_Client für die Options- und Nachrichtentypen.
WhatsApp-Edition SGC_WHATSAPP wird in Zeile 728 definiert, der ersten Zeile im Block {$IFDEF SGC_EDT_PRO}, der von Zeile 727 bis Zeile 758 reicht. Also Professional und höher.
Telegram-Edition SGC_TELEGRAM wird in den Zeilen 677, 680, 683, 687, 691 und 694 definiert, alle innerhalb des Blocks {$IFDEF SGC_EDT_STD}, der von Zeile 675 bis Zeile 724 reicht. Sechs Zeilen, weil jede durch eine Plattform abgesichert ist. Also Standard und höher, auf den dort aufgeführten Plattformen.
Edition, eigenständiges Paket Das Produkt sgcSocial definiert SGC_PACK_SOCIAL in Zeile 860, und sein eigener Block in den Zeilen 968 bis 971 definiert SGC_TELEGRAM in Zeile 969 und SGC_WHATSAPP in Zeile 970. Dieselben zwei Clients, ohne den Rest der Bibliothek.
WhatsApp-Plattformen Keine native Abhängigkeit und kein Plattform-Guard. Es ist HTTPS zur Meta Graph API, daher funktioniert jedes Ziel, das ein TLS-Backend hat.
Telegram-Plattformen Braucht die TDLib-JSON-Bibliothek neben der Binärdatei: tdjson.dll unter Windows, libtdjson.dylib unter macOS 64 Bit, libtdjson.so unter Linux 64 Bit und unter Lazarus Linux, libtdjsonandroid.so unter Android. Unter iOS 64 wird die Bibliothek statt zur Laufzeit geladen statisch als libtdjson.a gelinkt.

Eine WhatsApp-Business-Cloud-Testnummer, ein permanentes Token und eine Telefonnummern-ID stammen alle aus der Meta-Entwicklerkonsole. Die Komponente erstellt dir nichts davon.

Schritt 1

Installieren und die Palettenseite finden

sgcSocial wird im sgcWebSockets-Installer und auch als eigenes Paket ausgeliefert. Die Installation läuft in beiden Fällen gleich ab.

1. Entpacken

Entpacke den Download in einen Ordner, unten {$DIR} genannt.

2. Bibliothekspfad

Tools, Optionen, Bibliothek. Füge {$DIR}\source und den lib-Ordner für deine IDE hinzu, zum Beispiel {$DIR}\libD13\$(Platform).

3. Pakete erstellen

Öffne die Paketgruppe für deine IDE-Version unter {$DIR}\Packages\. Kompiliere zuerst das Laufzeit-.dpk und installiere dann das Entwurfszeitpaket mit dcl.

4. Palette prüfen

Es erscheint eine Seite namens SGC Social. In einem Standard-Build enthält sie TsgcTDLib_Telegram. Ab Professional enthält sie zusätzlich TsgcWhatsApp_Client.

5. Nur für Telegram: TDLib ausliefern

Kopiere die TDLib-JSON-Bibliothek für deine Plattform neben die ausführbare Datei. Die mitgelieferte Telegram-Demo hat tdjson.dll zusammen mit libcrypto-3.dll, libssl-3.dll und zlib1.dll in ihrem Ordner, das ist der Satz, den Windows braucht.

QuickStart

Eine WhatsApp-Nachricht senden, in etwa zehn Zeilen

Setze die Telefonnummern-ID und das Token, rufe SendMessageText auf und lies die Antwort, die die Graph API zurückgeschickt hat.

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;

Das ist der gesamte Sendeweg. Sonst muss nichts konfiguriert werden, und es muss kein Server laufen. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons und SendMessageTemplate haben dieselbe Form.

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;

Der Empfang ist optional. StopServer fährt den Listener wieder herunter, und in OnBeforeSubscribe akzeptierst oder lehnst du die Verifizierungsanfrage von Meta ab, über den Parameter 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;

Um dich stattdessen als Bot anzumelden, lass PhoneNumber leer und setze Telegram.BotToken. Von da an läuft die Autorisierung ereignisgesteuert: OnAuthorizationStatus, OnAuthenticationCode und OnAuthenticationPassword fragen dich nach dem, was TDLib als Nächstes braucht.

Die ersten beiden Tabs sind die mitgelieferte Demo Demos\50.Other\05.WhatsApp\FWhatsApp.pas, wobei die Formularsteuerelemente durch Literale ersetzt wurden. Die Sende-Schaltfläche dieser Demo ruft tatsächlich SendMessageLocation auf, der hier gezeigte Textaufruf ist der SendMessageText-Pfad derselben Datei. Der Telegram-Tab zeigt die eine Zeile, die sich von jeder anderen Komponente der Bibliothek unterscheidet.

Schritt 2

Prüfen, ob die Nachricht akzeptiert wurde

Zwei Ebenen des Belegs: was der Sendeaufruf zurückgibt und was dir der Webhook anschließend mitteilt.

Der Rückgabewert

SendMessageText liefert den Antwort-Body der Graph API als string. Protokolliere ihn. Ein Fehler von Meta kommt in diesem Body an und nicht als Exception, daher steht die Erklärung für einen scheinbar wirkungslosen Versand meist genau dort.

OnMessageSent

Meldet nachträglich, was mit einer Nachricht passiert ist, über einen Statuswert, der von unbekannt über gesendet und zugestellt zu gelesen wechselt. Es braucht den laufenden Webhook-Server, denn der Status trifft als eingehender Callback ein.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Setze aMarkAsRead, um die Nachricht zu bestätigen, wodurch die blauen Haken auf dem Bildschirm des Absenders erscheinen.

Telegram

OnConnectionStatus und OnAuthorizationStatus sind die beiden, die du beobachten solltest. TDLib meldet sich in mehreren Schritten an, daher sind die Statusereignisse der einzige verlässliche Weg zu wissen, wo du in dieser Abfolge stehst.

Häufige Probleme

Was beim ersten Mal meistens schiefgeht

Sechs Probleme erklären fast jeden fehlgeschlagenen ersten Versand.

Die Komponente fehlt in der Palette

TsgcWhatsApp_Client wird nur kompiliert, wenn SGC_WHATSAPP definiert ist, was in Zeile 728 innerhalb des Professional-Blocks geschieht. In einem Standard-Build bekommst du Telegram und nicht WhatsApp.

Der Versand liefert einen Fehler zu einer Vorlage

WhatsApp erlaubt eine Freitext-Nachricht nur innerhalb des Kundenservice-Fensters, das sich öffnet, wenn der Nutzer dir zuerst schreibt. Außerhalb davon musst du eine genehmigte Vorlage senden, also SendMessageTemplate und nicht SendMessageText.

Nichts kommt an und es wird kein Fehler ausgelöst

Lies den Rückgabewert. SendMessageText liefert die rohe Graph-API-Antwort als String, und die Demo protokolliert ihn direkt. Ein Fehler von Meta kommt in diesem Body zurück.

Das Token läuft nach einem Tag ab

Das temporäre Token in der Meta-Konsole ist kurzlebig. Erzeuge ein permanentes Token für einen Systembenutzer, bevor du das Beispiel hinter dir lässt.

Telegram löst beim Start einen Bibliotheksfehler aus

TDLib wurde nicht gefunden. Die Komponente lädt sie zur Laufzeit mit dlopen oder LoadLibrary und löst einen Fehler aus, wenn das scheitert. Lege die Datei neben deine ausführbare Datei oder setze den Suchpfad mit SetTDJsonPath.

Ereignisse werden im falschen Thread ausgelöst

Die Demo setzt NotifyEvents := neAsynchronous, damit sie das Formular direkt ansprechen kann, und ihr eigener Kommentar sagt, in der Produktion neNoSync zu verwenden und selbst in den UI-Thread zu marshallen.

Tiefer einsteigen

Über die erste Nachricht hinaus

Vier Richtungen, in die die Arbeit meist geht, alle im selben Paket.

Umfangreichere WhatsApp-Nachrichten

Bilder, Dokumente, Standorte, Kontakte, interaktive Button-Nachrichten und genehmigte Vorlagen haben jeweils ihre eigene Sendemethode in derselben Komponente.

WhatsApp-Referenz

Nicht nur senden, auch empfangen

Die Komponente kann den Webhook-Endpunkt selbst hosten. StartServer fährt ihn hoch, OnBeforeSubscribe akzeptiert oder lehnt den Verifizierungs-Handshake ab, und OnMessageReceived übergibt dir jede eingehende Nachricht.

WhatsApp-Referenz

Vollständige Telegram-Apps, nicht nur Bots

TDLib ist dieselbe Bibliothek, die die offiziellen Telegram-Clients verwenden, daher erreicht die Komponente Benutzerkonten, Chats, Medien und gesponserte Nachrichten und nicht nur die Bot-API.

Telegram-Referenz

Zustellstatus

OnMessageSent meldet den Fortschritt einer gesendeten Nachricht über die von der API definierten Zustände: unbekannt, gesendet, zugestellt und gelesen.

WhatsApp-Referenz

Ressourcen

Referenz, Demos und Dokumentation

Die Referenzseiten dokumentieren jede Methode und jedes Ereignis. Die Demo-Projekte liegen im Download unter Demos\50.Other.

Referenz, WhatsApp-Client Jede Sendemethode, Option und jedes Ereignis von TsgcWhatsApp_Client. Öffnen
Referenz, Telegram-Client Autorisierung, Chats, Nachrichten und Medien in TsgcTDLib_Telegram. Öffnen
Komponentenseite TsgcWhatsApp_Client Jede Sendemethode und jedes Ereignis, mit Verweis auf den Telegram-Client. Öffnen
Testversion herunterladen Derselbe Installer wie in der Vollversion, zeitlich begrenzt. Öffnen
Online-Hilfe Die generierte Referenz, stets auf dem Stand der aktuellen Version. Öffnen
Benutzerhandbuch (PDF) Das vollständige Handbuch zu jeder Komponente der Bibliothek. Öffnen

Zum Weiterlesen: die WhatsApp-Komponente, lokale Dateien über WhatsApp senden, der Telegram-Client und Telegram hinter einem Proxy. Jedes Produkt hat einen eigenen Schnellstart, aufgelistet auf der Seite Erste Schritte.

FAQ

Fragen zum sgcSocial-Schnellstart

TsgcWhatsApp_Client auf der Palettenseite SGC Social. Sie ist in sgcLibs.pas als veröffentlichter Wrapper um TsgcWhatsApp_Client_Base deklariert, das in sgcLib_WhatsApp_Client.pas deklariert ist und die Sendemethoden enthält. Setze WhatsAppOptions.PhoneNumberId und WhatsAppOptions.Token und rufe dann SendMessageText auf.
WhatsApp wird durch SGC_WHATSAPP gesteuert, definiert in Zeile 728 von sgcVer.inc, der ersten Zeile des Blocks SGC_EDT_PRO, der von Zeile 727 bis Zeile 758 reicht. Das ist Professional und höher. Telegram wird durch SGC_TELEGRAM gesteuert, sechsmal definiert in den Zeilen 677 bis 694 innerhalb des Blocks SGC_EDT_STD, Zeilen 675 bis 724, einmal je Plattform. Telegram beginnt also eine Stufe tiefer. Das eigenständige Paket sgcSocial schaltet beide über SGC_PACK_SOCIAL ein, Zeile 860, dessen Block in den Zeilen 968 bis 971 sie ohne Plattform-Guard definiert.
Einen string, nämlich den rohen Antwort-Body der Meta Graph API. Die vollständige Signatur lautet function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. Die mitgelieferte Demo protokolliert den Rückgabewert direkt, und das ist der schnellste Weg, einen Fehler von Meta zu sehen, denn ein abgelehnter Versand kommt im Body zurück und nicht als Exception.
Die Komponente kann der Server sein. Rufe StartServer auf, und sie lauscht selbst auf den Meta-Webhook. Mit OnBeforeSubscribe akzeptierst oder lehnst du die Verifizierungsanfrage ab, und OnMessageReceived liefert dir jede eingehende Nachricht samt einem Flag var aMarkAsRead, das du zum Bestätigen setzen kannst. StopServer fährt ihn herunter. Zum Senden ist nichts davon nötig.
Die native TDLib-JSON-Bibliothek neben deiner ausführbaren Datei. Die Komponente lädt sie zur Laufzeit und benennt sie je Plattform: tdjson.dll unter Windows, libtdjson.dylib unter macOS 64 Bit, libtdjson.so unter Linux 64 Bit und unter Lazarus Linux sowie libtdjsonandroid.so unter Android. iOS 64 ist die Ausnahme, dort wird die Bibliothek statisch als libtdjson.a gelinkt. Fehlt sie, löst die Komponente bei der ersten Verwendung einen Fehler aus. SetTDJsonPath richtet sie auf einen anderen Ordner.
Ja, jedes hat eine eigene Methode in derselben Komponente: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons und SendMessageTemplate, die überladen ist. MarkMessageRead markiert eine eingehende Nachricht als gelesen.
Wegen des Threading-Modus. Die mitgelieferte Demo setzt NotifyEvents := neAsynchronous, damit ihre Handler VCL-Steuerelemente ansprechen können, und ihr eigener Kommentar sagt, in der Produktion neNoSync zu verwenden. Mit neNoSync wird das Ereignis im Worker-Thread ausgelöst, was schneller und für einen Dienst richtig ist, und es wird deine Aufgabe, alles zu marshallen, was die Oberfläche berührt.
Ja. Es ist ein eigenständiges Paket mit der enthaltenen Core-Laufzeit von sgcWebSockets, und es ist auch Teil von sgcWebSockets, für WhatsApp ab Professional und für Telegram ab Standard. Im Quelltext ist der eigenständige Weg SGC_PACK_SOCIAL in Zeile 860 von sgcVer.inc, dessen Block in den Zeilen 968 bis 971 beide Clients definiert.
Bestes Preis-Leistungs-Verhältnis: All-AccessAlle eSeGeCe-Produkte, inklusive Premium-Support, ab €1,059 pro Jahr.
All-Access-Preise ansehen

Bereit, deinen Kunden aus Delphi zu schreiben?

Lade die Testversion herunter und sende noch heute deine erste WhatsApp-Nachricht.

Kostenlose Testversion herunterladen Preise ansehen