WhatsApp Cloud API

Overview

WhatsApp Cloud API client — Meta-hosted WhatsApp Business messaging, templates and media for Delphi. The component is part of the sgcWebSockets library.

At a glance

Features

• Native Delphi implementation with full ANSI/Unicode support.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical Get Started configuration sourced from the online help.

Delphi (VCL / FireMonkey)

oClient := TsgcWhatsapp_Client.Create(nil);
oClient.WhatsappOptions.PhoneNumberId := '107809351952205';
oClient.WhatsappOptions.Token := 'EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2';
oClient.SendTest('34605889421');

C++ Builder

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient->WhatsappOptions->PhoneNumberId = "107809351952205";
oClient->WhatsappOptions->Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient->SendTest("34605889421");

.NET (C#)

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient.WhatsappOptions.PhoneNumberId = "107809351952205";
oClient.WhatsappOptions.Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient.SendTest("34605889421");

Common scenarios

The following scenarios are lifted verbatim from the online help. Each shows the configuration and method calls needed to drive the component through a specific real-world flow.

1 · Received Messages

Every time a new message is received the event OnMessageReceived is called, where you can access to the content of the Message and mark the message as read.

procedure OnWhatsAppMessageReceived(Sender: TObject; const aMessage: TsgcWhatsApp_Receive_Message; var aMarkAsRead: Boolean);
var
  vText: string;
  vTo: string;
begin
  if aMessage.Contacts.Count > 0 then
  begin
    vTo := aMessage.Contacts.Contact[0].WaID;
    if aMessage.Messages.Count > 0 then
    begin
      if aMessage.Messages._Message[0]._Type = wapmrtText then
      begin
        vText := 'ECHO ==> ' + aMessage.Messages._Message[0].Text.Body;
        WhatsApp.SendMessageText(vTo, vText);
        aMarkAsRead := True;
      end;
    end;
  end;
end;

void OnWhatsAppMessageReceived(TObject *Sender, const TsgcWhatsApp_Receive_Message *aMessage, ref bool aMarkAsRead)
{
  if (aMessage->Contacts->Count > 0)
  {
    string vTo = aMessage->Contacts->Contact[0]->WaID;
    if (aMessage->Messages->Count > 0)
    {
      if (aMessage->Messages->_Message[0]->_Type = wapmrtText)
      {
        vText = "ECHO ==> " + aMessage->Messages->_Message[0]->Text->Body;
        WhatsApp->SendMessageText(vTo, vText);
        aMarkAsRead = true;
      }
    }
  }
}

void OnWhatsAppMessageReceived(TsgcWhatsApp_Client Sender, TsgcWhatsApp_Receive_Message Message, ref bool MarkAsRead)
{
  DoLog("Message Received: [" + Message.From + "] " + Message.Text);
 MarkAsRead = true;
}

2 · Create Endpoint

Before you can start receiving notifications you will need to create an endpoint on your server to receive notifications.

oClient := TsgcWhatsapp_Client.Create(nil);
oClient.ServerOptions.WebhookOptions.Endpoint := '/webhook';
oClient.ServerOptions.WebhookOptions.Token := 'MySecretToken';
oClient.StartServer();

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient->ServerOpptions->WebhookOptions->PhoneNumberId = "/webhook";
oClient->ServerOptions->WebhookOptions->Token = "MySecretToken";
oClient->StartServer();

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient.ServerOptions.WebhookOptions.PhoneNumberId = "/webhook";
oClient.ServerOptions.WebhookOptions.Token = "MySecretToken";
oClient.StartServer();

3 · Image Messages

Call the method SendMessageImage and pass the following parameters:

oClient := TsgcWhatsApp_Client.Create(nil);
oClient.WhatsappOptions.PhoneNumberId := '107809351952205';
oClient.WhatsappOptions.Token := 'EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2';
oClient.SendFileImage('34605889421', 'c:\images\image.png', 'image/png');

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient->WhatsappOptions->PhoneNumberId = "107809351952205";
oClient->WhatsappOptions->Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient->SendFileImage("34605889421", "c:\images\image.png", "image/png");

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient.WhatsappOptions.PhoneNumberId = "107809351952205";
oClient.WhatsappOptions.Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient.SendFileImage("34605889421", "c:\images\image.png", "image/png");

4 · Interactive List

Interactive messages give your users a simpler way to find and select what they want from your business on WhatsApp. During testing, chatbots using interactive messaging features achieved significantly higher response rates and conversions compared to those that are text-based.

oClient := TsgcWhatsApp_Client.Create(nil);
oClient.WhatsappOptions.PhoneNumberId := '107809351952205';
oClient.WhatsappOptions.Token := 'EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2';
oClient.SendMessageInteractiveList('34605889421', 'What Would you like to do today?', 'To begin, Tap Main Menu and choose from of the following options', '', 'Main Menu', ['Buy bundles', 'Buy airtime', 'Manage your account', 'FAQs', 'Get help with a problem']);

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient->WhatsappOptions->PhoneNumberId = "107809351952205";
oClient->WhatsappOptions->Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient->SendMessageInteractiveList("</code><code class="delphi">34605889421</code><code class="cpp">", "What Would you like to do today?", "To begin, Tap Main Menu and choose from of the following options", "", "Main Menu", ["Buy bundles", "Buy airtime", "Manage your account", "FAQs", "Get help with a problem"]);

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient.WhatsappOptions.PhoneNumberId = "107809351952205";
oClient.WhatsappOptions.Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient.SendMessageInteractiveList("</code><code class="delphi">34605889421</code><code class="csharp">", "What Would you like to do today?", "To begin, Tap Main Menu and choose from of the following options", "", "Main Menu", "Buy bundles", "Buy airtime", "Manage your account", "FAQs", "Get help with a problem");

5 · Template Message Parameters

Templates can include parameters, see below an example of default template with parameters

procedure SendSamplePurchaseFeedbackTemplate(const aName: string);
var
  oTemplate: TsgcWhatsApp_Send_Message_Template;
  oComponent: TsgcWhatsApp_Send_Message_Template_Component;
  oParameter: TsgcWhatsApp_Send_Message_Template_Parameter;
begin
  oTemplate := TsgcWhatsApp_Send_Message_Template.Create;
  Try
    oTemplate.Language.Code := 'en_US';
    oTemplate.TemplateName := 'sample_purchase_feedback';
    // ... header
    oComponent := TsgcWhatsApp_Send_Message_Template_Component.Create;
    oComponent._Type := wapctHeader;
    oTemplate.Components.Add(oComponent);
    oParameter := TsgcWhatsApp_Send_Message_Template_Parameter.Create;
    oParameter.Image.Link := 'https://www.esegece.com/images/esegece.png';
    oParameter._Type := wapptImage;
    oComponent.Parameters.Add(oParameter);
    // ... body
    oComponent := TsgcWhatsApp_Send_Message_Template_Component.Create;
    oComponent._Type := wapctBody;
    oTemplate.Components.Add(oComponent);
    oParameter := TsgcWhatsApp_Send_Message_Template_Parameter.Create;
    oParameter.Text := aName;
    oParameter._Type := wapptText;
    oComponent.Parameters.Add(oParameter);
    whatsapp.SendMessageTemplate('107809351952205', oTemplate);
  Finally
    oTemplate.Free;
  End;
end;

void SendSamplePurchaseFeedbackTemplate(string aName)
{
  TsgcWhatsApp_Send_Message_Template *oTemplate = new TsgcWhatsApp_Send_Message_Template();
  Try
    oTemplate->Language->Code = "en_US";
    oTemplate->TemplateName = "sample_purchase_feedback";
    // ... header
    TsgcWhatsApp_Send_Message_Template_Component *oComponent = new TsgcWhatsApp_Send_Message_Template_Component();
    oComponent->_Type = wapctHeader;
    oTemplate->Components->Add(oComponent);
    TsgcWhatsApp_Send_Message_Template_Parameter *oParameter = new TsgcWhatsApp_Send_Message_Template_Parameter();
    oParameter->Image->Link = "https://www.esegece.com/images/esegece.png";
    oParameter->_Type = wapptImage;
    oComponent->Parameters->Add(oParameter);
    // ... body
    TsgcWhatsApp_Send_Message_Template_Component *oComponent = new TsgcWhatsApp_Send_Message_Template_Component();
    oComponent->_Type = wapctBody;
    oTemplate->Components->Add(oComponent);
    TsgcWhatsApp_Send_Message_Template_Parameter *oParameter = new TsgcWhatsApp_Send_Message_Template_Parameter();
    oParameter->Text = aName;
    oParameter->_Type = wapptText;
    oComponent->Parameters->Add(oParameter);
    whatsapp->SendMessageTemplate("107809351952205", oTemplate);
  __Finally
    oTemplate->Free();
  End;
}

void SendSamplePurchaseFeedbackTemplate(string aName)
{
  TsgcWhatsApp_Send_Message_Template oTemplate = new TsgcWhatsApp_Send_Message_Template();
  oTemplate.Language.Code = "en_US";
  oTemplate.TemplateName = "sample_purchase_feedback";
  // ... header
  TsgcWhatsApp_Send_Message_Template_Component oComponent = new TsgcWhatsApp_Send_Message_Template_Component();
  oComponent._Type = wapctHeader;
  oTemplate.Components.Add(oComponent);
  TsgcWhatsApp_Send_Message_Template_Parameter oParameter = new TsgcWhatsApp_Send_Message_Template_Parameter();
  oParameter.Image.Link = "https://www.esegece.com/images/esegece.png";
  oParameter._Type = wapptImage;
  oComponent.Parameters.Add(oParameter);
  // ... body
  TsgcWhatsApp_Send_Message_Template_Component oComponent2 = new TsgcWhatsApp_Send_Message_Template_Component();
  oComponent2._Type = wapctBody;
  oTemplate.Components.Add(oComponent2);
  TsgcWhatsApp_Send_Message_Template_Parameter oParameter2 = new TsgcWhatsApp_Send_Message_Template_Parameter();
  oParameter2.Text = aName;
  oParameter2._Type = wapptText;
  oComponent2.Parameters.Add(oParameter2);
  whatsapp.SendMessageTemplate("107809351952205", oTemplate);
}

6 · Text Messages

Call the method SendMessageText and pass the following parameters:

oClient := TsgcWhatsApp_Client.Create(nil);
oClient.WhatsappOptions.PhoneNumberId := '107809351952205';
oClient.WhatsappOptions.Token := 'EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2';
oClient.SendMessageText('34605889421', 'Hello from sgcWebSockets!!!');

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient->WhatsappOptions->PhoneNumberId = "107809351952205";
oClient->WhatsappOptions->Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient->SendMessageText("34605889421", "Hello from sgcWebSockets!!!");

TsgcWhatsapp_Client oClient = new TsgcWhatsapp_Client();
oClient.WhatsappOptions.PhoneNumberId = "107809351952205";
oClient.WhatsappOptions.Token = "EAAO4OpgZAs98BAGj3nCFGr...ZB2t8mmLB2LRXJkte2Y5PMNh2";
oClient.SendMessageText("34605889421", "Hello from sgcWebSockets!!!");

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.