# 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 needs to be called. Two existing ISocketProvider (TCP and TLS) as well as an IDns instance must be passed to Create(). These instances must not be deleted before releasing the IWhatsApp instance!

## File information

File | common/interface/whatsapp.h
Classes | IWhatsAppClient UWhatsAppClient IWhatsAppOnboarding UWhatsAppOnboarding

# 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 IInstanceLog * const log,
        class IDns * const dns,
        class ISocketContext const socketContext = nullptr
        );

        virtual ~IWhatsAppClient() {}
        virtual void Close() = 0;
        virtual void SetConfig(const char * token, const char * secret) = 0;
        virtual void SetWebhookToken(const char* webhookToken) = 0;
        virtual void SendMessage(UWhatsAppClient * context, json_io value, word base, const char * remoteNum, const char * type, const char * channel, const char * callback_info=0, const char * refersToID = 0) = 0;
        virtual void RequestMedia(UWhatsAppClient * context, const char* destination, const char* mediaID, const char* detailsType) = 0;
        virtual const char* GetVersion() = 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.
Close
  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 * secret | The App-Secret from Meta

SetWebhookToken
  Sets a token that will be used for validation at registering webhooks (like receiving incoming messages) from WhatsApp at onboarding or at changing webhooks.

  #### Parameters

  const char * webhookToken | A token used for validating webhook registration

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

  UWhatsAppClient * context | The user to receive callbacks for the given message
  json_io value | json_io of the message
  word base | The jsons base
  const char * remoteNum | The mobile number of the recipients Whatsapp-Account
  const char * type | Type of the message (text, reaction, location, media, contact)
  const char *channel | The channel used for sending aka whatsapp phone_id
  const char * callback_info | Optional: additional information for the callback as src from frontend sendSrc
  const char *refersToID | Optional: Whatsapp-Message-ID of previous message that is referred to (if any)

  #### Callbacks

  After the data had been send, UWhatsAppClient::WhatsAppClientSendMessageResult() will be called.
div class="fnhead">RequestMedia
  Fetches Media from WhatsApp and posts (via HTTP) it to the given destination URL.

  #### Parameters

  UWhatsAppClient * context | The user to receive callbacks for the given message
  const char* destination | Destination to post the media to
  const char* mediaID | The WhatsApp-MediaID of the requested media (the original post from WhatsApp informing about the media will contain this data)
  const char * detailsType | Mime-Type of the requested media

GetVersion()
  Retrieves the version of the WhatsApp cloud API implemented.
<

