sgcSocial in vijf minuten

In dit package zitten twee messagingclients: WhatsApp Business Cloud en Telegram op de officiële TDLib. WhatsApp is de kortere weg, omdat het puur HTTPS is zonder iets om mee te leveren. Deze pagina verstuurt daarom eerst een WhatsApp-tekstbericht en vertelt je daarna wat Telegram extra nodig heeft.

WhatsApp Business Cloud API
Telegram op de officiële TDLib
WhatsApp vanaf Professional, Telegram vanaf Standard
In één oogopslag

Wat het eerste bericht nodig heeft

Eén component, twee waarden uit je Meta-app en één methodeaanroep die de API-respons als string teruggeeft.

Component

TsgcWhatsApp_Client op de palettabpagina SGC Social, gedeclareerd in sgcLibs.pas als gepubliceerde wrapper rond TsgcWhatsApp_Client_Base.

De twee waarden die je nodig hebt

WhatsAppOptions.PhoneNumberId and WhatsAppOptions.Token, beide afkomstig uit je Meta-ontwikkelaarsapp. Meer is er niet nodig om te versturen.

De aanroep

SendMessageText(aTo, aMessage) geeft een string terug, de ruwe responsbody van de Meta Graph API. Log die en je ziet meteen of het versturen is geaccepteerd.

Telegram is anders

TsgcTDLib_Telegram omhult de officiële TDLib en heeft dus de native bibliotheek naast je uitvoerbare bestand nodig. Dat is de ene extra stap en de onderstaande tabel noemt het bestand per platform.

Voordat je begint

Vereisten en edities

De editiekolom noemt de define die elke client afschermt, met het regelnummer in Source/sgcVer.inc.

Onderdeel Waarde
IDE Delphi 7 tot en met RAD Studio 13 en C++Builder 2007 tot en met 13.
Uses-clausule sgcLibs voor de palettklassen. De demo voegt sgcLib_WhatsApp_Client toe voor de opties en berichttypen.
WhatsApp-editie SGC_WHATSAPP wordt gedefinieerd op regel 728, de eerste regel in het {$IFDEF SGC_EDT_PRO}-blok dat loopt van regel 727 tot regel 758. Dus Professional en hoger.
Telegram-editie SGC_TELEGRAM wordt gedefinieerd op regel 677, 680, 683, 687, 691 en 694, allemaal binnen het {$IFDEF SGC_EDT_STD}-blok dat loopt van regel 675 tot regel 724. Zes regels omdat elke door een platform wordt beveiligd. Dus Standard en hoger, op de daar genoemde platforms.
Editie, zelfstandig package Het product sgcSocial definieert SGC_PACK_SOCIAL op regel 860 en het eigen blok op regel 968 tot 971 definieert SGC_TELEGRAM op regel 969 en SGC_WHATSAPP op regel 970. Dezelfde twee clients, zonder de rest van de bibliotheek.
WhatsApp-platforms Geen native afhankelijkheid en geen platformbeveiliging. Het is HTTPS naar de Meta Graph API, dus elk doelplatform met een TLS-backend werkt.
Telegram-platforms Heeft de TDLib JSON-bibliotheek naast het binaire bestand nodig: tdjson.dll op Windows, libtdjson.dylib op macOS 64-bit, libtdjson.so op Linux 64-bit en op Lazarus Linux, libtdjsonandroid.so op Android. Op iOS 64 wordt de bibliotheek statisch gelinkt als libtdjson.a in plaats van tijdens runtime geladen.

Een WhatsApp Business Cloud-testnummer, een permanent token en een telefoonnummer-id komen allemaal uit de Meta-ontwikkelaarsconsole. Het component maakt ze niet voor je aan.

Stap 1

Installeer en vind de palettabpagina

sgcSocial wordt geleverd in het sgcWebSockets-installatieprogramma en ook als eigen package. De installatie verloopt in beide gevallen op dezelfde manier.

1. Uitpakken

Pak de download uit in een map, hieronder {$DIR} genoemd.

2. Bibliotheekpad

Tools, Options, Library. Voeg {$DIR}\source toe en de libmap voor jouw IDE, bijvoorbeeld {$DIR}\libD13\$(Platform).

3. De packages bouwen

Open de packagegroep voor jouw IDE-versie onder {$DIR}\Packages\. Compileer eerst de runtime-.dpk en installeer daarna die van designtime (dcl).

4. Het palet controleren

Er verschijnt een pagina met de naam SGC Social. In een Standard-build bevat die TsgcTDLib_Telegram. Vanaf Professional bevat die ook TsgcWhatsApp_Client.

5. Alleen voor Telegram: lever TDLib mee

Kopieer de TDLib JSON-bibliotheek voor jouw platform naast het uitvoerbare bestand. De meegeleverde Telegram-demo heeft tdjson.dll samen met libcrypto-3.dll, libssl-3.dll en zlib1.dll in zijn map staan, en dat is de set die Windows nodig heeft.

QuickStart

Verstuur een WhatsApp-bericht, in ongeveer tien regels

