feat(whatsapp): add referral metadata to tags (botpress#14891)

Author: davidvitora

integrations/whatsapp/integration.definition.ts

@@ -93,7 +93,7 @@ const defaultBotPhoneNumberId = {
 }
 
 export const INTEGRATION_NAME = 'whatsapp'
-export const INTEGRATION_VERSION = '4.6.0'
+export const INTEGRATION_VERSION = '4.7.0'
 export default new IntegrationDefinition({
   name: INTEGRATION_NAME,
   version: INTEGRATION_VERSION,
@@ -266,6 +266,14 @@ export default new IntegrationDefinition({
             title: 'Reply To',
             description: 'The ID of the message that this message is a reply to',
           },
+          referralSourceUrl: {
+            title: 'Referral Source URL',
+            description: 'The URL of the ad or content that led to the conversation',
+          },
+          referralSourceId: {
+            title: 'Referral Source ID',
+            description: 'The ID of the ad or content that led to the conversation',
+          },
         },
       },
       conversation: {

integrations/whatsapp/src/auth.ts

@@ -13,7 +13,7 @@ const getWabaIdsFromTokenResponseSchema = z
       granular_scopes: z.array(
         z.object({
           scope: z.string(),
-          target_ids: z.array(z.string()),
+          target_ids: z.array(z.string()).optional(),
         })
       ),
     }),

integrations/whatsapp/src/misc/types.ts

@@ -21,6 +21,13 @@ const WhatsAppBaseMessageSchema = z.object({
       id: z.string().optional(),
     })
     .optional(),
+  // there are other fields in the referral object, but we don't need them
+  referral: z
+    .object({
+      source_url: z.string().optional(),
+      source_id: z.string().optional(),
+    })
+    .optional(),
   errors: z
     .array(
       z.object({

integrations/whatsapp/src/webhook/handlers/messages.ts

@@ -89,7 +89,11 @@ async function _handleIncomingMessage(
   }: ValueOf<IncomingMessages> & { incomingMessageType?: string; replyTo?: string }) => {
     logger.forBot().debug(`Received ${incomingMessageType ?? type} message from WhatsApp:`, payload)
     return client.getOrCreateMessage({
-      tags: { id: message.id, replyTo },
+      tags: {
+        id: message.id,
+        replyTo,
+        ..._processReferralTags(message, logger),
+      },
       type,
       payload,
       userId: user.id,
@@ -245,3 +249,34 @@ function _getMediaExpiry(ctx: bp.Context) {
   const expiresAt = new Date(Date.now() + expiryDelayHours * 60 * 60 * 1000)
   return expiresAt.toISOString()
 }
+
+function _processReferralTags(message: WhatsAppMessage, logger: bp.Logger): Record<string, string> {
+  const { referral } = message
+  if (!referral) {
+    return {}
+  }
+
+  const tags: Record<string, string> = {}
+
+  if (referral.source_url) {
+    const originalUrl = referral.source_url
+    // Urls can go up to 2048 characters, but we limit to 500 to avoid tags limit error
+    const processedUrl = originalUrl.slice(0, 500)
+
+    if (originalUrl !== processedUrl) {
+      logger
+        .forBot()
+        .warn(
+          `For whatsapp message "${message.id}", referral source URL was truncated from ${originalUrl.length} to 500 characters. Original: ${originalUrl}, Sliced: ${processedUrl}`
+        )
+    }
+
+    tags.referralSourceUrl = processedUrl
+  }
+
+  if (referral.source_id) {
+    tags.referralSourceId = referral.source_id
+  }
+
+  return tags
+}