Skip to main content

Dynamic Structure Sync

Copycord continuously watches source servers for structural changes and mirrors them to your clone server in real time.

What gets synced​

Channels​

EventAction in cloneConfigurable
Channel createdNew channel created in cloneAlways on
Channel deletedClone channel deletedDELETE_CHANNELS
Channel renamedClone channel renamedRENAME_CHANNELS
Channel repositionedClone channel repositionedREPOSITION_CHANNELS
Topic changedClone topic updatedSYNC_CHANNEL_TOPIC
NSFW toggledClone NSFW updatedSYNC_CHANNEL_NSFW
Slowmode changedClone slowmode updatedSYNC_CHANNEL_SLOWMODE
Permissions changedClone permissions updatedMIRROR_CHANNEL_PERMISSIONS

Threads​

EventAction in clone
Thread createdMatching thread created
Thread deletedClone thread removed (DELETE_THREADS)
Thread renamedClone thread renamed
Thread archived/unarchivedClone thread updated

Roles​

EventAction in cloneConfigurable
Role createdNew role created in cloneCLONE_ROLES
Role deletedClone role deletedDELETE_ROLES
Role renamedClone role renamedUPDATE_ROLES
Color changedClone role color updatedUPDATE_ROLES
Permissions changedClone permissions updatedMIRROR_ROLE_PERMISSIONS
Hoist toggledClone hoist updatedUPDATE_ROLES
Position changedClone position updatedREARRANGE_ROLES
Icon changedClone icon updatedCLONE_ROLE_ICONS

Emojis and Stickers​

EventAction in clone
Emoji addedNew emoji cloned
Emoji removedClone emoji deleted
Sticker addedNew sticker cloned
Sticker removedClone sticker deleted

Guild-level properties​

EventConfigurable
Server icon changedCLONE_GUILD_ICON
Server banner changedCLONE_GUILD_BANNER
Splash screen changedCLONE_GUILD_SPLASH
Description changedSYNC_GUILD_DESCRIPTION

How it works​

Copycord uses two methods to keep the clone in sync:

1. Real-time gateway events​

The client self-bot receives Discord gateway events for every change in the source server. These are processed immediately:

  • GUILD_CHANNEL_CREATE/DELETE/UPDATE
  • GUILD_ROLE_CREATE/DELETE/UPDATE
  • GUILD_EMOJIS_UPDATE
  • GUILD_STICKERS_UPDATE
  • GUILD_UPDATE
  • THREAD_CREATE/DELETE/UPDATE

2. Periodic full sync​

A comprehensive structure comparison runs periodically (default: every 60 minutes). This catches any changes that might have been missed during downtime or network interruptions.

Sync architecture​

Structure sync is designed to be as fast as possible while respecting Discord's API limits.

Two-phase channel sync​

Channel and category creation runs first without any artificial delays — Discord's built-in rate limit handling (via Retry-After headers) is used automatically. Webhook creation is handled separately:

  • ON_DEMAND_WEBHOOKS: true (default) — Webhooks are not created during sync at all. Instead, they are created lazily when the first message arrives for a channel. This makes initial server cloning near-instant for the structure phase.
  • ON_DEMAND_WEBHOOKS: false — Webhooks are batch-created in the background after structure sync completes, with a small delay between each to avoid hitting rate limits.

Parallel background tasks​

Roles, emojis, and stickers sync in parallel as background tasks while structure sync runs. The sync is only reported as complete once all background tasks have finished.

Cancel and restart​

If a new sitemap arrives while a sync is already running for the same clone guild, the running sync is canceled and a new one starts with the latest data. Background tasks (roles, emojis, stickers, webhooks) from the canceled sync continue running independently — they are not interrupted.

Message buffering​

Messages that arrive for channels not yet cloned are automatically queued. Once the sync creates the channel and its webhook (on-demand or batch), buffered messages are replayed in order. No messages are dropped during sync.

Emoji and sticker limits​

When cloning emojis or stickers, if the clone guild hits Discord's limit (e.g., 50 emojis for unboosted servers), the sync stops. The limit is re-evaluated on each sync cycle.

Rate limiting​

Copycord uses discord.py's native rate limit handling for all structure sync operations. When Discord returns a 429 Too Many Requests response, the library automatically waits the required Retry-After duration before retrying.