whatsapp-client-service plugin

Technical description of whatsapp-client-service plugin

Introduction

whatsapp-client-service plugin contains the services and utilities related to the WhatsApp channel. This plugin also contains the WhatsApp client to send messages to WhatsApp through Kernel.

The specific environment variables for this plugin are located at whatsapp-client-service plugin configuration.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
prometheus	PluginType.Service	Metrics client for Prometheus

Provides components (IOC)

Name	Type	Description
whatsappClient	PluginType.Client	WhatsApp client

whatsappClient plugin

The WhatsappClient class extends from the AuraBridgeClientOAuthTokens class to obtain the access tokens used in OpenId authentication necessary to perform communications with the Kernel API.

The WhatsappClient allows sending requests to WhatsApp through the Kernel API and is responsible for managing and refreshing all the access tokens of the whatsapp channel type.

Management of multiple Kernel WhatsApp APIs

WhatsappClient is able to handle multiple versions of Kernel WhatsApp APIs. Every channel could have in its configuration a version field with the Kernel WhatsApp API version, and this is the version to be used. By default, if no version is configured, WhatsappClient will use v1. Currently, v1 and v2 are supported.

Configuration by channel

The whatsApp.client field allows the configuration of WhatsappClient options. The interface for this field is defined as follows:

export interface FPClientModel {
    /** Client id */
    id: string;
    /** Client secret */
    secret: string;
    /** Client purposes */
    purposes?: string;
    /** Client scopes */
    scopes?: string;
    /** Client version */
    version?: string;
}

Example:

{
    ...
    "type": "whatsapp",
    "whatsapp": {
        "client": {
            "id": "client-id",              // Client id
            "purposes": "client-purposes",  // Client purposes
            "scopes": "client-scopes",      // Client scopes
            "secret": "client-secret"       // Client secret
            "version": "v1"
        }
    }
}

Error management policy

The WhatsappClient defines its own retry policy when an error occurs.

export const whatsappClientErrorPolicy: IndexedErrorPolicy = {
    // Client code (whatsapp)
    responseCode: {
        429: {
            description: 'The frequency limit was reached',
            recoverable: true
        },
        500: {
            description: 'Generic error-Message failed to send because of an unknown error.Try again later.',
            recoverable: true
        },
        1015: {
            description: 'Customer frequency limit reached.',
            recoverable: true
        },
        1016: {
            description: 'System overloaded.',
            recoverable: true
        },
        1017: {
            description: 'It is not the main master node.',
            recoverable: true
        },
        1018: {
            description: 'It is not a primary main app.',
            recoverable: true
        }
    },
    // Http status (4P)
    status: {
        // 404
        [StatusCodes.NOT_FOUND]: {
            description: ReasonPhrases.NOT_FOUND,
            recoverable: true
        },
        // 408
        [StatusCodes.REQUEST_TIMEOUT]: {
            description: ReasonPhrases.REQUEST_TIMEOUT,
            recoverable: true
        },
        // 409
        [StatusCodes.CONFLICT]: {
            description: ReasonPhrases.CONFLICT,
            recoverable: true
        },
        // 413
        [StatusCodes.REQUEST_TOO_LONG]: {
            description: ReasonPhrases.REQUEST_TOO_LONG,
            recoverable: true
        },
        // 500
        [StatusCodes.INTERNAL_SERVER_ERROR]: {
            description: ReasonPhrases.INTERNAL_SERVER_ERROR,
            recoverable: true
        },
        // 502
        [StatusCodes.BAD_GATEWAY]: {
            description: ReasonPhrases.BAD_GATEWAY,
            recoverable: true
        },
        // 503
        [StatusCodes.SERVICE_UNAVAILABLE]: {
            description: ReasonPhrases.SERVICE_UNAVAILABLE,
            recoverable: true
        },
        // 504
        [StatusCodes.GATEWAY_TIMEOUT]: {
            description: ReasonPhrases.GATEWAY_TIMEOUT,
            recoverable: true
        }
    }
};

The WhatsappClient retry policy differences between two types of errors:

Errors generated by WhatsApp API, associated with the responseCode error field.
Errors generated by Kernel API, associated with the status error field.

Last modified June 9, 2025: feat: Add changes to use kernel whatsapp apis v2 #AURA-28376 [RTM] (e8e849e7)

Tags:

Categories: