sgcSocial in cinque minuti

In questo pacchetto sono inclusi due client di messaggistica: WhatsApp Business Cloud e Telegram sul TDLib ufficiale. WhatsApp è il percorso più breve, perché è puro HTTPS senza nulla da distribuire, quindi questa pagina invia prima un messaggio di testo WhatsApp e poi ti dice cosa serve in più per Telegram.

API WhatsApp Business Cloud
Telegram sul TDLib ufficiale
WhatsApp dalla Professional, Telegram dalla Standard
In sintesi

Cosa serve per il primo messaggio

Un componente, due valori dalla tua app Meta e una chiamata di metodo che restituisce la risposta dell'API come stringa.

Componente

TsgcWhatsApp_Client nella pagina SGC Social della palette, dichiarato in sgcLibs.pas come wrapper pubblicato attorno a TsgcWhatsApp_Client_Base.

I due valori che ti servono

WhatsAppOptions.PhoneNumberId e WhatsAppOptions.Token, entrambi presi dalla tua app per sviluppatori Meta. Per inviare non serve nient'altro.

La chiamata

SendMessageText(aTo, aMessage) restituisce una string, il corpo grezzo della risposta dell'API Graph di Meta. Registralo nel log e vedi subito se l'invio è stato accettato.

Telegram è diverso

TsgcTDLib_Telegram incapsula il TDLib ufficiale, quindi richiede la libreria nativa accanto al tuo eseguibile. È l'unico passaggio aggiuntivo e la tabella qui sotto indica il file per piattaforma.

Prima di iniziare

Requisiti ed edizioni

La colonna dell'edizione indica il define che regola ogni client, con la riga in cui si trova in Source/sgcVer.inc.

Cosa Valore
IDE Da Delphi 7 a RAD Studio 13 e da C++Builder 2007 a 13.
Clausola uses sgcLibs per le classi della palette. La demo aggiunge sgcLib_WhatsApp_Client per le opzioni e i tipi di messaggio.
Edizione WhatsApp SGC_WHATSAPP è definito alla riga 728, la prima riga dentro il blocco {$IFDEF SGC_EDT_PRO} che va dalla riga 727 alla riga 758. Quindi Professional e superiori.
Edizione Telegram SGC_TELEGRAM è definito alle righe 677, 680, 683, 687, 691 e 694, tutte dentro il blocco {$IFDEF SGC_EDT_STD} che va dalla riga 675 alla riga 724. Sei righe perché ciascuna è protetta da una piattaforma. Quindi Standard e superiori, sulle piattaforme elencate lì.
Edizione, pacchetto autonomo Il prodotto sgcSocial definisce SGC_PACK_SOCIAL alla riga 860 e il suo blocco alle righe da 968 a 971 definisce SGC_TELEGRAM alla riga 969 e SGC_WHATSAPP alla riga 970. Stessi due client, senza il resto della libreria.
Piattaforme WhatsApp Nessuna dipendenza nativa e nessuna guardia di piattaforma. È HTTPS verso l'API Graph di Meta, quindi funziona su ogni target che abbia un back end TLS.
Piattaforme Telegram Richiede la libreria TDLib JSON accanto al binario: tdjson.dll su Windows, libtdjson.dylib su macOS 64 bit, libtdjson.so su Linux 64 bit e su Lazarus Linux, libtdjsonandroid.so su Android. Su iOS 64 la libreria è collegata staticamente come libtdjson.a invece di essere caricata a runtime.

Un numero di test di WhatsApp Business Cloud, un token permanente e un phone number id provengono tutti dalla console per sviluppatori Meta. Nessuna parte del componente li crea per te.

Passo 1

Installa e trova la pagina della palette

sgcSocial è incluso nell'installer di sgcWebSockets e anche come pacchetto a sé. L'installazione ha la stessa forma in entrambi i casi.

1. Decomprimi

Decomprimi il download in una cartella, chiamata {$DIR} qui sotto.

2. Library path

Tools, Options, Library. Aggiungi {$DIR}\source e la cartella lib per il tuo IDE, per esempio {$DIR}\libD13\$(Platform).

3. Compila i package

Apri il gruppo di package per la versione del tuo IDE in {$DIR}\Packages\. Compila prima il .dpk di runtime, poi installa quello di design-time dcl.

4. Controlla la palette

Compare una pagina chiamata SGC Social. In una build Standard contiene TsgcTDLib_Telegram. Dalla Professional in su contiene anche TsgcWhatsApp_Client.

5. Solo per Telegram, distribuisci TDLib

Copia la libreria TDLib JSON per la tua piattaforma accanto all'eseguibile. La demo Telegram inclusa ha tdjson.dll insieme a libcrypto-3.dll, libssl-3.dll e zlib1.dll nella sua cartella, che è l'insieme necessario a Windows.

QuickStart

Invia un messaggio WhatsApp, in circa dieci righe

