sgcSocial en cinq minutes

Deux clients de messagerie sont livrés dans ce package : WhatsApp Business Cloud et Telegram sur le TDLib officiel. WhatsApp est le chemin le plus court, car c'est du pur HTTPS sans rien à déployer, cette page envoie donc d'abord un message texte WhatsApp, puis te dit ce dont Telegram a besoin en plus.

WhatsApp Business Cloud API
Telegram sur le TDLib officiel
WhatsApp à partir de Professional, Telegram à partir de Standard
En un coup d'œil

Ce dont a besoin le premier message

Un composant, deux valeurs issues de ton application Meta, et un appel de méthode qui renvoie la réponse de l'API sous forme de chaîne.

Composant

TsgcWhatsApp_Client sur la page de palette SGC Social, déclaré dans sgcLibs.pas comme enveloppe publiée autour de TsgcWhatsApp_Client_Base.

Les deux valeurs dont tu as besoin

WhatsAppOptions.PhoneNumberId et WhatsAppOptions.Token, toutes deux issues de ton application développeur Meta. Rien d'autre n'est requis pour envoyer.

L'appel

SendMessageText(aTo, aMessage) renvoie une string, le corps brut de la réponse de l'API Meta Graph. Journalise-la et tu vois immédiatement si l'envoi a été accepté.

Telegram est différent

TsgcTDLib_Telegram enveloppe le TDLib officiel, il a donc besoin de la bibliothèque native à côté de ton exécutable. C'est la seule étape supplémentaire, et le tableau ci-dessous nomme le fichier selon la plateforme.

Avant de commencer

Prérequis et éditions

La colonne d'édition indique le define qui conditionne chaque client, avec la ligne où il se trouve dans Source/sgcVer.inc.

Quoi Valeur
IDE Delphi 7 jusqu'à RAD Studio 13, et C++Builder 2007 jusqu'à 13.
Clause uses sgcLibs pour les classes de la palette. La démo ajoute sgcLib_WhatsApp_Client pour les types d'options et de messages.
Édition WhatsApp SGC_WHATSAPP est défini à la ligne 728, la première ligne du bloc {$IFDEF SGC_EDT_PRO} qui va de la ligne 727 à la ligne 758. Donc Professional et supérieures.
Édition Telegram SGC_TELEGRAM est défini aux lignes 677, 680, 683, 687, 691 et 694, toutes dans le bloc {$IFDEF SGC_EDT_STD} qui va de la ligne 675 à la ligne 724. Six lignes car chacune est protégée par une plateforme. Donc Standard et supérieures, sur les plateformes indiquées.
Édition, package autonome Le produit sgcSocial définit SGC_PACK_SOCIAL à la ligne 860, et son propre bloc des lignes 968 à 971 définit SGC_TELEGRAM à la ligne 969 et SGC_WHATSAPP à la ligne 970. Les mêmes deux clients, sans le reste de la bibliothèque.
Plateformes WhatsApp Aucune dépendance native et aucune garde de plateforme. C'est du HTTPS vers l'API Meta Graph, donc toute cible disposant d'un moteur TLS fonctionne.
Plateformes Telegram Nécessite la bibliothèque JSON TDLib à côté du binaire : tdjson.dll sous Windows, libtdjson.dylib sous macOS 64 bits, libtdjson.so sous Linux 64 bits et sous Lazarus Linux, libtdjsonandroid.so sous Android. Sous iOS 64, la bibliothèque est liée statiquement sous le nom libtdjson.a au lieu d'être chargée à l'exécution.

Un numéro de test WhatsApp Business Cloud, un jeton permanent et un identifiant de numéro de téléphone proviennent tous de la console développeur Meta. Aucun élément du composant ne les crée pour toi.

Étape 1

Installer et trouver la page de palette

sgcSocial est livré dans l'installeur de sgcWebSockets et aussi comme package à part. L'installation a la même forme dans les deux cas.

1. Décompresser

Décompresse le téléchargement dans un dossier, appelé {$DIR} ci-dessous.

2. Chemin de bibliothèque

Outils, Options, Bibliothèque. Ajoute {$DIR}\source et le dossier lib de ton IDE, par exemple {$DIR}\libD13\$(Platform).

3. Compiler les packages

Ouvre le groupe de packages de ta version d'IDE sous {$DIR}\Packages\. Compile d'abord le .dpk d'exécution, puis installe celui de conception dcl.

4. Vérifier la palette

Une page nommée SGC Social apparaît. Dans une version Standard, elle contient TsgcTDLib_Telegram. À partir de Professional, elle contient aussi TsgcWhatsApp_Client.

5. Pour Telegram uniquement, livre TDLib

Copie la bibliothèque JSON TDLib de ta plateforme à côté de l'exécutable. La démo Telegram livrée a tdjson.dll avec libcrypto-3.dll, libssl-3.dll et zlib1.dll dans son dossier, ce qui est l'ensemble dont Windows a besoin.

