discord-join-requests

Unofficial Node.js library for automating Discord server join requests (Apply to Join) via self-bot.

Warning

This library uses Discord's private API and a user token (self-bot). Use at your own risk — account suspension may occur.

日本語版はこちら

Installation

npm install discord-join-requests

Quick Start

import { JoinRequestsClient } from 'discord-join-requests';

const client = new JoinRequestsClient({ token: 'YOUR_USER_TOKEN' });

client.on('ready', () => {
  console.log('Connected to Discord Gateway');
});

client.on('joinRequest', async ({ guild_id, request }) => {
  console.log(`New request from user ${request.user_id}`);
  console.log('Answers:', request.form_responses);

  // Approve
  await client.approve(guild_id, request.user_id);

  // Or reject with an optional reason (max 160 chars)
  // await client.reject(guild_id, request.user_id, 'Does not meet requirements.');
});

client.on('error', (err) => console.error(err));

client.connect();

CommonJS:

const { JoinRequestsClient } = require('discord-join-requests');

API

new JoinRequestsClient(options)

Option	Type	Description
token	string	Discord user token (not a bot token)

---

Events

client.on('ready', () => void)

Fired when the WebSocket connection to the Gateway is established and identified.

client.on('joinRequest', (payload) => void)

Fired when a user submits a join request (GUILD_JOIN_REQUEST_CREATE).

payload

Field	Type	Description
guild_id	string	Guild (server) ID
status	"SUBMITTED"	Always SUBMITTED for new requests
request	JoinRequest	Full request object (see below)

client.on('disconnect', (code, reason) => void)

Fired when the WebSocket disconnects.

client.on('error', (error) => void)

Fired on WebSocket or connection errors.

---

Methods

client.connect()

Connect to the Discord Gateway and start listening for events.

client.destroy()

Disconnect from the Gateway and clean up all resources.

client.approve(guildId, userId)

Approve a user's join request.

await client.approve('GUILD_ID', 'USER_ID');

client.reject(guildId, userId, reason?)

Reject a user's join request. reason is optional and must be ≤ 160 characters.

await client.reject('GUILD_ID', 'USER_ID', 'Does not meet requirements.');

client.getJoinRequests(guildId, options?)

Fetch a list of join requests for a guild.

const { guild_join_requests } = await client.getJoinRequests('GUILD_ID', {
  status: 'SUBMITTED', // 'SUBMITTED' | 'APPROVED' | 'REJECTED'
  limit: 100,          // 1–100, default 100
  before: 'SNOWFLAKE', // pagination
  after: 'SNOWFLAKE',  // pagination
});

client.getMemberVerification(guildId)

Fetch the join-request form questions for a guild.

const form = await client.getMemberVerification('GUILD_ID');
console.log(form.form_fields);

---

Types

JoinRequest

Field	Type	Description
id	string	Request ID
user_id	string	Applicant's user ID
guild_id	string	Guild ID
created_at	string	ISO 8601 timestamp
status	JoinRequestStatus	SUBMITTED / APPROVED / REJECTED
rejection_reason	string?	Rejection reason if rejected
form_responses	FormResponse[]	Applicant's answers to the form
actioned_by_user	unknown?	Who approved/rejected
actioned_at	string?	When actioned

FormResponse

Field	Type	Description
field_type	FormFieldType	TERMS / TEXT_INPUT / PARAGRAPH / MULTIPLE_CHOICE
label	string	Question text
response	string?	Text answer
values	string[]?	Selected choices (for MULTIPLE_CHOICE)
required	boolean	Whether the field was required

MemberVerification

Field	Type	Description
version	string	Form version timestamp
form_fields	FormField[]	Array of question definitions
description	string?	Server description shown on the form

FormField

Field	Type	Description
field_type	FormFieldType	Question type
label	string	Question title
choices	string[]?	Available choices (for MULTIPLE_CHOICE)
required	boolean	Whether the field is required
description	string?	Question description
placeholder	string?	Placeholder text

---

Error Handling

try {
  await client.approve(guildId, userId);
} catch (err) {
  // err.message describes the cause:
  // "401 Unauthorized: Invalid or missing token."
  // "403 Forbidden: Missing KICK_MEMBERS permission in this guild."
  // "429 Too Many Requests: Rate limited. Retry after 1s."
  // "Unknown Guild Member Verification Form: join requests are not enabled on this server."
}

Code	Meaning
401	Invalid or missing user token
403	Missing KICK_MEMBERS permission in the guild
429	Rate limited
10068	Join requests not enabled on this server

License

MIT