Awesome

Ballerina Discord Connector

Overview

Discord is a popular communication platform designed for creating communities and facilitating real-time messaging, voice, and video interactions over the internet.

The Ballerina Discord connector offers APIs to connect and interact with the Discord REST API v10.

Setup guide

Follow these steps to create a Discord developer account.

Step 1: Login to Discord developer page

Visit Discord developer portal by logging into your Discord account.
<img src="https://github.com/ballerina-platform/module-ballerinax-discord/blob/main/docs/setup/resources/discord-dev-page.png?raw=true" alt="Discord Dev Page" style="width: 70%;">
If you do not have a Discord account already, create a new discord account by clicking on the Register hyperlink below the Log In button when opening the Discord developer page.
<img src= "https://github.com/ballerina-platform/module-ballerinax-discord/blob/main/docs/setup/resources/create-acc.png?raw=true" alt="Create Discord Account" style="width: 70%;">
Complete the account creation process by including the relevant information in the given fields.

Step 2: Make a new Discord application

Once in the Discord developer portal is open, click on the New Application button as displayed above to start the process.
<img src="https://github.com/ballerina-platform/module-ballerinax-discord/blob/main/docs/setup/resources/make-new-app.png?raw=true" alt="Make New Application" style="width: 70%;">

Step 3: Name the Discord Application

Proceed by giving the Discord Application a name and click on the terms of service.
<img src="https://github.com/ballerina-platform/module-ballerinax-discord/blob/main/docs/setup/resources/create-app.png?raw=true" alt="Name and Create the App" style="width: 70%;">
Finally complete the naming process by clicking on the next button.

Step 4: Obtain the Client ID and Client Secret

Under the OAuth2 section found on the left-sided list, locate the Client's Information as shown on the screen. To implement the functionalities provided by Discord's API, you will need the Client ID and Client Secret.
<img src="https://github.com/ballerina-platform/module-ballerinax-discord/blob/main/docs/setup/resources/obtain-client-id.png?raw=true" alt="Obtain Client ID and Secret" style="width: 70%;">

Quickstart

To use the discord connector in your Ballerina application, modify the .bal file as follows:

Step 1: Import the module

Import the discord module.

import ballerinax/discord;

Step 2: Instantiate a new connector

Create a discord:ConnectionConfig with the obtained OAuth2.0 Client Credentials and initialize the connector with it.

Apps must receive approval from users installing them to perform actions within Discord. To enable these functions, specific scopes must be defined. These scopes are outlined in the OAuth2 Scopes documentation.

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string[] scopes = ?;

discord:Client discord = check new({
    auth: {
            clientId,
            clientSecret,
            scopes
        }
});

Step 3: Invoke the connector operation

Now, utilize the available connector operations.

Return linked third-party accounts of the user

public function main() returns error? {
    ConnectedAccountResponse[] connectedAccounts = check discord->/users/\@me/connections();
}

Step 4: Run the Ballerina application

bal run

Examples

The Discord connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

Automated Event Reminders - This use case illustrates how the Discord API can be leveraged to create a scheduled event in a Discord server and automate daily reminders about this event across all channels within the server.
Automated Role Assignment Based on Reactions - This use case illustrates the utilization of the Discord API to assign roles to members based on their interests, enabling them to gain roles by reacting to designated messages.

Build from the source

Prerequisites

Download and install Java SE Development Kit (JDK) version 17. You can download it from either of the following sources:
- Oracle JDK
- OpenJDK
Note: After installation, remember to set the JAVA_HOME environment variable to the directory where JDK was installed.
Download and install Ballerina Swan Lake.
Download and install Docker.

Note: Ensure that the Docker daemon is running before executing any tests.
Export Github Personal access token with read package permissions as follows,
```
export packageUser=<Username>
export packagePAT=<Personal access token>
```

Build options

Execute the commands below to build from the source.

To build the package:
```
./gradlew clean build
```
To run the tests:
```
./gradlew clean test
```
To build the without the tests:
```
./gradlew clean build -x test
```

To run tests against different environment:

./gradlew clean test -Pgroups=<Comma separated groups/test cases>

To debug package with a remote debugger:
```
./gradlew clean build -Pdebug=<port>
```

To debug with the Ballerina language:

./gradlew clean build -PbalJavaDebug=<port>

Publish the generated artifacts to the local Ballerina Central repository:
```
./gradlew clean build -PpublishToLocalCentral=true
```
Publish the generated artifacts to the Ballerina Central repository:
```
./gradlew clean build -PpublishToCentral=true
```