WhatsApp Client

The IWhatsApp interface is for working with a WhatsApp Connector to a companies' WhatsApp Business Account.

To create an IWhatsApp instance, the static Create() function need to be called. Two existing ISocketProvider as well as an IDns instance must be passed to Create(). Those interfaces must not be deleted before releasing the IWhatsApp instance!

File information

File	common/interface/whatsapp.h
Classes	IWhatsAppClient UWhatsAppClient

Classes

IWhatsAppClient


    class IWhatsAppClient {
    public:
    static IWhatsAppClient * Create(class IIoMux * const iomux,
    class UWhatsAppClient * const user,
    class ISocketProvider * const tcpSocketProvider,
    class ISocketProvider * const tlsSocketProvider,
    class IDns * const dns,
    class IInstanceLog * const log);

    virtual ~IWhatsAppClient() {}
    virtual void Close();
    virtual void SetConfig(const char * token, const char * id, const char * version,  const char * webhooktoken, const char * secret) = 0;
    virtual void SendMessage(const char * msg, const char * tel, UWhatsAppClient * context) = 0;
    virtual void Subscribe(UWhatsAppClient * subscriber, const char * tel = 0) = 0;
    virtual void Unsubscribe(UWhatsAppClient * unsubscriber, const char * tel = 0) = 0;
    };

Overview

This is the interface to establish a WhatsApp for Business connection. The interface is quite simple and straight forward to use.

Public functions

Create (static function)

This static function creates the IWhatsAppClient Instance. The returned instance must be released if no longer needed by using the C++ delete operator.

Parameters

class IIoMux * const iomux	The IIoMux instance the IWhatsAppClient instance will be registered to.
class UWhatsAppClient * const user	The UWhatsAppClient instance that will receive the callbacks of IWhatsAppClient.
class IWebserverPlugin * const webserver	instance that can create a Webserver Plugin.
class ISocketProvider * const tcpSocketProvider	A ISocketProvider instance that can create a TCP ISocket.
class ISocketProvider * const tlsSocketProvider	A ISocketProvider instance that can create a TLS ISocket.
class IInstanceLog * const log	The IInstanceLog instance used for logging purposes.
class IDns * const dns	The IDns instance used to resolve the server name if needed.
class ISocketContext * const socketContext dns	The ISocketContext Socket context if needed

Return value

The IWhatsAppClient Instance created. It must be freed by the C++ operator delete, if no longer be used.

Remarks

Note that the two ISocketProvider instances as well as the IDns instance must not be freed before the IWhatsAppClient instance had been deleted.

Closes the WhatsAppClient. Will usually be called from a corresponding app.

Callbacks

Once the close is completed, UWhatsAppClient::WhatsAppClientCloseComplete() will be called. The WhatsAppClient-Object can thus be deleted then.

SetConfig

Sets certain configurations that are necessary to send or receive Messages to/from WhatsApp. The App-Secret can be found in the Meta-Appdashboard. It is necessary for accepting incoming messages.

Parameters

const char * token	A token used for authentication with WhatsApp
const char * id	The Account-ID of the (sending) WhatsApp-Business-Account
const char * version	The version of the WhatsApp interface
const char * webhooktoken	The set token for a webhook (only needed for webhook-registration)
const char * secret	The App-Secret from Meta

SendMessage

Sends the given data to the (private) WhatsApp Messenger Account identified by the phone number. A message to a private Account will only be delivered if a message from that private Account had been received within 24 hours before. Template-Messages are an exception an can be sent without preceding initiation from the private Account. If the data could not be send right now, it will be cached and sent later. The context will be informed if the data had been finally send or any errors that occur instead.

Parameters

const char * msg	The message to send
const char * tel	The phone number of the recipients Whatsapp-Account
UWhatsAppClient * context	The user to receive callbacks for the given message

Callbacks

After the data had been send, UWhatsAppClient::WhatsAppClientSendMessageResult() will be called.

Subscribing a user for receiving incoming WhatsApp-Messages for a given phone number. If no phone number is given, the user will receive all incoming messages.

Parameters

UWhatsAppClient * subscriber	The user to receive incoming messages
const char * tel	The phone number to subscribe. If 0 all incoming messages are received

