Usage for Discord¶

Note

Agoras uses agoras discord for Discord operations. See the migration guide for upgrading from agoras publish.

Discord is a communication platform designed for creating communities. It features text channels, voice channels, and rich media sharing capabilities. Agoras can publish messages, videos, images, and manage scheduled content on Discord using the official Discord.py library.

Important: Discord uses bot tokens for authentication. You must create a Discord application and bot, then invite it to your server with appropriate permissions before using these features. Share functionality is not supported by Agoras for Discord.

Required Credentials¶

Before using Agoras with Discord, you’ll need to manually extract the following credentials from your Discord Application in the Discord Developer Portal. These credentials are required for bot authentication and server access.

Bot Token (DISCORD_BOT_TOKEN): Your Discord bot’s authentication token, obtained from the Discord Developer Portal
Server Name (DISCORD_SERVER_NAME): The exact name of the Discord server where your bot is a member
Channel Name (DISCORD_CHANNEL_NAME): The exact name of the text channel where you want to post (without the # symbol)

See Discord credentials for detailed instructions on how to create a Discord application, set up a bot, invite it to your server, and obtain these credentials.

For CI/CD environments, see Discord credentials for unattended execution setup.

Available Actions¶

authorize - Set up bot authentication (required first step)
post - Send text messages with links and images (up to 4 images)
video - Upload and send video files
delete - Delete messages

Authorization¶

Added in version 2.0: Bot token “authorize first” workflow

Before performing any actions, you must authorize Agoras to access your Discord server:

agoras discord authorize \
  --bot-token "${DISCORD_BOT_TOKEN}" \
  --server-name "${DISCORD_SERVER_NAME}" \
  --channel-name "${DISCORD_CHANNEL_NAME}"

This will:

Validate your bot token and server/channel access
Store encrypted credentials in ~/.agoras/tokens/

After authorization, you can perform actions without providing credentials. Credentials are automatically loaded from storage.

For CI/CD environments, see Discord credentials for unattended execution setup.

Publish a Discord message¶

This command will send a message to a Discord channel using your bot. The message can include text, links, and up to 4 images. Links will automatically generate rich embeds with previews when possible.

New format (Agoras 2.0+):

agoras discord post \
  --text "${STATUS_TEXT}" \
  --link "${STATUS_LINK}" \
  --image-1 "${STATUS_IMAGE_URL_1}" \
  --image-2 "${STATUS_IMAGE_URL_2}" \
  --image-3 "${STATUS_IMAGE_URL_3}" \
  --image-4 "${STATUS_IMAGE_URL_4}"

Parameters:

--text: The text content of your message
--link: A URL that will be embedded as a rich preview
--image-X: URLs pointing to downloadable images (JPEG, PNG, JPG)

Note: You must provide at least one of --text, --link, or --image-1.

Deprecated since version 2.0: The agoras publish --network "discord" command is deprecated. Use agoras discord post instead.

Publish a Discord video¶

This command will upload and send a video file to a Discord channel. The video can include a title and description that will be displayed in a rich embed alongside the video file.

New format (Agoras 2.0+):

agoras discord video \
  --video-url "${DISCORD_VIDEO_URL}" \
  --video-title "${DISCORD_VIDEO_TITLE}" \
  --text "${STATUS_TEXT}"

Parameters:

--video-url: URL pointing to a downloadable video file (required)
--video-title: Title for the video (optional)
--text: Additional description text (optional)

Video requirements: - Supported formats: MP4, MOV, WebM, AVI - File size limit: 8MB for regular Discord users, 50MB for Nitro users - File must be accessible: The URL must point to a downloadable video file

Delete a Discord message¶

This command will delete an existing Discord message. The bot must have permission to delete messages and the message must be in the specified channel.

New format (Agoras 2.0+):

agoras discord delete \
  --post-id "${DISCORD_POST_ID}"

Note: Share functionality is not supported for Discord.

Post the last URL from an RSS feed into Discord¶

This command will parse an RSS feed located at --feed-url, and publish the last --max-count number of entries published in the last --post-lookback number of seconds. The post content will consist of the title and the link of the feed entry.

Please read about how the RSS feed should be structured in the RSS feed section. This ensures that the feed is correctly parsed and that the post content is properly formatted.

New format (Agoras 2.0+):

agoras utils feed-publish \
  --network discord \
  --mode last \
  --feed-url "${FEED_URL}" \
  --max-count "${MAX_COUNT}" \
  --post-lookback "${POST_LOOKBACK}"

Post a random URL from an RSS feed into Discord¶

This command will parse an RSS feed at --feed-url and publish one random entry that’s not older than --max-post-age. The post content will consist of the title and the link of the feed entry.

Please read about how the RSS feed should be structured in the RSS feed section. This ensures that the feed is correctly parsed and that the post content is properly formatted.

New format (Agoras 2.0+):

agoras utils feed-publish \
  --network discord \
  --mode random \
  --feed-url "${FEED_URL}" \
  --max-post-age "${MAX_POST_AGE}"

Google Sheets Scheduling¶

Agoras can schedule Discord messages using Google Sheets. This allows you to plan and automate message sending.

Run Scheduled Messages¶

Process scheduled messages from a Google Sheet:

agoras utils schedule-run \
  --network discord \
  --sheets-id "${GOOGLE_SHEETS_ID}" \
  --sheets-name "Discord" \
  --sheets-client-email "${GOOGLE_SHEETS_CLIENT_EMAIL}" \
  --sheets-private-key "${GOOGLE_SHEETS_PRIVATE_KEY}"

Note

You must run agoras discord authorize first before using this command.

Sheet Format¶

Your Google Sheet should have the following columns:

status_text: Message text content
status_link: URL to include in message
status_image_url_1 through status_image_url_4: Image URLs (optional)
date: Scheduled date (format: DD-MM-YYYY)
hour: Scheduled hour (format: HH, 24-hour format)
state: Post state (pending, published, error)

Example sheet row:

status_text,status_link,status_image_url_1,status_image_url_2,status_image_url_3,status_image_url_4,date,hour,state
"This is a test Discord post","https://agoras.luisalejandro.org/en/latest/","https://example.com/image1.jpg","https://example.com/image2.jpg","","","21-11-2022","17","pending"

Scheduling Logic¶

Posts with state="pending" and scheduled time in the past are processed
Posts are created at the scheduled date and hour
Sheet state is updated to published after successful posting
If posting fails, state is updated to error
Use --network discord to process only Discord posts, or omit to process all networks

Discord Features and Limitations¶

Rich Embeds:

Links automatically generate rich previews with title, description, and images
Multiple embeds are supported for multiple images
Video uploads include custom embed with title and description

File Upload Limits:

Regular users: 8MB maximum file size
Nitro users: 50MB maximum file size
Supported video formats: MP4, MOV, WebM, AVI
Supported image formats: JPEG, PNG, JPG

Bot Permissions Required:

Send Messages: To post text content
Embed Links: To create rich embeds
Attach Files: To upload videos and images
Manage Messages: To delete messages (if using delete action)

Limitations:

Share/repost functionality is not supported
Bot must be invited to the server and have access to the target channel
Message content follows Discord’s community guidelines and character limits
File URLs must be publicly accessible for download

Getting your message ID¶

From Agoras output:

When you create a Discord message with Agoras, it will print the message ID (in JSON format) in the console:

$ agoras discord post \
      --text "This is a test post"
$ {"id":"NNNNNNNNNNN"}

NNNNNNNNNNN is the message ID.

From Discord client:

Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode)
Right-click on any message
Select “Copy Message ID”
The copied value is the message ID you can use with --post-id

Server and Channel Names¶

Server Name (--server-name):

Use the exact server name as it appears in Discord
Case-sensitive
Must be a server where your bot is a member

Channel Name (--channel-name):

Use the channel name without the # symbol
Case-sensitive
Bot must have access to read and send messages in this channel

For example, if you see “#general” in Discord, use general as the channel name.