Stel het telefoonnummer-id en het token in, roep SendMessageText aan en lees de respons die de Graph API terugstuurde.

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;

Dat is het hele verzendpad. Er hoeft verder niets te worden geconfigureerd en er hoeft geen server te draaien. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons en SendMessageTemplate hebben dezelfde vorm.

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;

Ontvangen is optioneel. StopServer sluit de listener weer af en in OnBeforeSubscribe accepteer of weiger je het verificatieverzoek van Meta, via de 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;

Om in plaats daarvan als bot in te loggen, laat je PhoneNumber leeg en stel je Telegram.BotToken in. Vanaf daar verloopt autorisatie via gebeurtenissen: OnAuthorizationStatus, OnAuthenticationCode en OnAuthenticationPassword vragen je om wat TDLib hierna nodig heeft.

De eerste twee tabbladen zijn de meegeleverde demo Demos\50.Other\05.WhatsApp\FWhatsApp.pas, met de formulierbesturingselementen vervangen door literals. De verzendknop van die demo roept in werkelijkheid SendMessageLocation aan; de hier getoonde tekstaanroep is het SendMessageText-pad uit hetzelfde bestand. Het Telegram-tabblad toont de ene regel die anders is dan bij elk ander component in de bibliotheek.

Stap 2

Controleer of het bericht is geaccepteerd

Twee niveaus van bewijs: wat de verzendaanroep teruggeeft en wat de webhook je daarna vertelt.

De retourwaarde

SendMessageText geeft de responsbody van de Graph API terug als string. Log die. Een fout van Meta komt in die body terecht en niet als exception, dus een verzending die niets lijkt te doen, heeft daar meestal de verklaring staan.

OnMessageSent

Meldt achteraf wat er met een bericht is gebeurd, via een statuswaarde die verloopt van onbekend naar verzonden, afgeleverd en gelezen. Het heeft de webhookserver nodig, omdat de status als binnenkomende callback aankomt.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Stel aMarkAsRead in om het bericht te bevestigen, waardoor de blauwe vinkjes op het scherm van de afzender verschijnen.

Telegram

OnConnectionStatus en OnAuthorizationStatus zijn de twee om in de gaten te houden. TDLib logt in via meerdere stappen, dus de statusgebeurtenissen zijn de enige betrouwbare manier om te weten waar je in die reeks zit.

Veelvoorkomende problemen

Wat er de eerste keer meestal misgaat

Zes problemen verklaren bijna elke mislukte eerste verzending.

Het component staat niet op het palet

TsgcWhatsApp_Client wordt alleen gecompileerd als SGC_WHATSAPP is gedefinieerd, wat gebeurt op regel 728 binnen het Professional-blok. In een Standard-build krijg je Telegram en geen WhatsApp.

De verzending geeft een fout over een sjabloon

WhatsApp staat een vrij tekstbericht alleen toe binnen het klantenservicevenster dat opent wanneer de gebruiker jou als eerste een bericht stuurt. Daarbuiten moet je een goedgekeurd sjabloon versturen, en dat is SendMessageTemplate, niet SendMessageText.

Er komt niets aan en er is geen fout

Lees de retourwaarde. SendMessageText geeft de ruwe Graph API-respons terug als string en de demo logt die rechtstreeks. Een fout van Meta komt in die body terug.

Het token verloopt na een dag

Het tijdelijke token in de Meta-console is kortlevend. Genereer een permanent token voor een systeemgebruiker voordat je het voorbeeld achter je laat.

Telegram geeft bij het opstarten een bibliotheekfout

TDLib is niet gevonden. Het component laadt de bibliotheek tijdens runtime met dlopen of LoadLibrary en veroorzaakt een exception als dat mislukt. Zet het bestand naast je uitvoerbare bestand, of stel het zoekpad in met SetTDJsonPath.

Gebeurtenissen worden op de verkeerde thread aangeroepen

De demo stelt NotifyEvents := neAsynchronous in zodat die het formulier rechtstreeks kan aanraken, en de eigen opmerking zegt dat je in productie neNoSync moet gebruiken en zelf naar de UI-thread moet marshallen.

Verder verdiepen

Voorbij het eerste bericht

Vier richtingen die het werk meestal op gaat, allemaal binnen hetzelfde package.

Rijkere WhatsApp-berichten

Afbeeldingen, documenten, locaties, contacten, interactieve knopberichten en goedgekeurde sjablonen hebben elk een eigen verzendmethode op hetzelfde component.

WhatsApp-referentie

Ontvangen, niet alleen versturen

Het component kan het webhookeindpunt zelf hosten. StartServer start het, OnBeforeSubscribe accepteert of weigert de verificatiehandshake en OnMessageReceived geeft je elk binnenkomend bericht.

WhatsApp-referentie

Complete Telegram-apps, niet alleen bots

TDLib is dezelfde bibliotheek die de officiële Telegram-clients gebruiken, dus het component bereikt gebruikersaccounts, chats, media en gesponsorde berichten en niet alleen de bot-API.

Telegram-referentie

Afleverstatus

