# 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 * version,  const char * webhooktoken, const char * secret) = 0;
        virtual void SendMessage(const char * msg, const char * tel, UWhatsAppClient * context, const char * channel, const char * callback_info=0, const char * refersToID = 0) = 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.
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 * 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
  const char *channel | The channel used for sending aka whatsapp phone_id
  const char * callback_info | Opitional: additional information for the callback as src from frontend sendSrc
  const char *refersToID | Whatsapp-Message-ID of previous message that is referred to (if any)

  #### Callbacks

  After the data had been send, UWhatsAppClient::WhatsAppClientSendMessageResult() will be called.
Subscribe
  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) = 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 WhatsAppClientForwardMessage(IWhatsAppClient* const whatsappClient, const char* msg, const char* tel, const char* channel, const char* type, const char* id, const char * refersToID = 0) = 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
  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)

WhatsAppClientForwardMessage
  Forwards a message from one app that subscribed for a channel to another app that subscribed to the same channel to avoid multiple answers to the same original post from a whatsapp user.

  #### Parameters

  class IWhatsAppClient * const whatsappClient | The calling IWhatsAppClient instance
  const char * msg | The forwarded message
  const char * tel | The target telephone number from the forwarded message
  const char * channel | The channel that originally sent the message
  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 original message (necessary to refer to the message later)
  const char *refersToID | Whatsapp-Message-ID of previous message that is referred to (if any)

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

# API

## Overview

Below is the description of the API messages that are sent or accepted by the whatsapp-client if used with the class whatsapp.cpp. Note that any optional value is marked by =0.

## Subscribing for incoming Messages

This message can be sent in order to subscribe for incoming messages from a specific channel (whatsapp phone_number_id) or all registered channels (if no specific channel is given).

    {
        "mt": "Subscribe",
        "api": "com.innovaphone.whatsapp",
        "channel": string
        }

## Unsubscribing

This message can be sent in order to unsubscribe for incoming messages from a specific channel (whatsapp phone_number_id) or all subscribed channels (if no specific channel is given).

    {
        "mt": "Unsubscribe",
        "api": "com.innovaphone.whatsapp",
        "channel": string
    }

## Sending to WhatsApp

This message can be sent in order to sent a message to a customer via WhatsApp. As there exist many different types of message that can be sent, there is a basic part of the message and additional parts. remoteNum defines the customers phone-number, channel the phone-id that will be used as sender-number.
Please note that currently only text is supported!

    {
        "mt": "SendMessage",
        "api": "com.innovaphone.whatsapp",
        "remoteNum": string,
        "channel": string,
        "type": string,
        "value": JsonObject
    }

The JsonObject "value" can be one of the following and aligns with the type of the message.

text
reaction
location
media
template
contact

### type = "text"

    {
        "text": string
    }

### type = "reaction"

    {
        "reaction": string
    }

### type = "location"

    {
        "lat": string,
        "lon": string,
        "name": string = 0,
        "address": string = 0
    }

### type = "media"

    {
        "path": string,
        "mediatype": string,
        "caption": string,
        "filename": string
    }

Mediatype can be "audio", "document", "image", "sticker", or "video".

### type = "template"

    {
        "name": string,
        "language": string,
        "components": [{"text": string}],
    }

Components are optional and represent text to fill in specific spaces in the template if any.

### type = "contact"

    {
        "name":         {
                        "fullName": string,
                        "firstName": string = 0,
                        "lastName": string = 0,
                        "middleName": string = 0,
                        "suffix": string = 0,
                        "prefix": string = 0
                        },
        "addresses":    [{
                        "street": string = 0,
                        "city": string = 0,
                        "state": string = 0,
                        "zip": string = 0,
                        "country": string = 0,
                        "countryCode": string = 0,
                        "type": string = 0
                        }] = 0,
        "birthday": string = 0,
        "emails":       [{
                        "email": string = 0,
                        "type": string = 0
                        }] = 0,
        "organisation": {
                        "company": string = 0,
                        "department": string = 0,
                        "title": string = 0
                        } = 0,
        "phones":       [{
                        "phone": string = 0,
                        "type": string = 0,
                        "waUID": string = 0
                        }] = 0
    }

For addresses and emails type may be "WORK" or "HOME". Accepted types for phones are "CELL", "MAIN", "IPHONE", "HOME", "WORK". Birthday is to be given in format: "YYYY-MM-DD". waUID means Whatsapp User-ID. Beside the fullName, at least one more field of name must be filled (as decided by whatsapp)

## Possible Results from Sending to WhatsApp

    {
        "mt": "SendMessageResult",
        "api": "com.innovaphone.whatsapp",
        "status": string,
        "wamid": string = 0,
        "error": boolean = 0,
        "errorText": string = 0
    }

Status will be "Transmitted", "Sent" or any of whatsapp_error_t.

## Incoming Messages from Connector

If incoming messages are received at the connector, after processing them the connector is expected to send out one of the following messages.

    {
        "mt": "RecvMessage",
        "api": "com.innovaphone.whatsapp",
        "remoteNum": string,
        "channel": string,
        "wamid": string,
        "type": string,
        "value": JsonObject
    }

"value" can take the same values as in SendMessage.

    {
        "mt": "ForwardMessage",
        "api": "com.innovaphone.whatsapp",
        "remoteNum": string,
        "channel": string,
        "wamid": string,
        "type": string,
        "value": JsonObject
    }

"value" can take the same values as in SendMessage.

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