sgcSocial em cinco minutos

Dois clientes de mensageria acompanham este pacote: o WhatsApp Business Cloud e o Telegram sobre o TDLib oficial. O WhatsApp é o caminho mais curto, porque é HTTPS puro, sem nada para distribuir, então esta página envia primeiro uma mensagem de texto do WhatsApp e depois diz o que o Telegram precisa a mais.

API WhatsApp Business Cloud
Telegram sobre o TDLib oficial
WhatsApp a partir da Professional, Telegram a partir da Standard
Visão geral

O que a primeira mensagem precisa

Um componente, dois valores do seu aplicativo Meta e uma chamada de método que retorna a resposta da API como uma string.

Componente

TsgcWhatsApp_Client na página SGC Social da paleta, declarado em sgcLibs.pas como um wrapper publicado em torno de TsgcWhatsApp_Client_Base.

Os dois valores de que você precisa

WhatsAppOptions.PhoneNumberId e WhatsAppOptions.Token, ambos obtidos no seu aplicativo de desenvolvedor da Meta. Nada mais é necessário para enviar.

A chamada

SendMessageText(aTo, aMessage) retorna uma string, o corpo bruto da resposta da API Graph da Meta. Registre-a no log e você vê imediatamente se o envio foi aceito.

O Telegram é diferente

TsgcTDLib_Telegram envolve o TDLib oficial, então precisa da biblioteca nativa ao lado do seu executável. Esse é o único passo extra, e a tabela abaixo informa o nome do arquivo por plataforma.

Antes de começar

Requisitos e edições

A coluna de edição é o define que controla cada cliente, com a linha em que ele aparece em Source/sgcVer.inc.

O quê Valor
IDE Do Delphi 7 ao RAD Studio 13, e do C++Builder 2007 ao 13.
Cláusula uses sgcLibs para as classes da paleta. O demo adiciona sgcLib_WhatsApp_Client para os tipos de opções e de mensagens.
Edição do WhatsApp SGC_WHATSAPP é definido na linha 728, a primeira linha dentro do bloco {$IFDEF SGC_EDT_PRO} que vai da linha 727 à linha 758. Ou seja, Professional e superiores.
Edição do Telegram SGC_TELEGRAM é definido nas linhas 677, 680, 683, 687, 691 e 694, todas dentro do bloco {$IFDEF SGC_EDT_STD} que vai da linha 675 à linha 724. São seis linhas porque cada uma é protegida por uma plataforma. Ou seja, Standard e superiores, nas plataformas listadas ali.
Edição, pacote independente O produto sgcSocial define SGC_PACK_SOCIAL na linha 860, e seu próprio bloco nas linhas 968 a 971 define SGC_TELEGRAM na linha 969 e SGC_WHATSAPP na linha 970. Os mesmos dois clientes, sem o restante da biblioteca.
Plataformas do WhatsApp Sem dependência nativa e sem restrição de plataforma. É HTTPS para a API Graph da Meta, então todo destino que tenha um back end TLS funciona.
Plataformas do Telegram Precisa da biblioteca JSON do TDLib ao lado do binário: tdjson.dll no Windows, libtdjson.dylib no macOS 64 bits, libtdjson.so no Linux 64 bits e no Lazarus Linux, libtdjsonandroid.so no Android. No iOS 64, a biblioteca é vinculada estaticamente como libtdjson.a em vez de carregada em tempo de execução.

Um número de teste do WhatsApp Business Cloud, um token permanente e um id de número de telefone vêm todos do console de desenvolvedor da Meta. Nada no componente os cria para você.

Passo 1

Instale e encontre a página da paleta

O sgcSocial acompanha o instalador do sgcWebSockets e também como pacote próprio. A instalação tem o mesmo formato nos dois casos.

1. Descompacte

Descompacte o download em uma pasta, chamada de {$DIR} abaixo.

2. Caminho da biblioteca

Tools, Options, Library. Adicione {$DIR}\source e a pasta lib da sua IDE, por exemplo {$DIR}\libD13\$(Platform).

3. Compile os pacotes

Abra o grupo de pacotes da versão da sua IDE em {$DIR}\Packages\. Compile primeiro o .dpk de runtime e depois instale o de design-time, o dcl.

4. Confira a paleta

Aparece uma página chamada SGC Social. Em uma compilação Standard, ela contém TsgcTDLib_Telegram. Na Professional e superiores, ela também contém TsgcWhatsApp_Client.

5. Somente para o Telegram, distribua o TDLib

Copie a biblioteca JSON do TDLib da sua plataforma para ao lado do executável. O demo do Telegram que acompanha o pacote tem tdjson.dll junto com libcrypto-3.dll, libssl-3.dll e zlib1.dll em sua pasta, que é o conjunto de que o Windows precisa.

QuickStart

Envie uma mensagem do WhatsApp, em cerca de dez linhas

