Skip to main content
The welcome API is used by the web dashboard to preview how welcome messages will render with real or mock member data before saving them. Base path: /api/v1/guilds/:id/welcome Authentication: API key or JWT Bearer token required.

​
POST /guilds/:id/welcome/preview

Renders a welcome message template with mock or provided member data. Useful for previewing how a message will look in the dashboard before saving. All body fields are optional. The template resolution order is:
  1. Explicit template string in the request body
  2. variants array (picks one randomly)
  3. Per-channel config for channelId
  4. Global welcome config

​
Path parameters

​
id
string
required
The Discord guild ID.

​
Request body

​
template
string
Template string to preview directly (overrides guild config).
​
variants
array
Array of template strings to pick from randomly (overrides guild config).
​
channelId
string
Channel ID to resolve per-channel welcome config.
​
member
object
Mock member data for template rendering.
​
guild
object
Mock guild data for template rendering.

​
Response

​
rendered
string
The final rendered message with all template variables substituted.
​
template
string
The template string that was used for rendering.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "Welcome to {server}, {user}! You are member #{memberCount}.",
    "member": { "id": "111222333", "username": "alice" },
    "guild": { "name": "Volvox", "memberCount": 500 }
  }' \
  "https://volvox.bot/api/v1/guilds/987654321/welcome/preview"

{
  "rendered": "Welcome to Volvox, <@111222333>! You are member #500.",
  "template": "Welcome to {server}, {user}! You are member #{memberCount}."
}

​
GET /guilds/:id/welcome/variables

Returns the list of supported template variables and their descriptions. Useful for dashboard autocomplete and tooltip display.

​
Path parameters

​
id
string
required
The Discord guild ID.

​
Response

​
variables
array
List of supported template variable objects.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/guilds/987654321/welcome/variables"

{
  "variables": [
    { "variable": "{user}", "description": "Discord mention of the new member (e.g. <@123>)" },
    { "variable": "{username}", "description": "Plain username of the new member" },
    { "variable": "{guild}", "description": "Name of the server (alias for {server})" },
    { "variable": "{server}", "description": "Name of the server (alias for {guild})" },
    { "variable": "{count}", "description": "Current member count (alias for {memberCount})" },
    { "variable": "{memberCount}", "description": "Current member count (alias for {count})" }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us