feat: WhatsApp Business Cloud Node - new operation sendAndWait (#12941)

Co-authored-by: Tomi Turtiainen <[email protected]>

Author: michael-radency

packages/core/src/execution-engine/__tests__/workflow-execute.test.ts

@@ -31,6 +31,7 @@ import type {
 	IWorkflowExecuteAdditionalData,
 	WorkflowTestData,
 	RelatedExecution,
+	IExecuteFunctions,
 } from 'n8n-workflow';
 import {
 	ApplicationError,
@@ -1462,4 +1463,90 @@ describe('WorkflowExecute', () => {
 			expect(runExecutionData.executionData?.nodeExecutionStack).toContain(executionData);
 		});
 	});
+
+	describe('customOperations', () => {
+		const nodeTypes = mock<INodeTypes>();
+		const testNode = mock<INode>();
+
+		const workflow = new Workflow({
+			nodeTypes,
+			nodes: [testNode],
+			connections: {},
+			active: false,
+		});
+
+		const executionData = mock<IExecuteData>({
+			node: { parameters: { resource: 'test', operation: 'test' } },
+			data: { main: [[{ json: {} }]] },
+		});
+		const runExecutionData = mock<IRunExecutionData>();
+		const additionalData = mock<IWorkflowExecuteAdditionalData>();
+		const workflowExecute = new WorkflowExecute(additionalData, 'manual');
+
+		test('should execute customOperations', async () => {
+			const nodeType = mock<INodeType>({
+				description: {
+					properties: [],
+				},
+				execute: undefined,
+				customOperations: {
+					test: {
+						async test(this: IExecuteFunctions) {
+							return [[{ json: { customOperationsRun: true } }]];
+						},
+					},
+				},
+			});
+
+			nodeTypes.getByNameAndVersion.mockReturnValue(nodeType);
+
+			const runPromise = workflowExecute.runNode(
+				workflow,
+				executionData,
+				runExecutionData,
+				0,
+				additionalData,
+				'manual',
+			);
+
+			const result = await runPromise;
+
+			expect(result).toEqual({ data: [[{ json: { customOperationsRun: true } }]], hints: [] });
+		});
+
+		test('should throw error if customOperation and execute both defined', async () => {
+			const nodeType = mock<INodeType>({
+				description: {
+					properties: [],
+				},
+				async execute(this: IExecuteFunctions) {
+					return [];
+				},
+				customOperations: {
+					test: {
+						async test(this: IExecuteFunctions) {
+							return [];
+						},
+					},
+				},
+			});
+
+			nodeTypes.getByNameAndVersion.mockReturnValue(nodeType);
+
+			try {
+				await workflowExecute.runNode(
+					workflow,
+					executionData,
+					runExecutionData,
+					0,
+					additionalData,
+					'manual',
+				);
+			} catch (error) {
+				expect(error.message).toBe(
+					'Node type cannot have both customOperations and execute defined',
+				);
+			}
+		});
+	});
 });

packages/core/src/execution-engine/workflow-execute.ts

