Skip to main content

​
Overview

Templates allow you to save and reuse message configurations. Templates support all message features including embeds and can be shared with collaborators.

​
List All Templates

GET /templates Retrieve all templates owned by or shared with the authenticated user.

​
Query Parameters

​
category
string
Filter by category
​
search
string
Search templates by name or description
​
ownership
string
Filter by ownership: owned, shared, or all

​
Response

​
templates
object
​
data
array
Array of template objects
​
id
integer
Template ID
​
name
string
Template name
​
description
string
Template description
​
category
string
Template category
​
content
object
Message content (same structure as message send)
​
is_owner
boolean
Whether current user owns this template
​
permission_level
string
User’s permission: owner, edit, or view
curl -X GET https://your-domain.com/templates \
  -H "Accept: application/json" \
  -H "X-CSRF-TOKEN: your-csrf-token" \
  --cookie "session-cookie"
Response
{
  "templates": {
    "data": [
      {
        "id": 1,
        "name": "Production Alert",
        "description": "Critical production alerts template",
        "category": "alerts",
        "content": {
          "content": "🚨 Alert from {user.name}",
          "embeds": [
            {
              "title": "Critical Alert",
              "description": "Something needs attention!",
              "color": 15158332
            }
          ]
        },
        "is_owner": true,
        "permission_level": "owner",
        "webhook_id": null,
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      }
    ]
  }
}

​
Create Template

POST /templates Create a new message template.

​
Request Body

​
name
string
required
Template name (max 255 characters)
​
description
string
Template description (max 1000 characters)
​
category
string
required
Template category (max 50 characters)
​
content
object
required
Message content object
​
content.content
string
Plain text content (max 2000 characters)
​
content.embeds
array
Array of embed objects (max 10)
​
webhook_id
integer
Optional webhook ID to associate with template
​
is_shared
boolean
default:"false"
Whether template is shared
{
  "name": "Server Status",
  "description": "Weekly server status report",
  "category": "reports",
  "content": {
    "content": "Weekly Status Report - {date}",
    "embeds": [
      {
        "title": "Server Statistics",
        "description": "Performance metrics for the week",
        "color": 3447003,
        "fields": [
          {
            "name": "Uptime",
            "value": "99.9%",
            "inline": true
          },
          {
            "name": "Requests",
            "value": "1.2M",
            "inline": true
          }
        ],
        "footer": {
          "text": "Report generated by {user.name}"
        },
        "timestamp": true
      }
    ]
  }
}

​
Response

Returns 302 redirect to /templates with success message.

​
Get Template Details

GET /templates/{id} Retrieve detailed information about a specific template.

​
Path Parameters

​
id
integer
required
Template ID

​
Response

{
  "template": {
    "id": 1,
    "name": "Production Alert",
    "description": "Critical production alerts",
    "category": "alerts",
    "content": {
      "content": "🚨 Alert from {user.name}",
      "embeds": [...]
    },
    "is_owner": true,
    "permission_level": "owner",
    "webhook_id": 5,
    "webhook": {
      "id": 5,
      "name": "Production Webhook"
    },
    "user": {
      "id": 1,
      "name": "John Doe"
    },
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

​
Update Template

PUT/PATCH /templates/{id} Update an existing template. Requires edit or owner permission.

​
Path Parameters

​
id
integer
required
Template ID

​
Request Body

Same structure as Create Template. 
{
  "name": "Updated Template Name",
  "description": "Updated description",
  "category": "updates",
  "content": {
    "content": "Updated content",
    "embeds": []
  }
}

​
Response

Returns 302 redirect to /templates with success message.

​
Delete Template

DELETE /templates/{id} Permanently delete a template. Only the owner can delete a template.

​
Path Parameters

​
id
integer
required
Template ID

​
Response

Returns 302 redirect to /templates with success message.

​
Duplicate Template

POST /templates/{id}/duplicate Create a copy of an existing template. The copy will be owned by the current user.

​
Path Parameters

​
id
integer
required
Template ID to duplicate
curl -X POST https://your-domain.com/templates/1/duplicate \
  -H "X-CSRF-TOKEN: your-csrf-token" \
  --cookie "session-cookie"

​
Response

Returns 302 redirect to edit page of the new template with success message. The duplicated template:
  • Has ” (Copy)” appended to the name
  • Is owned by the current user
  • Is not shared by default
  • Does not copy webhook associations

​
Template Categories

Common template categories:
  • alerts - Alert and notification templates
  • reports - Report and summary templates
  • announcements - Announcement templates
  • updates - Status update templates
  • welcome - Welcome message templates
  • reminders - Reminder templates
  • custom - Custom category
Categories are free-form strings. You can create any category name (max 50 characters).

​
Using Templates

Templates can be used when sending messages:
  1. Load the template content
  2. Variables are automatically replaced
  3. Send through any webhook

​
Example Flow

// 1. Get template
const response = await fetch('/templates/1');
const { template } = await response.json();

// 2. Use template content in message
fetch('/webhooks/5/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-TOKEN': csrfToken
  },
  credentials: 'include',
  body: JSON.stringify(template.content)
})

​
Template Collaborators

Templates can be shared with other users. See the Collaborators section for managing template access.

​
Collaborator Endpoints

  • GET /templates/{template}/collaborators - List collaborators
  • POST /templates/{template}/collaborators - Add collaborator
  • PUT /templates/{template}/collaborators/{user} - Update permission
  • DELETE /templates/{template}/collaborators/{user} - Remove collaborator
  • POST /templates/{template}/leave - Leave as collaborator

​
Permission Levels

LevelPermissions
viewView template content only
editView and modify template
ownerFull control (creator only)

​
Content Validation

Template content follows the same validation rules as messages:
  • Plain text: max 2000 characters
  • Embeds: max 10 per message
  • Embed title: max 256 characters
  • Embed description: max 4096 characters
  • Embed fields: max 25 per embed
  • Field name: max 256 characters
  • Field value: max 1024 characters
All embed fields are optional, but at least one field must be present for the embed to be valid. Common fields:
  • title
  • description
  • color (decimal integer)
  • url
  • timestamp
  • footer (text, icon_url)
  • image (url)
  • thumbnail (url)
  • author (name, url, icon_url)
  • fields (array)
Templates fully support variable replacement:Variables are replaced when the message is sent, not when the template is saved.

​
Authorization

OperationPermission Required
ListAny (shows owned + shared)
Viewview, edit, or owner
CreateAuthenticated user
Updateedit or owner
Deleteowner only
Duplicateview, edit, or owner

​
Example Templates

{
  "name": "Simple Alert",
  "category": "alerts",
  "content": {
    "content": "⚠️ Alert: Something needs attention!"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us