sgcSocial en cinco minutos

Este paquete incluye dos clientes de mensajería: WhatsApp Business Cloud y Telegram sobre el TDLib oficial. WhatsApp es el camino más corto, porque es HTTPS puro y no hay nada que desplegar, así que esta página envía primero un mensaje de texto de WhatsApp y después te cuenta qué necesita Telegram además.

API de WhatsApp Business Cloud
Telegram sobre el TDLib oficial
WhatsApp desde Professional, Telegram desde Standard
De un vistazo

Lo que necesita el primer mensaje

Un componente, dos valores de tu app de Meta y una llamada a un método que devuelve la respuesta de la API como cadena.

Componente

TsgcWhatsApp_Client en la página SGC Social de la paleta, declarado en sgcLibs.pas como una envoltura publicada sobre TsgcWhatsApp_Client_Base.

Los dos valores que necesitas

WhatsAppOptions.PhoneNumberId y WhatsAppOptions.Token, ambos tomados de tu app de desarrollador de Meta. No se necesita nada más para enviar.

La llamada

SendMessageText(aTo, aMessage) devuelve un string, el cuerpo de la respuesta en bruto de la API Graph de Meta. Regístralo y verás de inmediato si el envío fue aceptado.

Telegram es distinto

TsgcTDLib_Telegram envuelve el TDLib oficial, así que necesita la biblioteca nativa junto a tu ejecutable. Es el único paso extra, y la tabla de abajo nombra el archivo por plataforma.

Antes de empezar

Requisitos y ediciones

La columna de edición es el define que controla cada cliente, con la línea en la que se encuentra en Source/sgcVer.inc.

Qué Valor
IDE Delphi 7 hasta RAD Studio 13, y C++Builder 2007 hasta 13.
Cláusula uses sgcLibs para las clases de la paleta. La demo añade sgcLib_WhatsApp_Client para las opciones y los tipos de mensaje.
Edición de WhatsApp SGC_WHATSAPP se define en la línea 728, la primera línea dentro del bloque {$IFDEF SGC_EDT_PRO} que va de la línea 727 a la 758. Es decir, Professional y superiores.
Edición de Telegram SGC_TELEGRAM se define en las líneas 677, 680, 683, 687, 691 y 694, todas dentro del bloque {$IFDEF SGC_EDT_STD} que va de la línea 675 a la 724. Seis líneas porque cada una está protegida por una plataforma. Es decir, Standard y superiores, en las plataformas que se indican ahí.
Edición, paquete independiente El producto sgcSocial define SGC_PACK_SOCIAL en la línea 860, y su propio bloque de las líneas 968 a 971 define SGC_TELEGRAM en la línea 969 y SGC_WHATSAPP en la línea 970. Los mismos dos clientes, sin el resto de la biblioteca.
Plataformas de WhatsApp Sin dependencia nativa y sin guarda de plataforma. Es HTTPS hacia la API Graph de Meta, así que funciona en cualquier destino que tenga un back end TLS.
Plataformas de Telegram Necesita la biblioteca JSON de TDLib junto al binario: tdjson.dll en Windows, libtdjson.dylib en macOS de 64 bits, libtdjson.so en Linux de 64 bits y en Lazarus Linux, libtdjsonandroid.so en Android. En iOS 64 la biblioteca se enlaza estáticamente como libtdjson.a en lugar de cargarse en tiempo de ejecución.

Un número de prueba de WhatsApp Business Cloud, un token permanente y un id de número de teléfono salen todos de la consola de desarrollador de Meta. Nada en el componente los crea por ti.

Paso 1

Instala y localiza la página de la paleta

sgcSocial se distribuye dentro del instalador de sgcWebSockets y también como paquete propio. La instalación tiene la misma forma en ambos casos.

1. Descomprime

Descomprime la descarga en una carpeta, llamada {$DIR} más abajo.

2. Ruta de biblioteca

Tools, Options, Library. Añade {$DIR}\source y la carpeta lib de tu IDE, por ejemplo {$DIR}\libD13\$(Platform).

3. Compila los paquetes

Abre el grupo de paquetes de tu versión de IDE en {$DIR}\Packages\. Compila primero el .dpk de runtime y después instala el de tiempo de diseño, el dcl.

4. Comprueba la paleta

Aparece una página llamada SGC Social. En una compilación Standard contiene TsgcTDLib_Telegram. En Professional y superiores contiene además TsgcWhatsApp_Client.

5. Solo para Telegram, distribuye TDLib

Copia la biblioteca JSON de TDLib de tu plataforma junto al ejecutable. La demo de Telegram incluida tiene tdjson.dll junto con libcrypto-3.dll, libssl-3.dll y zlib1.dll en su carpeta, que es el conjunto que necesita Windows.

QuickStart

