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

Classes

    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

Public functions

    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

Public functions

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

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
    }

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
}

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": string
}

{
    "reaction": string
}

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

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

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

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

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

{
    "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.

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
    }