Imposta il phone number id e il token, chiama SendMessageText e leggi la risposta restituita dall'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;

Questo è l'intero percorso di invio. Non serve configurare nient'altro e non deve essere in esecuzione alcun server. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons e SendMessageTemplate seguono la stessa forma.

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 ricezione è facoltativa. StopServer spegne di nuovo il listener e OnBeforeSubscribe è il punto in cui accetti o rifiuti la richiesta di verifica di Meta, tramite il suo parametro 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;

Per accedere invece come bot, lascia vuoto PhoneNumber e imposta Telegram.BotToken. Da lì l'autorizzazione è guidata dagli eventi: OnAuthorizationStatus, OnAuthenticationCode e OnAuthenticationPassword ti chiedono ciò che TDLib richiede di volta in volta.

Le prime due schede sono la demo inclusa Demos\50.Other\05.WhatsApp\FWhatsApp.pas, con i controlli del form sostituiti da valori letterali. Il pulsante di invio di quella demo chiama in realtà SendMessageLocation; la chiamata di testo mostrata qui è il percorso SendMessageText dello stesso file. La scheda Telegram mostra l'unica riga diversa da ogni altro componente della libreria.

Passo 2

Verifica che il messaggio sia stato accettato

Due livelli di prova: ciò che restituisce la chiamata di invio e ciò che il webhook ti comunica in seguito.

Il valore restituito

SendMessageText restituisce il corpo della risposta dell'API Graph come string. Registralo nel log. Un errore di Meta arriva in quel corpo e non come eccezione, quindi un invio che sembra non fare nulla ha di solito la sua spiegazione proprio lì.

OnMessageSent

Riporta ciò che è successo a un messaggio in seguito, tramite un valore di stato che passa da sconosciuto a inviato, consegnato e letto. Richiede che il server webhook sia in esecuzione, perché lo stato arriva come callback in ingresso.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Imposta aMarkAsRead per confermare la lettura del messaggio, che è ciò che mostra le spunte blu sullo schermo del mittente.

Telegram

OnConnectionStatus e OnAuthorizationStatus sono i due da tenere d'occhio. TDLib effettua l'accesso in più passaggi, quindi gli eventi di stato sono l'unico modo affidabile per sapere a che punto sei in quella sequenza.

Problemi comuni

Cosa va storto di solito la prima volta

Sei problemi spiegano quasi ogni primo invio fallito.

Il componente non è nella palette

TsgcWhatsApp_Client viene compilato solo quando è definito SGC_WHATSAPP, cosa che avviene alla riga 728 dentro il blocco Professional. In una build Standard hai Telegram e non WhatsApp.

L'invio restituisce un errore su un template

WhatsApp consente un messaggio di testo libero solo all'interno della finestra del servizio clienti che si apre quando è l'utente a scriverti per primo. Fuori da essa devi inviare un template approvato, cioè SendMessageTemplate, non SendMessageText.

Non arriva nulla e non viene sollevato alcun errore

Leggi il valore restituito. SendMessageText restituisce la risposta grezza dell'API Graph come stringa e la demo la registra direttamente nel log. Un errore di Meta torna in quel corpo.

Il token scade dopo un giorno

Il token temporaneo nella console Meta ha vita breve. Genera un token permanente per un utente di sistema prima di lasciare l'esempio.

Telegram solleva un errore di libreria all'avvio

TDLib non è stato trovato. Il componente lo carica a runtime con dlopen o LoadLibrary e solleva un'eccezione quando fallisce. Metti il file accanto al tuo eseguibile oppure imposta il percorso di ricerca con SetTDJsonPath.

Gli eventi vengono generati sul thread sbagliato

La demo imposta NotifyEvents := neAsynchronous per poter toccare direttamente il form e il suo stesso commento dice di usare neNoSync in produzione e di passare al thread dell'interfaccia da soli.

Approfondisci

Oltre il primo messaggio

Quattro direzioni che il lavoro prende di solito, tutte nello stesso pacchetto.

Messaggi WhatsApp più ricchi

Immagini, documenti, posizioni, contatti, messaggi con pulsanti interattivi e template approvati hanno ciascuno il proprio metodo di invio nello stesso componente.

Riferimento di WhatsApp

Ricevi, non solo invii

Il componente può ospitare da solo l'endpoint del webhook. StartServer lo avvia, OnBeforeSubscribe accetta o rifiuta l'handshake di verifica e OnMessageReceived ti consegna ogni messaggio in ingresso.

Riferimento di WhatsApp

App Telegram complete, non solo bot

TDLib è la stessa libreria usata dai client Telegram ufficiali, quindi il componente raggiunge account utente, chat, contenuti multimediali e messaggi sponsorizzati e non solo l'API dei bot.

Riferimento di Telegram

Stato di consegna