Defina o id do número de telefone e o token, chame SendMessageText e leia a resposta que a API Graph devolveu.

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;

Esse é todo o caminho de envio. Nada mais precisa ser configurado e nenhum servidor precisa estar em execução. SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons e SendMessageTemplate seguem o mesmo formato.

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;

Receber é opcional. StopServer desliga o listener novamente, e OnBeforeSubscribe é onde você aceita ou rejeita a requisição de verificação da Meta, por meio de seu 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 entrar como bot, deixe PhoneNumber vazio e defina Telegram.BotToken. A partir daí, a autorização é orientada a eventos: OnAuthorizationStatus, OnAuthenticationCode e OnAuthenticationPassword pedem a você o que o TDLib precisa em seguida.

As duas primeiras abas são o demo que acompanha o pacote, Demos\50.Other\05.WhatsApp\FWhatsApp.pas, com os controles do formulário substituídos por literais. O botão de envio desse demo na verdade chama SendMessageLocation; a chamada de texto mostrada aqui é o caminho SendMessageText do mesmo arquivo. A aba do Telegram mostra a única linha que é diferente de todos os outros componentes da biblioteca.

Passo 2

Confira se a mensagem foi aceita

Dois níveis de prova: o que a chamada de envio retorna e o que o webhook informa depois.

O valor de retorno

SendMessageText retorna o corpo da resposta da API Graph como uma string. Registre-o no log. Um erro da Meta chega nesse corpo e não como exceção, então um envio que parece não fazer nada geralmente tem a explicação ali mesmo.

OnMessageSent

Informa o que aconteceu com uma mensagem depois, por meio de um valor de status que passa de desconhecido para enviado, entregue e lido. Precisa do servidor de webhook em execução, porque o status chega como um callback de entrada.

OnMessageReceived

procedure(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean). Defina aMarkAsRead para confirmar a mensagem, que é o que coloca os tiques azuis na tela do remetente.

Telegram

OnConnectionStatus e OnAuthorizationStatus são os dois a acompanhar. O TDLib faz o login em várias etapas, então os eventos de status são a única forma confiável de saber em que ponto dessa sequência você está.

Problemas comuns

O que costuma dar errado na primeira vez

Seis problemas respondem por quase todo primeiro envio que falha.

O componente não está na paleta

TsgcWhatsApp_Client só é compilado quando SGC_WHATSAPP está definido, o que acontece na linha 728, dentro do bloco Professional. Em uma compilação Standard, você tem o Telegram e não o WhatsApp.

O envio retorna um erro sobre um modelo

O WhatsApp só permite uma mensagem de texto livre dentro da janela de atendimento ao cliente, que se abre quando o usuário envia mensagem primeiro. Fora dela, você deve enviar um modelo aprovado, que é SendMessageTemplate, não SendMessageText.

Nada chega e nenhum erro é gerado

Leia o valor de retorno. SendMessageText retorna a resposta bruta da API Graph como uma string, e o demo a registra diretamente. Um erro da Meta volta nesse corpo.

O token expira depois de um dia

O token temporário do console da Meta tem vida curta. Gere um token permanente para um usuário de sistema antes de deixar o exemplo para trás.

O Telegram gera um erro de biblioteca na inicialização

O TDLib não foi encontrado. O componente o carrega em tempo de execução com dlopen ou LoadLibrary e gera uma exceção quando isso falha. Coloque o arquivo ao lado do seu executável ou defina o caminho de busca com SetTDJsonPath.

Os eventos disparam na thread errada

O demo define NotifyEvents := neAsynchronous para poder tocar o formulário diretamente, e seu próprio comentário diz para usar neNoSync em produção e fazer você mesmo o redirecionamento para a thread da interface.

Aprofunde-se

Além da primeira mensagem

Quatro direções que o trabalho costuma tomar, todas dentro do mesmo pacote.

Mensagens do WhatsApp mais ricas

Imagens, documentos, localizações, contatos, mensagens com botões interativos e modelos aprovados têm, cada um, seu próprio método de envio no mesmo componente.

Referência do WhatsApp

Receba, não apenas envie

O componente pode hospedar o próprio endpoint de webhook. StartServer o inicia, OnBeforeSubscribe aceita ou rejeita o handshake de verificação e OnMessageReceived entrega cada mensagem recebida.

Referência do WhatsApp

Aplicativos Telegram completos, não apenas bots

O TDLib é a mesma biblioteca que os clientes oficiais do Telegram usam, então o componente alcança contas de usuário, chats, mídia e mensagens patrocinadas, e não apenas a API de bots.

Referência do Telegram

Status de entrega

OnMessageSent informa o andamento de uma mensagem que você enviou, pelos estados que a API define: desconhecido, enviado, entregue e lido.

Referência do WhatsApp

Recursos

Referência, demos e documentação