Envía un mensaje de WhatsApp, en unas diez líneas

Define el id del número de teléfono y el token, llama a SendMessageText y lee la respuesta que devolvió la 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;

Ese es todo el camino de envío. No hay que configurar nada más y no hace falta ningún servidor en ejecución. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons y SendMessageTemplate siguen la misma 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;

Recibir es opcional. StopServer vuelve a apagar el listener, y OnBeforeSubscribe es donde aceptas o rechazas la petición de verificación de Meta, mediante su parámetro 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;

Para iniciar sesión como bot, deja PhoneNumber vacío y define Telegram.BotToken. A partir de ahí la autorización se guía por eventos: OnAuthorizationStatus, OnAuthenticationCode y OnAuthenticationPassword te piden lo que TDLib necesita a continuación.

Las dos primeras pestañas son la demo incluida Demos\50.Other\05.WhatsApp\FWhatsApp.pas, con los controles del formulario sustituidos por literales. El botón de envío de esa demo en realidad llama a SendMessageLocation; la llamada de texto que se muestra aquí es la ruta SendMessageText del mismo archivo. La pestaña de Telegram muestra la única línea que es distinta de la de cualquier otro componente de la biblioteca.

Paso 2

Comprueba que el mensaje fue aceptado

Dos niveles de prueba: lo que devuelve la llamada de envío y lo que te dice el webhook después.

El valor de retorno

SendMessageText devuelve el cuerpo de la respuesta de la API Graph como un string. Regístralo. Un error de Meta llega en ese cuerpo y no como una excepción, así que un envío que parece no hacer nada suele tener su explicación justo ahí.

OnMessageSent

Informa de lo que le ocurrió a un mensaje después, mediante un valor de estado que pasa de desconocido a enviado, entregado y leído. Necesita que el servidor del webhook esté en ejecución, porque el estado llega como una llamada entrante.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Pon aMarkAsRead para confirmar el mensaje, que es lo que muestra los ticks azules en la pantalla del remitente.

Telegram

OnConnectionStatus y OnAuthorizationStatus son los dos que hay que vigilar. TDLib inicia sesión en varios pasos, así que los eventos de estado son la única forma fiable de saber en qué punto de esa secuencia estás.

Problemas habituales

Lo que suele fallar la primera vez

Seis problemas explican casi todos los primeros envíos fallidos.

El componente no está en la paleta

TsgcWhatsApp_Client se compila solo cuando SGC_WHATSAPP está definido, lo que ocurre en la línea 728 dentro del bloque Professional. En una compilación Standard obtienes Telegram y no WhatsApp.

El envío devuelve un error sobre una plantilla

WhatsApp solo permite un mensaje de texto libre dentro de la ventana de atención al cliente que se abre cuando el usuario te escribe primero. Fuera de ella tienes que enviar una plantilla aprobada, que es SendMessageTemplate, no SendMessageText.

No llega nada y no se lanza ningún error

Lee el valor de retorno. SendMessageText devuelve la respuesta en bruto de la API Graph como cadena, y la demo la registra directamente. Un error de Meta vuelve en ese cuerpo.

El token caduca al cabo de un día

El token temporal de la consola de Meta dura poco. Genera un token permanente para un usuario del sistema antes de dejar atrás el ejemplo.

Telegram lanza un error de biblioteca al arrancar

No se encontró TDLib. El componente la carga en tiempo de ejecución con dlopen o LoadLibrary y lanza una excepción cuando eso falla. Pon el archivo junto a tu ejecutable, o define la ruta de búsqueda con SetTDJsonPath.

Los eventos se disparan en el hilo equivocado

La demo define NotifyEvents := neAsynchronous para poder tocar el formulario directamente, y su propio comentario dice que en producción se use neNoSync y que tú mismo pases al hilo de la interfaz.

Ve más a fondo

Más allá del primer mensaje

Cuatro direcciones que suele tomar el trabajo, todas dentro del mismo paquete.

Mensajes de WhatsApp más ricos

Imágenes, documentos, ubicaciones, contactos, mensajes con botones interactivos y plantillas aprobadas tienen cada uno su propio método de envío en el mismo componente.

Referencia de WhatsApp

Recibe, no solo envíes

El componente puede alojar él mismo el endpoint del webhook. StartServer lo levanta, OnBeforeSubscribe acepta o rechaza el handshake de verificación y OnMessageReceived te entrega cada mensaje entrante.

Referencia de WhatsApp

Apps completas de Telegram, no solo bots

TDLib es la misma biblioteca que usan los clientes oficiales de Telegram, así que el componente llega a cuentas de usuario, chats, multimedia y mensajes patrocinados, y no solo a la API de bots.

Referencia de Telegram

Estado de entrega

