/collabland_action_express

A boilerplate for creating Collab Action in Express js

Primary LanguageTypeScript

Collab🤝Land Actions Express.js Template

Introduction 🙏

The repository serves as a Express.js template for implementing Collab.Land actions for Discord interactions. The Collab.Land actions are installed to the Collab.Land bot through the /test-flight miniapp available in the Collab.Land marketplace.

Pre-requisites 💻

Environment:

Code Editors (Optional, but we prefer it!):

Tunnel Forwarding:

Server Setup ⚙️

Starting the server:

  • Clone the repository to your machine
  • Open the folder in a code editor of your choice
  • Install dependencies: 
    npm install
  • Build the project: 
    npm run build
  • Start the server (The server starts in port 3000 by default): 
    npm start
  • If the server fails due to the port being occupied, start the server in a different port: 
    PORT=5000 npm start
  • To expose your localhost API to public domain, open a new terminal and start NGROK: 
    ngrok http <PORT>
  • Copy the .ngrok.io link shown in your terminal

Installing the Collab.Land actions:

  • The API exposes 3 types of Collab.Land actions:
    • <NGROK URL>/hello-action : Sample Discord interaction demo-ing Discord message interactions
    • <NGROK URL>/button-action : Sample Discord interaction demo-ing Discord button interactions
    • <NGROK URL>/popup-action : Sample Discord interaction demo-ing Discord modal interactions
  • Use the /test-flight install action-url: <Your action URL> command in the Collab.Land Bot to install the Collab.Land actions.

Switching on signature verification:

  • In order to verify the webhook requests coming from the Collab.Land bot, please delete the SKIP_VERIFICATION variable in your .env file and restart the server.
  • Please fetch the public key from the [Collab.Land Config], and replace your COLLABLAND_ACTION_PUBLIC_KEY variable in the .env file.

API Specifications 🛠️

  • The API exposes two routes per slash command:
    • GET /hello-action/metadata : To provide the metadata for the /hello-action command
    • POST /hello-action/interactions : To handle the Discord interactions corresponding to the /hello-action command
    • GET /button-action/metadata : To provide the metadata for the /button-action command
    • POST /button-action/interactions : To handle the Discord interactions corresponding to the /button-action command
    • GET /popup-action/metadata : To provide the metadata for the /popup-action command
    • POST /popup-action/interactions : To handle the Discord interactions corresponding to the /popup-action command
  • The slash commands provide example codes for the following Discord interactions:
    • /hello-action : It shows how to interact with a basic slash command Discord interaction, and then reply to that interaction. Along with that it shows an example of how to edit messages, delete messages or send follow-up messages using Collab.Land actions.
    • /button-action : It shows how to create buttons using Discord interactions, and then respond to the button events.
    • /popup-action : It shows how to send modals for forms using Discord interactions, and then listen for the form submissions and even read data submitted by the user.

Contributing 🫶

  • Please go through the following article [Link] to understand the deep technical details regarding building on the Collab.Land actions platform.
  • In order to change the slash commands for the actions, try editing the MiniAppManifest models mentioned in the metadata route handlers [Here 👀]
  • In order to change the logic which runs on the slash commands, try changing the handle() function mentioned in the interactions route handlers [Here 👀]
Built with ❤️ and 🤝 by Collab.Land