## UWhatsAppClient

        class UWhatsAppClient {
        public:
        virtual ~UWhatsAppClient() {};
        virtual void WhatsAppClientCloseComplete(IWhatsAppClient * const whatsappClient) = 0;
        virtual void WhatsAppClientSendMessageResult(IWhatsAppClient * const whatsappClient, whatsapp_error_t error, const char * callback_info = 0, const char * content = 0) = 0;
        virtual void WhatsAppClientRecvMessage(IWhatsAppClient* const whatsappClient, const char* msg, const char* tel, const char * channel, const char * type, const char * id, const char * refersToID = 0) = 0;
        virtual void WhatsAppClientRecvMedia(IWhatsAppClient* const whatsAppClient, const char* sender, const char* channel, const char* wamid, const char* mediaid, const char* mimeType) = 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.
  const char * callback_info | Opitional: additional information for the callback as src from frontend sendSrc
  const char * content | Optional: additional content as Whatsapp-message-id

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
  const char * channel | The channel used for sending aka whatsapp phone_id
  const char * type | The type of the received message (may be "text|image|status|reaction|location|contact")
  const char * id | The Whatsapp-Message-ID of the message (necessary to refer to the message later)
  const char *refersToID | Whatsapp-Message-ID of previous message that is referred to (if any)

virtual void WhatsAppClientRecvMedia(IWhatsAppClient* const whatsAppClient, const char* sender, const char* channel, const char* wamid, const char* mediaid, const char* mimeType) = 0;
WhatsAppClientRecvMedia
  Informs the using app about incoming media. For the app to receive the media, a request to fetch it via GET-Request to /client/getMedia with Parameter id=mediaid is required.

  #### Parameters

  class IWhatsAppClient * const whatsappClient | The calling IWhatsAppClient instance
  const char * sender | The sending telephone number
  const char * channel | The channel used for sending aka whatsapp phone_id
  const char * wamid | The Whatsapp-Message-ID of the message (necessary to refer to the message later)
  const char * mediaid | The id of the media (necessary to retrieve the actual data)
  const char * mimeType | The mime-type of the media

## IWhatsAppOnboarding

        class IWhatsAppOnboarding {
        public:
        static IWhatsAppClient * Create(class IIoMux * const iomux,
        class UWhatsAppOnboarding * const user,
        class ISocketProvider * const tcpSocketProvider,
        class ISocketProvider * const tlsSocketProvider,
        class IInstanceLog * const log,
        class IDns * const dns,
        class ISocketContext const socketContext = nullptr
        );

        virtual ~IWhatsAppOnboarding() {}
        virtual void Close() = 0;
        virtual void Onboard(UWhatsAppOnbaording * context, const char* src, const char* vrsion, const char* code, const char* webhookToken, const char* wabaID, const char* callbackUri, const char* phoneID, const char* phonePin) = 0;
        };

### Overview

This is the interface to start all necessary actions to onboard a new customer, which means retrieving a token, registering all necessary webhooks and registering the main phone number. For onboarding, the WhatsAppClient needs be running too.

### Public functions

Create (static function)
  This static function creates the IWhatsAppOnboarding 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 IWhatsAppOnboarding 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.
Close
  Closes the WhatsAppOnboarding. Will usually be called from a corresponding app once the onboarding is complete.

  #### Callbacks

  Once the close is completed, UWhatsAppOnboarding::WhatsAppOnboardingCloseComplete() will be called. The WhatsAppOnboarding-Object can thus be deleted then.

## UWhatsAppOnboarding

        class UWhatsAppOnboarding {
        public:

        virtual ~UWhatsAppOnboarding() {}
        virtual void WhatsAppOnboardingCloseComplete(IWhatsAppOnboarding * const onboarding) = 0;
        virtual void WhatsAppOnboardingOnboardResult(IWhatsAppOnbaording * const onboarding, const char* callback_info, onboardingStatus status, const char* token = 0) = 0;
        };

### Overview

This is the interface to start all necessary actions to onboard a new customer, which means retrieving a token, registering all necessary webhooks and registering the main phone number. For onboarding, the WhatsAppClient needs be running too.

### Public functions

WhatsAppOnboardingCloseComplete
  Callback from calling IWhatsAppOnboarding::Close(), signaling the Object stopped all current processes and is ready for deletion.
WhatsAppOnboardingOnboardResult
  Callback from calling IWhatsAppOnboarding::Onboard(), providing the result of the onboarding.

  #### Parameters

  class IWhatsAppOnboarding * const onboarding | The onboarding instance that executed the onboarding.
  const char * callback_info | Information containing the src from the call, allowing to transmit the result back to frontend
  onboardingStatus status | The status of the onboarding. If completely successfull, the status is FINISHED. Otherwise it shows the last stage of the onboarding that was executed and failed.
  const char* token | In case of success with at least the first stage (retrieving a token), the token is returned. The token is also saved to config and will be used for further authorization agains WhatsApp.

# Data types

## whatsapp_error_t

        typedef enum {
        WHATSAPP_ERR_OK = 0,
        WHATSAPP_ERR_MISSING_TOKEN,
        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.

## onboardingStatus

        typedef enum {
        UNSTARTED,
        FETCH_TOKEN,
        REGISTER_WEBHOOKS,
        REGISTER_PHONE,
        FINISHED
        } onboardingStatus;

This enum defines the possible outcomes for an onboarding. Stages are passed from Top to Bottom, signaling the failing stage if onboarding could not completely finished, allowing further follow-up for only the unfinished stages.

# Getting the Data

The WhatsAppClient sends the data using the described methods to other Apps. The current App (Connector for WhatsApp) sends the data to Apps providing the Connect-API using methods of that API.

# 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
        }