Unsubscribe

Unsubscribes a user for receiving WhatsApp-Messages for a given phone number. If no phone number is given, all subscriptions will be deleted and hence no messages will be received anymore.

Parameters

UWhatsAppClient * unsubscriber	The user to unsubscribe
const char * tel	The phone number to unsubscribe. If 0 all subscriptions are cancelled

UWhatsAppClient


    class UWhatsAppClient {
    public:
    virtual ~UWhatsAppClient() {};
    virtual void WhatsAppClientCloseComplete(IWhatsAppClient * const whatsappClient);
    virtual void WhatsAppClientSendMessageResult(IWhatsAppClient * const whatsappClient, whatsapp_error_t error);
    virtual void WhatsAppClientRecvMessage(IWhatsAppClient* const whatsappClient, const char* msg, const char* tel) = 0;
    };

Overview

The UWhatsAppClient class is used to receive callbacks from an IWhatsAppClient instance. An application must subclass UWhatsAppClient, implement the functions that must be implemented and pass that class as user to IWhatsAppClient::Create(). The instance of that subclass must not be freed before the IWhatsAppClient instance assigned to. One UWhatsAppClient instance can be assigned to multiple IWhatsAppClient instances, because the calling IWhatsAppClient will be passed as parameter to the callback functions.

Public functions

WhatsAppClientCloseComplete

Will be called after calling IWhatsAppClient::Close(). After receiving that callback, the IWhatsAppClient-Object can be deleted.

Parameters

class IWhatsAppClient * const whatsappClient

The calling IWhatsAppClient instance

WhatsAppClientSendMessageResult

Will be called after calling IWhatsAppClient::SendMessage(). After receiving that callback, the IWhatsAppClient instance can be used to send data and receive reactions.

Parameters

class IWhatsAppClient * const whatsappClient	The calling IWhatsAppClient instance
whatsapp_error_t error	The error status after sending. See whatsapp_error_t for more information

WhatsAppClientRecvMessage

Passes an incoming message from whatsapp to a user who has subscribed for receiving Messages for the phone number (or all Messages).

Parameters

class IWhatsAppClient * const whatsappClient	The calling IWhatsAppClient instance
const char * msg	The received Message
const char * tel	The sending telephone number

Data types

whatsapp_error_t


    typedef enum {
    WHATSAPP_ERR_OK = 0,
    WHATSAPP_ERR_MISSING_TOKEN,
    WHATSAPP_ERR_MISSING_ACCOUNT_ID,
    WHATSAPP_ERR_MISSING_VERSION,
    WHATSAPP_ERR_NOT_FOUND,
    WHATSAPP_ERR_BAD_REQUEST,
    WHATSAPP_ERR_AUTHENTICATION_FAILED,
    WHATSAPP_ERR_OTHER_HTTP,
    WHATSAPP_ERR_CLOSING
    } whatsapp_error_t;

This enum defines the possible outcomes for sending a message via the connector. One of them will be returned at UWhatsAppClient::WhatsAppClientSendMessageResult.

Code Example

IWhatsAppClient


    app::app(class IIoMux * iomux,
    ISocketProvider * tcpSocketProvider,
    ISocketProvider * tlsSocketProvider,
    IDns * dns,
    IInstanceLog * log)
    : iomux(iomux)
    {
        this->client = IWhatsAppClient::Create(iomux,
                                                this,
                                                webserverPlugin,
                                                tcpSocketProvider,
                                                tlsSocketProvider,
                                                this,
                                                dns);
    isTerminating = false;
    }

    void WhatsApp::Stop(){
    if (!isTerminating) {
        isTerminating = true;
        if (client != nullptr) client->Close();
        TryStop();
        }
    }

    void WhatsApp::TryStop(){
        if (isTerminating && client == nullptr) appService->AppStopped(this);
    }



    void app::WhatsAppClientCloseComplete(IWhatsAppClient* const whatsappClient){
        delete client;
        client = nullptr;
        TryStop();
    }

    void app::WhatsAppClientSendMessageResult(IWhatsAppClient* const whatsappClient, whatsapp_error_t error){
        //can ignore the result or act according to it
    }