When you install an integration in your bot in Botpress Studio, you can add custom cards that run advanced JavaScript programs and triggers that listen for external events.

For this tutorial, we will add the capability for a bot to create a trackable URL that notifies the creator when it is used. You can follow the instructions below or follow along the video.

Modify the Integration Definition

First, let's add the necessary configuration to your integration definition to enable the creation of trackable links and handle the trigger events.

Step 1: Add Actions to Integration Definition

Add the following configuration schema to the actions property in your integration.definition.ts:

// integration.definition.ts
import { IntegrationDefinition, z } from '@botpress/sdk'; // make sure to add the z import

export default new IntegrationDefinition({
  // ...existing properties
  actions: {
    createTrackableLink: {
      title: 'Create Trackable Link',
      description: 'Takes a link as an input and returns a link that notifies the author when the link is clicked.',
      input: {
        schema: z.object({
          conversationId: z.string().describe('ID of the conversation'),
          originalLink: z.string().describe('URL of the link to be tracked'),
        }),
      },
      output: {
        schema: z.object({
          trackableLink: z.string().describe('URL of the trackable link'),
        })
      },
    }
  },
  // ...existing properties
});

The actions property defines the custom action createTrackableLink which takes a conversation ID and an original link as input, and returns a trackable link.

Step 2: Add Events to Integration Definition

Next, add the following configuration schema to the events property in your integration.definition.ts:

// integration.definition.ts
import { IntegrationDefinition, z } from '@botpress/sdk'; // make sure to add the z import

export default new IntegrationDefinition({
  // ...existing properties
  events: {
    clickedLink: {
      schema: z.object({
        conversationId: z.string().describe("ID of the conversation to notify the user"),
        originalLink: z.string(),
      })
    },
  },
  // ...existing properties
});

The events property defines the clickedLink event that is triggered when the trackable link is clicked.

Add the Integration Logic

Now that we've defined the actions and triggers, let's implement the logic that creates the trackable link and handles the click event.

Step 3: Implement Action Logic

Update your src/index.ts to handle the creation of trackable links:

// src/index.ts
import { Integration, z } from '@botpress/sdk'; // import the z import

export default new Integration({
    // ...existing properties
  actions: {
    createTrackableLink: async ({ input, ctx }) => {
      const { conversationId, originalLink } = input;
      const { webhookId } = ctx;
      const encodedInformation = btoa(JSON.stringify({ conversationId, originalLink }));
      const trackableLink = `https://webhook.botpress.cloud/${webhookId}?rd=${encodedInformation}`;

      return { trackableLink };
    },
  },
  // ...existing properties
});

This allows a user to add a "createTrackableLink" card in Botpress Studio, which takes a conversation ID and an original link as input. The output is saved to a variable, which contains the trackable link.
We are using the btoa function to obfuscate the conversation ID and original link in the URL. We'll use in the next step to decode this information.

Step 4: Implement Event Handler Logic

Next, add the handler code to your src/index.ts to handle the redirect:

// src/index.ts
import { Integration } from '@botpress/sdk';

export default new Integration({
  // ...existing properties
  handler: async ({ req, client }) => {
    // add this code to the handler function
    if (req.path === "" && req.method === "GET" && req.query.startsWith("rd=")) {
      const url = new URL(`https://example.com/?${req.query}`);
      const rd = url.searchParams.get("rd") ?? "";
      const decodedInformation = JSON.parse(atob(rd));
      const conversationId = decodedInformation.conversationId;
      const originalLink = decodedInformation.originalLink;

      // this reports back to the url creator that the link was clicked
      await client.createEvent({
        type: "clickedLink",
        payload: { conversationId, originalLink },
      });

      // this redirects the url-clicker to the original link
      return {
        status: 307,
        headers: { "content-type": "text/html" },
        body: `<http><head><meta http-equiv="Refresh" content="0; URL=${originalLink}" /></head></http>`,
      };
    }
    // ...existing logic
  },
  // ...existing properties
});

The handler function allows you to catch any http requests sent to the webhook URL and its sub paths. We use the if statement to catch relevant requests and allow other requests to be handled by other functions.
The createTrackableLink action encodes the conversation ID and original link into a base64 string and creates a trackable link. The handler function decodes this information when the link is clicked, triggers the clickedLink event, and redirects the user to the original link.

Create and Test the Action in Botpress Studio

Now, let's create and test the action in Botpress Studio.

Step 5: Create the Action in Botpress Studio

Create an Action:
- In Botpress Studio, create an action card.
- Provide the URL as a string in the input and the current conversation ID like this: "{{event.conversationId}}".
- Save the output to a variable called output.
- Create a text card with the text: "This is the shareable URL: {{workflow.output.trackableLink}}".
Create a Trigger:
- Right-click the workflow, click "Trigger", then select the clickedLink event.
- In the created node, click it, then "Advanced settings", and put {{event.payload.conversationId}} in the conversation ID field.
- Create a text card connected to the trigger node, and add "A user has clicked your tracked link to {{event.payload.originalLink}}".

Step 6: Test the Action and Trigger

To test the action and trigger, you must use a published bot outside the emulator:

Publish the Bot:
- Ensure your bot is published and accessible.
Test the Trackable Link:
- Interact with the bot to generate the trackable link.
- Use the generated link.
- Verify that the bot notifies the creator when the link is clicked.

Congratulations! You've successfully added and tested custom actions and triggers in Botpress Studio. Now, your bot can create trackable links and notify users when those links are clicked.