OnMessageSent meldt de voortgang van een bericht dat je hebt verstuurd, via de statussen die de API definieert: onbekend, verzonden, afgeleverd en gelezen.

WhatsApp-referentie

Bronnen

Referentie, demo's en documentatie

De referentiepagina's documenteren elke methode en gebeurtenis. Demoprojecten zitten in de download, onder Demos\50.Other.

Referentie, WhatsApp-client Elke verzendmethode, optie en gebeurtenis van TsgcWhatsApp_Client. Openen
Referentie, Telegram-client Autorisatie, chats, berichten en media op TsgcTDLib_Telegram. Openen
Componentpagina TsgcWhatsApp_Client Elke verzendmethode en gebeurtenis, met de Telegram-client erin gelinkt. Openen
Download de proefversie Hetzelfde installatieprogramma als de productieversie, beperkt in tijd. Openen
Online help De gegenereerde referentie, altijd in lijn met de huidige release. Openen
Gebruikershandleiding (PDF) De volledige handleiding met alle componenten in de bibliotheek. Openen

Verder lezen: het WhatsApp-component, lokale bestanden versturen via WhatsApp, de Telegram-client en Telegram achter een proxy. Elk product heeft zijn eigen snelstart, te vinden op de pagina Aan de slag.

FAQ

Vragen over de sgcSocial-snelstart

TsgcWhatsApp_Client, op de palettabpagina SGC Social. Het wordt gedeclareerd in sgcLibs.pas als gepubliceerde wrapper rond TsgcWhatsApp_Client_Base, dat gedeclareerd wordt in sgcLib_WhatsApp_Client.pas en de verzendmethoden bevat. Stel WhatsAppOptions.PhoneNumberId en WhatsAppOptions.Token in en roep daarna SendMessageText aan.
WhatsApp wordt afgeschermd door SGC_WHATSAPP, gedefinieerd op regel 728 van sgcVer.inc, de eerste regel van het SGC_EDT_PRO-blok dat loopt van regel 727 tot regel 758. Dat is Professional en hoger. Telegram wordt afgeschermd door SGC_TELEGRAM, zes keer gedefinieerd op regel 677 tot 694 binnen het SGC_EDT_STD-blok, regel 675 tot 724, eenmaal per platform. Telegram begint dus één niveau lager. Het zelfstandige sgcSocial-package schakelt beide in via SGC_PACK_SOCIAL, regel 860, waarvan het blok op regel 968 tot 971 ze zonder platformbeveiliging definieert.
Een string, de ruwe responsbody van de Meta Graph API. De volledige signatuur is function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. De meegeleverde demo logt de retourwaarde rechtstreeks en dat is de snelste manier om een fout van Meta te zien, omdat een geweigerde verzending in de body terugkomt en niet als exception.
Het component kan zelf de server zijn. Roep StartServer aan en het luistert zelf naar de Meta-webhook. Met OnBeforeSubscribe accepteer of weiger je het verificatieverzoek en OnMessageReceived geeft je elk binnenkomend bericht plus een var aMarkAsRead-vlag die je kunt instellen om het te bevestigen. StopServer sluit het af. Versturen heeft niets daarvan nodig.
De native TDLib JSON-bibliotheek naast je uitvoerbare bestand. Het component laadt die tijdens runtime en gebruikt per platform een andere naam: tdjson.dll op Windows, libtdjson.dylib op macOS 64-bit, libtdjson.so op Linux 64-bit en op Lazarus Linux, en libtdjsonandroid.so op Android. iOS 64 is de uitzondering, waar de bibliotheek statisch wordt gelinkt als libtdjson.a. Als die ontbreekt, veroorzaakt het component bij het eerste gebruik een exception. Met SetTDJsonPath wijs je het naar een andere map.
Ja, elk heeft een eigen methode op hetzelfde component: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons en SendMessageTemplate, die overladen is. MarkMessageRead markeert een binnenkomend bericht als gelezen.
Door de threadingmodus. De meegeleverde demo stelt NotifyEvents := neAsynchronous in zodat de handlers VCL-besturingselementen mogen aanraken, en de eigen opmerking zegt dat je in productie neNoSync moet gebruiken. Met neNoSync wordt de gebeurtenis op de workerthread aangeroepen, wat sneller en correct is voor een service, en het wordt jouw taak om alles wat de UI aanraakt te marshallen.
Ja. Het is een zelfstandig package met de sgcWebSockets Core-runtime inbegrepen, en het maakt ook deel uit van sgcWebSockets vanaf Professional voor WhatsApp en vanaf Standard voor Telegram. In de broncode is de zelfstandige route SGC_PACK_SOCIAL op regel 860 van sgcVer.inc, waarvan het blok op regel 968 tot 971 beide clients definieert.
De beste deal: All-AccessElk eSeGeCe-product, inclusief Premium-ondersteuning, vanaf €1,059 per jaar.
Bekijk de All-Access-prijzen

Klaar om je klanten te berichten vanuit Delphi?

Download de proefversie en verstuur vandaag nog je eerste WhatsApp-bericht.

Download gratis proefversie Bekijk de prijzen