QuickStart

Envoyer un message WhatsApp, en une dizaine de lignes

Définis l'identifiant du numéro de téléphone et le jeton, appelle SendMessageText, et lis la réponse renvoyée par l'API Graph.

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;

Voilà tout le chemin d'envoi. Rien d'autre n'est à configurer, et aucun serveur n'a besoin de tourner. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons et SendMessageTemplate ont la même forme.

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;

La réception est facultative. StopServer arrête à nouveau l'écouteur, et OnBeforeSubscribe est l'endroit où tu acceptes ou rejettes la requête de vérification de Meta, via son paramètre 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;

Pour te connecter en tant que bot, laisse PhoneNumber vide et définis Telegram.BotToken. L'autorisation est ensuite pilotée par événements : OnAuthorizationStatus, OnAuthenticationCode et OnAuthenticationPassword te demandent ce dont TDLib a besoin ensuite.

Les deux premiers onglets proviennent de la démo livrée Demos\50.Other\05.WhatsApp\FWhatsApp.pas, avec les contrôles de la fiche remplacés par des littéraux. Le bouton d'envoi de cette démo appelle en réalité SendMessageLocation ; l'appel texte montré ici correspond au chemin SendMessageText du même fichier. L'onglet Telegram montre la seule ligne qui diffère de tous les autres composants de la bibliothèque.

Étape 2

Vérifier que le message a été accepté

Deux niveaux de preuve : ce que renvoie l'appel d'envoi, et ce que te dit ensuite le webhook.

La valeur de retour

SendMessageText renvoie le corps de la réponse de l'API Graph sous forme de string. Journalise-la. Une erreur de Meta arrive dans ce corps plutôt que sous forme d'exception, donc un envoi qui semble ne rien faire y trouve généralement son explication.

OnMessageSent

Indique ce qui est arrivé à un message par la suite, via une valeur d'état qui passe d'inconnu à envoyé, distribué et lu. Il nécessite que le serveur webhook tourne, car l'état arrive comme un rappel entrant.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Définis aMarkAsRead pour accuser réception du message, ce qui affiche les coches bleues sur l'écran de l'expéditeur.

Telegram

OnConnectionStatus et OnAuthorizationStatus sont les deux à surveiller. TDLib se connecte en plusieurs étapes, les événements d'état sont donc le seul moyen fiable de savoir où tu en es dans cette séquence.

Problèmes courants

Ce qui se passe généralement mal la première fois

Six problèmes expliquent presque tous les premiers envois en échec.

Le composant n'est pas dans la palette

TsgcWhatsApp_Client n'est compilé que lorsque SGC_WHATSAPP est défini, ce qui se produit à la ligne 728 dans le bloc Professional. Dans une version Standard, tu as Telegram et pas WhatsApp.

L'envoi renvoie une erreur concernant un modèle

WhatsApp n'autorise un message texte libre que dans la fenêtre de service client qui s'ouvre quand l'utilisateur t'écrit en premier. En dehors, tu dois envoyer un modèle approuvé, c'est-à-dire SendMessageTemplate, et non SendMessageText.

Rien n'arrive et aucune erreur n'est levée

Lis la valeur de retour. SendMessageText renvoie la réponse brute de l'API Graph sous forme de chaîne, et la démo la journalise directement. Une erreur de Meta revient dans ce corps.

Le jeton expire au bout d'un jour

Le jeton temporaire de la console Meta a une durée de vie courte. Génère un jeton permanent pour un utilisateur système avant de quitter l'exemple.

Telegram lève une erreur de bibliothèque au démarrage

TDLib est introuvable. Le composant le charge à l'exécution avec dlopen ou LoadLibrary et lève une erreur si cela échoue. Place le fichier à côté de ton exécutable, ou définis le chemin de recherche avec SetTDJsonPath.

Les événements se déclenchent sur le mauvais thread

La démo définit NotifyEvents := neAsynchronous pour pouvoir toucher directement la fiche, et son propre commentaire indique d'utiliser neNoSync en production et de basculer toi-même vers le thread de l'interface.

Aller plus loin

Au-delà du premier message

Quatre directions que prend généralement le travail, toutes dans le même package.

Des messages WhatsApp plus riches

Les images, documents, localisations, contacts, messages à boutons interactifs et modèles approuvés ont chacun leur propre méthode d'envoi sur le même composant.

Référence WhatsApp

Recevoir, pas seulement envoyer

Le composant peut héberger lui-même le point d'accès webhook. StartServer le démarre, OnBeforeSubscribe accepte ou rejette la poignée de main de vérification, et OnMessageReceived te transmet chaque message entrant.

Référence WhatsApp

De vraies applications Telegram, pas seulement des bots

TDLib est la même bibliothèque que celle des clients Telegram officiels, le composant atteint donc les comptes utilisateurs, les conversations, les médias et les messages sponsorisés, et pas seulement l'API des bots.

Référence Telegram

État de livraison

