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

Classes

    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 * tel, const char * type, 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;
    virtual void SetChannels(const char* channels) = 0;
    virtual char* GetChannelsConfig() = 0;
    virtual const char* GetVersion() = 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 WhatsAppClientRecvMedia(IWhatsAppClient* const whatsAppClient, const char* sender, const char* channel, const char* wamid, const char* mediaid, const char* mimeType) = 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

    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

Public functions

    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

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.

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.

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 retrieve a list of available channels for the business account (as defined in config). Call before subscribe for selection.

{
    "mt": "GetChannels",
    "api": "com.innovaphone.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": 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
    }