Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

feat(whatsapp): clearer message setup, template preview and paginated dropdowns (#15752)

Talal Jaber1434692189c4
diff --git a/packages/pieces/community/whatsapp/package.json b/packages/pieces/community/whatsapp/package.json
index 620a0f04105..df9c286165a 100644
--- a/packages/pieces/community/whatsapp/package.json
+++ b/packages/pieces/community/whatsapp/package.json
@@ -1,6 +1,6 @@
{
"name": "@activepieces/piece-whatsapp",
- "version": "0.2.7",
+ "version": "0.3.0",
"main": "./dist/src/index.js",
"types": "./dist/src/index.d.ts",
"scripts": {
diff --git a/packages/pieces/community/whatsapp/src/index.ts b/packages/pieces/community/whatsapp/src/index.ts
index af0d2c0c27a..9cfa156a59a 100644
--- a/packages/pieces/community/whatsapp/src/index.ts
+++ b/packages/pieces/community/whatsapp/src/index.ts
@@ -1,29 +1,16 @@
-import { createPiece, PieceAuth, Property } from '@activepieces/pieces-framework';
+import { createPiece, PieceCategory } from '@activepieces/pieces-framework';
import { sendMessage } from './lib/actions/send-message';
import { sendMedia } from './lib/actions/send-media';
import { sendTemplateMessageAction } from './lib/actions/send-from-template';
import { whatsappAuth } from './lib/auth';
-const markdown = `
-To Obtain a Phone Number ID and a Permanent System User Access Token, follow these steps:
-
-1. Go to https://developers.facebook.com/
-2. Make a new app, Select Other for usecase.
-3. Choose Business as the type of app.
-4. Add new Product -> WhatsApp.
-5. Navigate to WhatsApp Settings > API Setup.
-6. Copy the Business Account ID.
-7. Login to your [Meta Business Manager](https://business.facebook.com/).
-8. Click on Settings.
-9. Create a new System User with access over the app and copy the access token.
-`;
-
export const whatsapp = createPiece({
displayName: 'WhatsApp Business',
- description: 'Manage your WhatsApp business account',
+ description: 'Send text, media and template messages from your WhatsApp Business number.',
auth: whatsappAuth,
- minimumSupportedRelease: '0.30.0',
+ minimumSupportedRelease: '0.88.2',
logoUrl: 'https://cdn.activepieces.com/pieces/whatsapp.png',
+ categories: [PieceCategory.COMMUNICATION],
authors: ['LevwTech', 'kishanprmr'],
actions: [sendMessage, sendMedia, sendTemplateMessageAction],
triggers: [],
diff --git a/packages/pieces/community/whatsapp/src/lib/actions/send-from-template.ts b/packages/pieces/community/whatsapp/src/lib/actions/send-from-template.ts
index 0230aee0ac5..d7b1d8765ff 100644
--- a/packages/pieces/community/whatsapp/src/lib/actions/send-from-template.ts
+++ b/packages/pieces/community/whatsapp/src/lib/actions/send-from-template.ts
@@ -8,14 +8,15 @@ export const sendTemplateMessageAction = createAction({
name: 'send-template-message',
classification: 'WRITE',
displayName: 'Send Template Message',
- description: 'Sends a template message.',
+ description: 'Send an approved template, filling in its placeholders.',
audience: 'both',
aiMetadata: { description: 'Sends a pre-approved WhatsApp message template to a recipient, filling its header, body, and button placeholders from the supplied fields. Choose this to initiate conversations outside the 24-hour customer service window or for notifications/marketing where a registered template is required; the template must already be approved in the WhatsApp Business account. Requires the sender phone number ID, recipient phone number, and the template ID (its name and language are resolved automatically). Not idempotent — each call delivers a new message.', idempotent: false },
props: {
phone_number_id: commonProps.phone_number_id,
to: Property.ShortText({
displayName: 'To',
- description: 'Recipient phone number.',
+ description: "Recipient's phone number in international format.",
+ placeholder: '15551234567',
required: true,
}),
message_template_id: commonProps.message_template_id,
diff --git a/packages/pieces/community/whatsapp/src/lib/actions/send-media.ts b/packages/pieces/community/whatsapp/src/lib/actions/send-media.ts
index 34b6c1c83fe..a827f4ed1e3 100644
--- a/packages/pieces/community/whatsapp/src/lib/actions/send-media.ts
+++ b/packages/pieces/community/whatsapp/src/lib/actions/send-media.ts
@@ -13,20 +13,21 @@ export const sendMedia = createAction({
name: 'sendMedia',
classification: 'WRITE',
displayName: 'Send Media',
- description: 'Send a media message through WhatsApp',
+ description: 'Send an image, video, audio, document or sticker by URL.',
audience: 'both',
aiMetadata: { description: 'Sends an image, video, audio, document, or sticker to a WhatsApp recipient by referencing the media via a public URL. Choose this when the message payload is a file rather than plain text; captions are supported for media types that allow them and a filename can be set for documents. Requires the sender phone number ID, recipient phone number, media type, and a reachable media URL; subject to WhatsApp messaging-window rules. Not idempotent — each call delivers a new message.', idempotent: false },
props: {
phone_number_id: commonProps.phone_number_id,
to: Property.ShortText({
displayName: 'To',
- description: 'The recipient of the message',
+ description: "Recipient's phone number in international format.",
+ placeholder: '15551234567',
required: true,
}),
type: Property.Dropdown({
auth: whatsappAuth,
- displayName: 'Type',
- description: 'The type of media to send',
+ displayName: 'Media Type',
+ description: 'What kind of file the URL points to.',
required: true,
options: async () => {
return {
@@ -40,18 +41,20 @@ export const sendMedia = createAction({
}),
media: Property.ShortText({
displayName: 'Media URL',
- description: 'The URL of the media to send',
+ description: 'Public link WhatsApp downloads when it sends the message.',
+ placeholder: 'https://example.com/photo.jpg',
required: true,
}),
caption: Property.LongText({
displayName: 'Caption',
- description: 'A caption for the media',
+ description: 'Text shown under the media. Ignored for audio and stickers.',
required: false,
}),
filename: Property.LongText({
displayName: 'Filename',
- description: 'Filename of the document to send',
+ description: 'Documents only: the file name the recipient sees.',
required: false,
+ advanced: true,
}),
},
async run(context) {
diff --git a/packages/pieces/community/whatsapp/src/lib/actions/send-message.ts b/packages/pieces/community/whatsapp/src/lib/actions/send-message.ts
index ab8c12bb16f..b5743ad01e7 100644
--- a/packages/pieces/community/whatsapp/src/lib/actions/send-message.ts
+++ b/packages/pieces/community/whatsapp/src/lib/actions/send-message.ts
@@ -15,12 +15,13 @@ export const sendMessage = createAction({
phone_number_id: commonProps.phone_number_id,
to: Property.ShortText({
displayName: 'To',
- description: 'The recipient of the message',
+ description: "Recipient's phone number in international format.",
+ placeholder: '15551234567',
required: true,
}),
text: Property.LongText({
displayName: 'Message',
- description: 'The message to send',
+ description: 'Plain text, up to 4096 characters.',
required: true,
}),
},
diff --git a/packages/pieces/community/whatsapp/src/lib/auth.ts b/packages/pieces/community/whatsapp/src/lib/auth.ts
index a41ebd90cd5..2248f4b7d63 100644
--- a/packages/pieces/community/whatsapp/src/lib/auth.ts
+++ b/packages/pieces/community/whatsapp/src/lib/auth.ts
@@ -1,17 +1,12 @@
import { PieceAuth, Property } from '@activepieces/pieces-framework';
const markdown = `
-To Obtain a Phone Number ID and a Permanent System User Access Token, follow these steps:
+You need the WhatsApp Business Account ID and a permanent System User access token from Meta.
-1. Go to https://developers.facebook.com/
-2. Make a new app, Select Other for usecase.
-3. Choose Business as the type of app.
-4. Add new Product -> WhatsApp.
-5. Navigate to WhatsApp Settings > API Setup.
-6. Copy the Business Account ID.
-7. Login to your [Meta Business Manager](https://business.facebook.com/).
-8. Click on Settings.
-9. Create a new System User with access over the app and copy the access token.
+1. Open [Meta for Developers](https://developers.facebook.com/) and create a **Business** app (use case **Other**).
+2. Add the **WhatsApp** product to the app.
+3. Go to **WhatsApp > API Setup** and copy the **WhatsApp Business Account ID**.
+4. In [Meta Business Manager](https://business.facebook.com/) open **Settings > System Users**, add a system user with access to the app, and generate a permanent token with the **whatsapp_business_messaging** and **whatsapp_business_management** permissions.
`;
export const whatsappAuth = PieceAuth.CustomAuth({
@@ -20,12 +15,13 @@ export const whatsappAuth = PieceAuth.CustomAuth({
props: {
access_token: PieceAuth.SecretText({
displayName: 'System User Access Token',
- description: 'The system user access token of your WhatsApp business account.',
+ description: 'Permanent token of a System User with access to the app.',
required: true,
}),
businessAccountId: Property.ShortText({
displayName: 'Business Account ID',
- description: 'The business account ID of your WhatsApp business account.',
+ description: 'Found under WhatsApp > API Setup in your Meta app.',
+ placeholder: '102290129340398',
required: true,
}),
},
diff --git a/packages/pieces/community/whatsapp/src/lib/common/utils.ts b/packages/pieces/community/whatsapp/src/lib/common/utils.ts
index a4d6a0074d2..658cd26d99b 100644
--- a/packages/pieces/community/whatsapp/src/lib/common/utils.ts
+++ b/packages/pieces/community/whatsapp/src/lib/common/utils.ts
@@ -7,9 +7,9 @@ import {
import { whatsappAuth } from '../auth';
import {
Property,
- PiecePropValueSchema,
DynamicPropsValue,
DropdownOption,
+ MarkdownVariant,
} from '@activepieces/pieces-framework';
export const supportedMediaTypes = ['image', 'audio', 'document', 'sticker', 'video'];
@@ -20,14 +20,14 @@ export const mediaTypeSupportsCaption = (type: string) =>
export const commonProps = {
phone_number_id: Property.Dropdown({
auth: whatsappAuth,
- displayName: 'Phone Number ID',
- description: 'Phone number ID that will be used to send the message.',
+ displayName: 'From Phone Number',
+ description: 'The business number the message is sent from.',
refreshers: [],
required: true,
options: async ({ auth }) => {
if (!auth) {
return {
- placeholder: 'Please connect account first',
+ placeholder: 'Please connect your account first',
disabled: true,
options: [],
};
@@ -38,16 +38,16 @@ export const commonProps = {
const options: DropdownOption<string>[] = [];
let hasMore = false;
- let cursor;
+ let cursor: string | undefined;
do {
const qs: QueryParams = {
fields: 'verified_name,id,display_phone_number',
- limit: '1',
+ limit: '100',
};
if (cursor) qs['after'] = cursor;
- const response = await httpClient.sendRequest({
+ const response = await httpClient.sendRequest<PhoneNumbersPage>({
method: HttpMethod.GET,
url: `https://graph.facebook.com/v20.0/${authValue.businessAccountId}/phone_numbers`,
authentication: {
@@ -57,22 +57,32 @@ export const commonProps = {
queryParams: qs,
});
- for (const phoneNumber of response.body.data) {
+ for (const phoneNumber of response.body.data ?? []) {
options.push({
- label: `${phoneNumber.verified_name as string} : ${
- phoneNumber.display_phone_number as string
- }`,
- value: phoneNumber.id as string,
+ label: `${phoneNumber.verified_name} (${phoneNumber.display_phone_number})`,
+ value: phoneNumber.id,
});
}
- if (response.body.paging.next) {
- (hasMore = true), (cursor = response.body.paging.cursors.after);
+ const nextPage = response.body.paging?.next;
+ const nextCursor = response.body.paging?.cursors?.after;
+
+ if (nextPage && nextCursor) {
+ hasMore = true;
+ cursor = nextCursor;
} else {
hasMore = false;
}
} while (hasMore);
+ if (options.length === 0) {
+ return {
+ placeholder: 'No phone numbers found in this account',
+ disabled: false,
+ options: [],
+ };
+ }
+
return {
disabled: false,
options,
@@ -80,14 +90,15 @@ export const commonProps = {
},
}),
message_template_id: Property.Dropdown({
- displayName: 'Message Template ID',
+ displayName: 'Template',
+ description: 'Only templates approved by WhatsApp are delivered.',
refreshers: [],
required: true,
auth: whatsappAuth,
options: async ({ auth }) => {
if (!auth) {
return {
- placeholder: 'Please connect account first',
+ placeholder: 'Please connect your account first',
disabled: true,
options: [],
};
@@ -98,16 +109,16 @@ export const commonProps = {
const options: DropdownOption<string>[] = [];
let hasMore = false;
- let cursor;
+ let cursor: string | undefined;
do {
const qs: QueryParams = {
fields: 'id,name,language',
- limit: '1',
+ limit: '100',
};
if (cursor) qs['after'] = cursor;
- const response = await httpClient.sendRequest({
+ const response = await httpClient.sendRequest<TemplatesPage>({
method: HttpMethod.GET,
url: `https://graph.facebook.com/v20.0/${authValue.businessAccountId}/message_templates`,
authentication: {
@@ -117,20 +128,32 @@ export const commonProps = {
queryParams: qs,
});
- for (const template of response.body.data) {
+ for (const template of response.body.data ?? []) {
options.push({
- label: `${template.name as string} (${template.language as string})`,
- value: template.id as string,
+ label: `${template.name} (${template.language})`,
+ value: template.id,
});
}
- if (response.body.paging.next) {
- (hasMore = true), (cursor = response.body.paging.cursors.after);
+ const nextPage = response.body.paging?.next;
+ const nextCursor = response.body.paging?.cursors?.after;
+
+ if (nextPage && nextCursor) {
+ hasMore = true;
+ cursor = nextCursor;
} else {
hasMore = false;
}
} while (hasMore);
+ if (options.length === 0) {
+ return {
+ placeholder: 'No message templates found',
+ disabled: false,
+ options: [],
+ };
+ }
+
return {
disabled: false,
options,
@@ -140,17 +163,18 @@ export const commonProps = {
message_template_fields: Property.DynamicProperties({
displayName: 'Template Fields',
+ description: 'Fill in each placeholder of the selected template.',
refreshers: ['message_template_id'],
required: true,
auth: whatsappAuth,
- props: async ({ auth, message_template_id }) => {
+ props: async ({ auth, message_template_id }) => {
if (!auth) return {};
if (!message_template_id) return {};
const authValue = auth.props;
- const templateId = message_template_id as unknown as string;
+ const templateId = String(message_template_id);
- const response = await httpClient.sendRequest({
+ const response = await httpClient.sendRequest<TemplateDetails>({
url: `https://graph.facebook.com/v20.0/${templateId}`,
method: HttpMethod.GET,
authentication: {
@@ -163,13 +187,11 @@ export const commonProps = {
const headerComponentFields: DynamicPropsValue = {};
const buttonComponentFields: DynamicPropsValue = {};
- for (const component of response.body.components) {
+ for (const component of response.body.components ?? []) {
if (component.type === 'BODY') {
- // https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components#syntax
bodyComponentFields['BODY_markdown'] = Property.MarkDown({
- value: `
- **Body :**
- ${component.text}`,
+ value: `**Body**\n\n${escapeTemplatePlaceholders(component.text ?? '')}`,
+ variant: MarkdownVariant.BORDERLESS,
});
const bodyTextVariables = component.text?.match(/{{(\d+)}}/g) ?? [];
@@ -181,11 +203,9 @@ export const commonProps = {
});
}
} else if (component.type === 'HEADER' && component.format === 'TEXT') {
- // https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components#text-headers
headerComponentFields['HEADER_markdown'] = Property.MarkDown({
- value: `
- **Header :**
- ${component.text}`,
+ value: `**Header**\n\n${escapeTemplatePlaceholders(component.text ?? '')}`,
+ variant: MarkdownVariant.BORDERLESS,
});
const headerTextVariables = component.text?.match(/{{(\d+)}}/g) ?? [];
@@ -197,8 +217,7 @@ export const commonProps = {
});
}
} else if (component.type === 'BUTTONS') {
- // https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components#url-buttons
- for (const button of component.buttons) {
+ for (const button of component.buttons ?? []) {
if (button.type === 'URL') {
const buttonURLTextVariables = button.url?.match(/{{(\d+)}}/g) ?? [];
@@ -223,3 +242,45 @@ export const commonProps = {
},
}),
};
+
+function escapeTemplatePlaceholders(text: string) {
+ return text.replace(/{{(\d+)}}/g, '`{`{$1`}`}');
+}
+
+type Paging = {
+ next?: string;
+ cursors?: {
+ after?: string;
+ };
+};
+
+type PhoneNumbersPage = {
+ data?: {
+ id: string;
+ verified_name: string;
+ display_phone_number: string;
+ }[];
+ paging?: Paging;
+};
+
+type TemplatesPage = {
+ data?: {
+ id: string;
+ name: string;
+ language: string;
+ }[];
+ paging?: Paging;
+};
+
+type TemplateDetails = {
+ components?: {
+ type: string;
+ format?: string;
+ text?: string;
+ buttons?: {
+ type: string;
+ text: string;
+ url?: string;
+ }[];
+ }[];
+};