@@ -40,6 +40,7 @@ import type {
 	IRunNodeResponse,
 	IWorkflowIssues,
 	INodeIssues,
+	INodeType,
 } from 'n8n-workflow';
 import {
 	LoggerProxy as Logger,
@@ -49,6 +50,7 @@ import {
 	sleep,
 	ExecutionCancelledError,
 	Node,
+	UnexpectedError,
 } from 'n8n-workflow';
 import PCancelable from 'p-cancelable';
 
@@ -971,6 +973,26 @@ export class WorkflowExecute {
 		return workflowIssues;
 	}
 
+	private getCustomOperation(node: INode, type: INodeType) {
+		if (!type.customOperations) return undefined;
+
+		if (type.execute) {
+			throw new UnexpectedError('Node type cannot have both customOperations and execute defined');
+		}
+
+		if (!node.parameters) return undefined;
+
+		const { customOperations } = type;
+		const { resource, operation } = node.parameters;
+
+		if (typeof resource !== 'string' || typeof operation !== 'string') return undefined;
+		if (!customOperations[resource] || !customOperations[resource][operation]) return undefined;
+
+		const customOperation = customOperations[resource][operation];
+
+		return customOperation;
+	}
+
 	/** Executes the given node */
 	// eslint-disable-next-line complexity
 	async runNode(
@@ -1000,8 +1022,16 @@ export class WorkflowExecute {
 
 		const nodeType = workflow.nodeTypes.getByNameAndVersion(node.type, node.typeVersion);
 
+		const isDeclarativeNode = nodeType.description.requestDefaults !== undefined;
+
+		const customOperation = this.getCustomOperation(node, nodeType);
+
 		let connectionInputData: INodeExecutionData[] = [];
-		if (nodeType.execute || (!nodeType.poll && !nodeType.trigger && !nodeType.webhook)) {
+		if (
+			nodeType.execute ||
+			customOperation ||
+			(!nodeType.poll && !nodeType.trigger && !nodeType.webhook)
+		) {
 			// Only stop if first input is empty for execute runs. For all others run anyways
 			// because then it is a trigger node. As they only pass data through and so the input-data
 			// becomes output-data it has to be possible.
@@ -1060,7 +1090,7 @@ export class WorkflowExecute {
 			inputData = newInputData;
 		}
 
-		if (nodeType.execute) {
+		if (nodeType.execute || customOperation) {
 			const closeFunctions: CloseFunction[] = [];
 			const context = new ExecuteContext(
 				workflow,
@@ -1076,10 +1106,16 @@ export class WorkflowExecute {
 				abortSignal,
 			);
 
-			const data =
-				nodeType instanceof Node
-					? await nodeType.execute(context)
-					: await nodeType.execute.call(context);
+			let data;
+
+			if (customOperation) {
+				data = await customOperation.call(context);
+			} else if (nodeType.execute) {
+				data =
+					nodeType instanceof Node
+						? await nodeType.execute(context)
+						: await nodeType.execute.call(context);
+			}
 
 			const closeFunctionsResults = await Promise.allSettled(
 				closeFunctions.map(async (fn) => await fn()),
@@ -1152,8 +1188,10 @@ export class WorkflowExecute {
 			}
 			// For trigger nodes in any mode except "manual" do we simply pass the data through
 			return { data: inputData.main as INodeExecutionData[][] };
-		} else if (nodeType.webhook) {
-			// For webhook nodes always simply pass the data through
+		} else if (nodeType.webhook && !isDeclarativeNode) {
+			// Check if the node have requestDefaults(Declarative Node),
+			// else for webhook nodes always simply pass the data through
+			// as webhook method would be called by WebhookService
 			return { data: inputData.main as INodeExecutionData[][] };
 		} else {
 			// NOTE: This block is only called by nodes tests.

packages/nodes-base/nodes/WhatsApp/GenericFunctions.ts

@@ -14,6 +14,8 @@ import type {
 	WhatsAppAppWebhookSubscriptionsResponse,
 	WhatsAppAppWebhookSubscription,
 } from './types';
+import type { SendAndWaitConfig } from '../../utils/sendAndWait/utils';
+export const WHATSAPP_BASE_URL = 'https://graph.facebook.com/v13.0/';
 
 async function appAccessTokenRead(
 	this: IHookFunctions | IExecuteFunctions | ILoadOptionsFunctions | IWebhookFunctions,
@@ -102,3 +104,27 @@ export async function appWebhookSubscriptionDelete(
 		payload: { object },
 	});
 }
+
+export const createMessage = (
+	sendAndWaitConfig: SendAndWaitConfig,
+	phoneNumberId: string,
+	recipientPhoneNumber: string,
+): IHttpRequestOptions => {
+	const buttons = sendAndWaitConfig.options.map((option) => {
+		return `*${option.label}:*\n_${sendAndWaitConfig.url}?approved=${option.value}_\n\n`;
+	});
+
+	return {
+		baseURL: WHATSAPP_BASE_URL,
+		method: 'POST',
+		url: `${phoneNumberId}/messages`,
+		body: {
+			messaging_product: 'whatsapp',
+			text: {
+				body: `${sendAndWaitConfig.message}\n\n${buttons.join('')}`,
+			},
+			type: 'text',
+			to: recipientPhoneNumber,
+		},
+	};
+};

packages/nodes-base/nodes/WhatsApp/MessageFunctions.ts

@@ -169,12 +169,13 @@ export async function componentsRequest(
 	return requestOptions;
 }
 
+export const sanitizePhoneNumber = (phoneNumber: string) => phoneNumber.replace(/[\-\(\)\+]/g, '');
+
 export async function cleanPhoneNumber(
 	this: IExecuteSingleFunctions,
 	requestOptions: IHttpRequestOptions,
 ): Promise<IHttpRequestOptions> {
-	let phoneNumber = this.getNodeParameter('recipientPhoneNumber') as string;
-	phoneNumber = phoneNumber.replace(/[\-\(\)\+]/g, '');
+	const phoneNumber = sanitizePhoneNumber(this.getNodeParameter('recipientPhoneNumber') as string);
 
 	if (!requestOptions.body) {
 		requestOptions.body = {};

packages/nodes-base/nodes/WhatsApp/MessagesDescription.ts

@@ -1,5 +1,5 @@
 import countryCodes from 'currency-codes';
-import type { INodeProperties } from 'n8n-workflow';
+import { SEND_AND_WAIT_OPERATION, type INodeProperties } from 'n8n-workflow';
 
 import {
 	cleanPhoneNumber,
@@ -32,6 +32,11 @@ export const messageFields: INodeProperties[] = [
 				value: 'send',
 				action: 'Send message',
 			},
+			{
+				name: 'Send and Wait for Response',
+				value: SEND_AND_WAIT_OPERATION,
+				action: 'Send message and wait for response',
+			},
 			{
 				name: 'Send Template',
 				value: 'sendTemplate',

packages/nodes-base/nodes/WhatsApp/WhatsApp.node.json

@@ -2,7 +2,10 @@
 	"node": "n8n-nodes-base.whatsApp",
 	"nodeVersion": "1.0",
 	"codexVersion": "1.0",
-	"categories": ["Communication"],
+	"categories": ["Communication", "HITL"],
+	"subcategories": {
+		"HITL": ["Human in the Loop"]
+	},
 	"resources": {
 		"credentialDocumentation": [
 			{

packages/nodes-base/nodes/WhatsApp/WhatsApp.node.ts

@@ -1,8 +1,19 @@
-import type { INodeType, INodeTypeDescription } from 'n8n-workflow';
-import { NodeConnectionType } from 'n8n-workflow';
+import type { IExecuteFunctions, INodeType, INodeTypeDescription } from 'n8n-workflow';
+import { NodeConnectionType, NodeOperationError, SEND_AND_WAIT_OPERATION } from 'n8n-workflow';
 
+import { createMessage, WHATSAPP_BASE_URL } from './GenericFunctions';
 import { mediaFields, mediaTypeFields } from './MediaDescription';
+import { sanitizePhoneNumber } from './MessageFunctions';
 import { messageFields, messageTypeFields } from './MessagesDescription';
+import { configureWaitTillDate } from '../../utils/sendAndWait/configureWaitTillDate.util';
+import { sendAndWaitWebhooksDescription } from '../../utils/sendAndWait/descriptions';
+import {
+	getSendAndWaitConfig,
+	getSendAndWaitProperties,
+	sendAndWaitWebhook,
+} from '../../utils/sendAndWait/utils';
+
+const WHATSAPP_CREDENTIALS_TYPE = 'whatsAppApi';
 
 export class WhatsApp implements INodeType {
 	description: INodeTypeDescription = {
@@ -19,14 +30,15 @@ export class WhatsApp implements INodeType {
 		usableAsTool: true,
 		inputs: [NodeConnectionType.Main],
 		outputs: [NodeConnectionType.Main],
+		webhooks: sendAndWaitWebhooksDescription,
 		credentials: [
 			{
-				name: 'whatsAppApi',
+				name: WHATSAPP_CREDENTIALS_TYPE,
 				required: true,
 			},
 		],
 		requestDefaults: {
-			baseURL: 'https://graph.facebook.com/v13.0/',
+			baseURL: WHATSAPP_BASE_URL,
 		},
 		properties: [
 			{
@@ -50,6 +62,42 @@ export class WhatsApp implements INodeType {
 			...mediaFields,
 			...messageTypeFields,
 			...mediaTypeFields,
+			...getSendAndWaitProperties([], 'message', undefined, {
+				noButtonStyle: true,
+				defaultApproveLabel: '✓ Approve',
+				defaultDisapproveLabel: '✗ Decline',
+			}).filter((p) => p.name !== 'subject'),
 		],
 	};
+
+	webhook = sendAndWaitWebhook;
+
+	customOperations = {
+		message: {
+			async [SEND_AND_WAIT_OPERATION](this: IExecuteFunctions) {
+				try {
+					const phoneNumberId = this.getNodeParameter('phoneNumberId', 0) as string;
+
+					const recipientPhoneNumber = sanitizePhoneNumber(
+						this.getNodeParameter('recipientPhoneNumber', 0) as string,
+					);
+
+					const config = getSendAndWaitConfig(this);
+
+					await this.helpers.httpRequestWithAuthentication.call(
+						this,
+						WHATSAPP_CREDENTIALS_TYPE,
+						createMessage(config, phoneNumberId, recipientPhoneNumber),
+					);
+
+					const waitTill = configureWaitTillDate(this);
+
+					await this.putExecutionToWait(waitTill);
+					return [this.getInputData()];
+				} catch (error) {
+					throw new NodeOperationError(this.getNode(), error);
+				}
+			},
+		},
+	};
 }