OnMessageSent indique la progression d'un message que tu as envoyé, à travers les états que définit l'API : inconnu, envoyé, distribué et lu.

Référence WhatsApp

Ressources

Référence, démos et documentation

Les pages de référence documentent chaque méthode et chaque événement. Les projets de démo sont livrés dans le téléchargement, sous Demos\50.Other.

Référence, client WhatsApp Chaque méthode d'envoi, option et événement de TsgcWhatsApp_Client. Ouvrir
Référence, client Telegram Autorisation, conversations, messages et médias sur TsgcTDLib_Telegram. Ouvrir
Page du composant TsgcWhatsApp_Client Chaque méthode d'envoi et événement, avec le client Telegram lié depuis celle-ci. Ouvrir
Télécharger l'essai Le même installeur que la version de production, limité dans le temps. Ouvrir
Aide en ligne La référence générée, toujours en phase avec la version actuelle. Ouvrir
Manuel utilisateur (PDF) Le manuel complet couvrant tous les composants de la bibliothèque. Ouvrir

Lectures associées : le composant WhatsApp, envoyer des fichiers locaux via WhatsApp, le client Telegram et Telegram derrière un proxy. Chaque produit a son propre démarrage rapide, listé sur la page de prise en main.

FAQ

Questions sur le démarrage rapide de sgcSocial

TsgcWhatsApp_Client, sur la page de palette SGC Social. Il est déclaré dans sgcLibs.pas comme enveloppe publiée autour de TsgcWhatsApp_Client_Base, lui-même déclaré dans sgcLib_WhatsApp_Client.pas et qui porte les méthodes d'envoi. Définis WhatsAppOptions.PhoneNumberId et WhatsAppOptions.Token, puis appelle SendMessageText.
WhatsApp est conditionné par SGC_WHATSAPP, défini à la ligne 728 de sgcVer.inc, la première ligne du bloc SGC_EDT_PRO qui va de la ligne 727 à la ligne 758. C'est Professional et au-dessus. Telegram est conditionné par SGC_TELEGRAM, défini six fois aux lignes 677 à 694 dans le bloc SGC_EDT_STD, lignes 675 à 724, une fois par plateforme. Telegram commence donc un niveau plus bas. Le package sgcSocial autonome active les deux via SGC_PACK_SOCIAL, ligne 860, dont le bloc des lignes 968 à 971 les définit sans garde de plateforme.
Une string, qui est le corps brut de la réponse de l'API Meta Graph. Sa signature complète est function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. La démo livrée journalise directement la valeur de retour, et c'est le moyen le plus rapide de voir une erreur de Meta, car un envoi rejeté revient dans le corps plutôt que sous forme d'exception.
Le composant peut être le serveur. Appelle StartServer et il écoute lui-même le webhook de Meta. OnBeforeSubscribe te permet d'accepter ou de rejeter la requête de vérification, et OnMessageReceived te transmet chaque message entrant avec un indicateur var aMarkAsRead que tu peux définir pour accuser réception. StopServer l'arrête. L'envoi n'a besoin de rien de tout cela.
De la bibliothèque JSON native TDLib à côté de ton exécutable. Le composant la charge à l'exécution et la nomme selon la plateforme : tdjson.dll sous Windows, libtdjson.dylib sous macOS 64 bits, libtdjson.so sous Linux 64 bits et sous Lazarus Linux, et libtdjsonandroid.so sous Android. iOS 64 est l'exception, où la bibliothèque est liée statiquement sous le nom libtdjson.a. Si elle est absente, le composant lève une erreur au premier usage. SetTDJsonPath la dirige vers un autre dossier.
Oui, chacun a sa propre méthode sur le même composant : SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons et SendMessageTemplate, qui est surchargée. MarkMessageRead marque un message entrant comme lu.
À cause du mode de gestion des threads. La démo livrée définit NotifyEvents := neAsynchronous pour que ses gestionnaires puissent toucher les contrôles VCL, et son propre commentaire indique d'utiliser neNoSync en production. Avec neNoSync, l'événement se déclenche sur le thread de travail, ce qui est plus rapide et correct pour un service, et il t'appartient alors de basculer vers le thread de l'interface tout ce qui la touche.
Oui. C'est un package autonome qui inclut le runtime sgcWebSockets Core, et il fait aussi partie de sgcWebSockets à partir de Professional pour WhatsApp et de Standard pour Telegram. Dans les sources, la voie autonome est SGC_PACK_SOCIAL à la ligne 860 de sgcVer.inc, dont le bloc des lignes 968 à 971 définit les deux clients.
Meilleur rapport qualité-prix : All-AccessTous les produits eSeGeCe, Support Premium inclus, à partir de €1,059/an.
Voir les tarifs All-Access

Prêt à écrire à tes clients depuis Delphi ?

Télécharge l'essai et envoie dès aujourd'hui ton premier message WhatsApp.

Télécharger l'essai gratuit Voir les tarifs