As páginas de referência documentam cada método e evento. Os projetos de demo acompanham o download, em Demos\50.Other.

Referência, cliente WhatsApp Cada método de envio, opção e evento de TsgcWhatsApp_Client. Abrir
Referência, cliente Telegram Autorização, chats, mensagens e mídia em TsgcTDLib_Telegram. Abrir
Página do componente TsgcWhatsApp_Client Cada método de envio e evento, com o cliente Telegram ligado a partir dela. Abrir
Baixe a versão de avaliação O mesmo instalador da versão de produção, com tempo limitado. Abrir
Ajuda online A referência gerada, sempre alinhada com a versão atual. Abrir
Manual do usuário (PDF) O manual completo que cobre todos os componentes da biblioteca. Abrir

Leitura relacionada: o componente WhatsApp, envio de arquivos locais pelo WhatsApp, o cliente Telegram e o Telegram atrás de um proxy. Cada produto tem seu próprio início rápido, listado na página de primeiros passos.

FAQ

Perguntas sobre o início rápido do sgcSocial

TsgcWhatsApp_Client, na página SGC Social da paleta. Ele é declarado em sgcLibs.pas como um wrapper publicado em torno de TsgcWhatsApp_Client_Base, que é declarado em sgcLib_WhatsApp_Client.pas e traz os métodos de envio. Defina WhatsAppOptions.PhoneNumberId e WhatsAppOptions.Token e depois chame SendMessageText.
O WhatsApp é controlado por SGC_WHATSAPP, definido na linha 728 de sgcVer.inc, a primeira linha do bloco SGC_EDT_PRO que vai da linha 727 à linha 758. Isso é Professional e superiores. O Telegram é controlado por SGC_TELEGRAM, definido seis vezes nas linhas 677 a 694, dentro do bloco SGC_EDT_STD, linhas 675 a 724, uma vez por plataforma. Portanto, o Telegram começa um nível abaixo. O pacote sgcSocial independente ativa os dois por meio de SGC_PACK_SOCIAL, linha 860, cujo bloco nas linhas 968 a 971 os define sem restrição de plataforma.
Uma string, que é o corpo bruto da resposta da API Graph da Meta. Sua assinatura completa é function SendMessageText(const aTo, aMessage: string; aPhoneNumberId: string = ''; const aOptions: TsgcWhatsApp_Message_Options = nil): string. O demo que acompanha o pacote registra o valor de retorno diretamente, e essa é a forma mais rápida de ver um erro da Meta, porque um envio rejeitado volta no corpo e não como exceção.
O componente pode ser o servidor. Chame StartServer e ele escuta o webhook da Meta por conta própria. OnBeforeSubscribe permite aceitar ou rejeitar a requisição de verificação, e OnMessageReceived entrega cada mensagem recebida, além de um flag var aMarkAsRead que você pode definir para confirmá-la. StopServer o desliga. Para enviar, nada disso é necessário.
A biblioteca JSON nativa do TDLib ao lado do seu executável. O componente a carrega em tempo de execução e a nomeia por plataforma: tdjson.dll no Windows, libtdjson.dylib no macOS 64 bits, libtdjson.so no Linux 64 bits e no Lazarus Linux, e libtdjsonandroid.so no Android. O iOS 64 é a exceção, em que a biblioteca é vinculada estaticamente como libtdjson.a. Se ela estiver ausente, o componente gera uma exceção no primeiro uso. SetTDJsonPath o aponta para outra pasta.
Sim, cada um tem seu próprio método no mesmo componente: SendMessageImage, SendMessageDocument, SendMessageLocation, SendMessageContact, SendMessageInteractiveButtons e SendMessageTemplate, que é sobrecarregado. MarkMessageRead marca uma mensagem recebida como lida.
Por causa do modo de threading. O demo que acompanha o pacote define NotifyEvents := neAsynchronous para que seus manipuladores possam tocar os controles VCL, e seu próprio comentário diz para usar neNoSync em produção. Com neNoSync, o evento dispara na thread de trabalho, o que é mais rápido e correto para um serviço, e passa a ser sua tarefa redirecionar para a thread da interface qualquer coisa que a toque.
Sim. É um pacote independente com o runtime sgcWebSockets Core incluído, e também faz parte do sgcWebSockets a partir da Professional para o WhatsApp e da Standard para o Telegram. No código-fonte, o caminho independente é SGC_PACK_SOCIAL na linha 860 de sgcVer.inc, cujo bloco nas linhas 968 a 971 define os dois clientes.
Melhor custo-benefício: All-AccessTodos os produtos da eSeGeCe, com Suporte Premium incluído, a partir de €1,059/ano.
Ver preços do All-Access

Pronto para enviar mensagens aos seus clientes a partir do Delphi?

Baixe a versão de avaliação e envie hoje mesmo sua primeira mensagem do WhatsApp.

Baixar avaliação gratuita Ver preços