OnMessageSent riporta l'avanzamento di un messaggio che hai inviato, attraverso gli stati definiti dall'API: sconosciuto, inviato, consegnato e letto.

Riferimento di WhatsApp

Risorse

Riferimento, demo e documentazione

Le pagine di riferimento documentano ogni metodo ed evento. I progetti demo sono inclusi nel download, in Demos\50.Other.

Riferimento, client WhatsApp Ogni metodo di invio, opzione ed evento di TsgcWhatsApp_Client. Apri
Riferimento, client Telegram Autorizzazione, chat, messaggi e contenuti multimediali in TsgcTDLib_Telegram. Apri
Pagina del componente TsgcWhatsApp_Client Ogni metodo di invio ed evento, con il client Telegram collegato da lì. Apri
Scarica la versione di prova Lo stesso installer della versione di produzione, con limite di tempo. Apri
Guida online Il riferimento generato, sempre allineato alla versione corrente. Apri
Manuale utente (PDF) Il manuale completo che copre ogni componente della libreria. Apri

Letture correlate: il componente WhatsApp, inviare file locali con WhatsApp, il client Telegram e Telegram dietro un proxy. Ogni prodotto ha la propria guida rapida, elencata nella pagina per iniziare.

FAQ

Domande sulla guida rapida di sgcSocial

TsgcWhatsApp_Client, nella pagina SGC Social della palette. È dichiarato in sgcLibs.pas come wrapper pubblicato attorno a TsgcWhatsApp_Client_Base, che è dichiarato in sgcLib_WhatsApp_Client.pas e contiene i metodi di invio. Imposta WhatsAppOptions.PhoneNumberId e WhatsAppOptions.Token, poi chiama SendMessageText.
WhatsApp è regolato da SGC_WHATSAPP, definito alla riga 728 di sgcVer.inc, la prima riga del blocco SGC_EDT_PRO che va dalla riga 727 alla riga 758. È la Professional e superiori. Telegram è regolato da SGC_TELEGRAM, definito sei volte alle righe da 677 a 694 dentro il blocco SGC_EDT_STD, righe da 675 a 724, una per piattaforma. Quindi Telegram parte un livello più in basso. Il pacchetto sgcSocial autonomo attiva entrambi tramite SGC_PACK_SOCIAL, riga 860, il cui blocco alle righe da 968 a 971 li definisce senza guardia di piattaforma.
Una string, cioè il corpo grezzo della risposta dell'API Graph di Meta. La sua firma completa è function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. La demo inclusa registra direttamente il valore restituito, ed è il modo più rapido per vedere un errore di Meta, perché un invio rifiutato torna nel corpo e non come eccezione.
Il componente può essere il server. Chiama StartServer e si mette in ascolto da solo per il webhook di Meta. OnBeforeSubscribe ti permette di accettare o rifiutare la richiesta di verifica e OnMessageReceived ti dà ogni messaggio in ingresso più un flag var aMarkAsRead che puoi impostare per confermarne la lettura. StopServer lo spegne. L'invio non richiede nulla di tutto questo.
La libreria nativa TDLib JSON accanto al tuo eseguibile. Il componente la carica a runtime e ne indica il nome per piattaforma: tdjson.dll su Windows, libtdjson.dylib su macOS 64 bit, libtdjson.so su Linux 64 bit e su Lazarus Linux, e libtdjsonandroid.so su Android. iOS 64 è l'eccezione, dove la libreria è collegata staticamente come libtdjson.a. Se manca, il componente solleva un'eccezione al primo utilizzo. SetTDJsonPath lo punta a una cartella diversa.
Sì, ciascuno ha il proprio metodo nello stesso componente: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons e SendMessageTemplate, che ha più overload. MarkMessageRead segna un messaggio in ingresso come letto.
A causa della modalità di threading. La demo inclusa imposta NotifyEvents := neAsynchronous in modo che i suoi gestori possano toccare i controlli VCL e il suo stesso commento dice di usare neNoSync in produzione. Con neNoSync l'evento viene generato sul thread di lavoro, che è più veloce e corretto per un servizio, e diventa tuo compito passare al thread dell'interfaccia tutto ciò che la tocca.
Sì. È un pacchetto autonomo con il runtime sgcWebSockets Core incluso ed è anche parte di sgcWebSockets dalla Professional in su per WhatsApp e dalla Standard in su per Telegram. Nel sorgente la strada autonoma è SGC_PACK_SOCIAL alla riga 860 di sgcVer.inc, il cui blocco alle righe da 968 a 971 definisce entrambi i client.
La scelta più conveniente: All-AccessTutti i prodotti eSeGeCe, con Supporto Premium incluso, a partire da €1,059/anno.
Vedi i prezzi All-Access

Pronto a scrivere ai tuoi clienti da Delphi?

Scarica la versione di prova e invia oggi il tuo primo messaggio WhatsApp.

Scarica la versione di prova gratuita Vedi i prezzi