OnMessageSent informa del progreso de un mensaje que enviaste, a través de los estados que define la API: desconocido, enviado, entregado y leído.

Referencia de WhatsApp

Recursos

Referencia, demos y documentación

Las páginas de referencia documentan cada método y evento. Los proyectos de demo se incluyen dentro de la descarga, en Demos\50.Other.

Referencia, cliente de WhatsApp Todos los métodos de envío, opciones y eventos de TsgcWhatsApp_Client. Abrir
Referencia, cliente de Telegram Autorización, chats, mensajes y multimedia en TsgcTDLib_Telegram. Abrir
Página del componente TsgcWhatsApp_Client Todos los métodos de envío y eventos, con el cliente de Telegram enlazado desde ella. Abrir
Descarga la versión de prueba El mismo instalador que en producción, con límite de tiempo. Abrir
Ayuda en línea La referencia generada, siempre al día con la versión actual. Abrir
Manual de usuario (PDF) El manual completo que cubre todos los componentes de la biblioteca. Abrir

Lecturas relacionadas: el componente de WhatsApp, enviar archivos locales por WhatsApp, el cliente de Telegram y Telegram detrás de un proxy. Cada producto tiene su propio inicio rápido, listado en la página de primeros pasos.

FAQ

Preguntas sobre el inicio rápido de sgcSocial

TsgcWhatsApp_Client, en la página SGC Social de la paleta. Está declarado en sgcLibs.pas como una envoltura publicada sobre TsgcWhatsApp_Client_Base, que se declara en sgcLib_WhatsApp_Client.pas y lleva los métodos de envío. Define WhatsAppOptions.PhoneNumberId y WhatsAppOptions.Token y llama después a SendMessageText.
WhatsApp está controlado por SGC_WHATSAPP, definido en la línea 728 de sgcVer.inc, la primera línea del bloque SGC_EDT_PRO que va de la línea 727 a la 758. Eso es Professional y superiores. Telegram está controlado por SGC_TELEGRAM, definido seis veces en las líneas 677 a 694 dentro del bloque SGC_EDT_STD, líneas 675 a 724, una vez por plataforma. Así que Telegram empieza un nivel más abajo. El paquete sgcSocial independiente activa ambos mediante SGC_PACK_SOCIAL, línea 860, cuyo bloque de las líneas 968 a 971 los define sin guarda de plataforma.
Un string, que es el cuerpo de la respuesta en bruto de la API Graph de Meta. Su firma completa es function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. La demo incluida registra directamente el valor de retorno, y esa es la forma más rápida de ver un error de Meta, porque un envío rechazado vuelve en el cuerpo y no como una excepción.
El componente puede ser el servidor. Llama a StartServer y escucha él mismo el webhook de Meta. OnBeforeSubscribe te permite aceptar o rechazar la petición de verificación, y OnMessageReceived te entrega cada mensaje entrante más un indicador var aMarkAsRead que puedes activar para confirmarlo. StopServer lo apaga. Enviar no necesita nada de eso.
La biblioteca JSON nativa de TDLib junto a tu ejecutable. El componente la carga en tiempo de ejecución y la nombra por plataforma: tdjson.dll en Windows, libtdjson.dylib en macOS de 64 bits, libtdjson.so en Linux de 64 bits y en Lazarus Linux, y libtdjsonandroid.so en Android. iOS 64 es la excepción, donde la biblioteca se enlaza estáticamente como libtdjson.a. Si falta, el componente lanza una excepción en el primer uso. SetTDJsonPath lo apunta a otra carpeta.
Sí, cada uno tiene su propio método en el mismo componente: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons y SendMessageTemplate, que está sobrecargado. MarkMessageRead marca un mensaje entrante como leído.
Por el modo de hilos. La demo incluida define NotifyEvents := neAsynchronous para que sus manejadores puedan tocar controles VCL, y su propio comentario dice que en producción se use neNoSync. Con neNoSync el evento se dispara en el hilo de trabajo, que es más rápido y correcto para un servicio, y pasa a ser tu tarea trasladar al hilo de la interfaz cualquier cosa que toque la UI.
Sí. Es un paquete independiente que incluye el runtime de sgcWebSockets Core, y también forma parte de sgcWebSockets desde Professional para WhatsApp y desde Standard para Telegram. En el código fuente la vía independiente es SGC_PACK_SOCIAL en la línea 860 de sgcVer.inc, cuyo bloque de las líneas 968 a 971 define ambos clientes.
La mejor opción: All-AccessTodos los productos de eSeGeCe, con Premium Support incluido, desde €1,059 al año.
Ver precios de All-Access

¿Listo para escribir a tus clientes desde Delphi?

Descarga la versión de prueba y envía hoy tu primer mensaje de WhatsApp.

Descargar prueba gratuita Ver precios