Skip to main content
Templates are the messages your team writes calmly in advance so nobody is drafting customer-facing prose during an incident. Each template belongs to a type, carries separate content for each stage of an incident, and uses Liquid variables so the incident’s own details fill themselves in. Set these up in order: types, then stages, then templates.

​
Types

A communication type is a category of message with a distinct audience and purpose — customer updates, internal leadership updates, support-team briefings. Types are the organizing principle for the whole module. Both recipient groups and templates belong to a type, which is what connects an audience to the messages it can receive.
​
string
required
What this category of communication is. Name it for the audience and purpose together — “Customer status updates” rather than “External”.
​
color
required
A visual marker so responders can tell types apart at a glance when choosing a template mid-incident.
A type that has groups or templates attached cannot be deleted. Detach or remove them first — which is deliberate, since deleting a type in use would orphan both an audience and the messages meant for it.
Resist creating a type per team. Types multiply the templates you must maintain, because each type needs its own template with content for every stage. Most organizations need three or four.

​
Stages

A stage is a phase of an incident that you communicate at. Stages are defined once for the organization and shared across every type, so “Resolved” means the same thing everywhere. Typical stages map to how an incident actually unfolds: Stages are your own — name them to match how your organization already talks about incidents rather than adopting a standard set that nobody recognizes.
Setting the next update time in every stage before Resolved is what keeps stakeholders from chasing you. A message that says nothing except “still working, next update at 15:00” is a good message.

​
Templates

A template holds the prepared content for one type, with separate text for each stage and each channel.
1

Create the template and pick its type

The type determines which audiences can receive it.
2

Write content for each stage

Within the template, each stage gets its own message. A template without content for a stage cannot be used at that stage.
3

Write each channel separately

Email subject and body, SMS text, and Slack message are authored independently, because they are read very differently.
4

Insert Liquid variables for anything factual

Title, summary, severity, affected services, and timestamps should come from the incident record.

​
Writing for Each Channel

The same update needs three different shapes:
  • Email carries the full message — context, impact, what is being done, when the next update comes. Subject lines can be long, but the useful part belongs at the front, since that is all a phone preview shows.
  • SMS is capped near 160 characters. Treat it as a pointer, not a summary: what is wrong, who is affected, where to read more. Longer messages split into multiple segments.
  • Slack sits between the two, and can carry links comfortably.
Email subject, header, and footer have generous limits — thousands of characters — so the practical constraint is what a reader will tolerate, not what the field accepts. SMS is the one channel where the limit genuinely bites.

​
Liquid Variables

Liquid is what makes a prepared template specific to the incident it is sent from. Instead of typing the severity into the message, the template references it and Rootly fills it in at send time. Use variables for anything that exists on the incident record — title, summary, severity, status, affected services and functionalities, timestamps, and links. Incident variables lists everything available.
A variable referencing a field the incident has not filled renders empty, which produces a message with a gap where the summary should be. For customer-facing templates, keep the sentence readable if a variable resolves to nothing, and make sure the incident fields your templates depend on are ones your process actually populates.
Preview a template against a real past incident before relying on it. Reading it filled in is the only way to catch a variable that resolves to something technically correct and completely unhelpful — an internal service slug in a customer email, for instance.

​
Keeping Templates Usable

  • Fewer, better templates. One well-written template per type covering every stage beats a dozen situational ones nobody can choose between under pressure.
  • Write for the reader, not the responder. Customer-facing templates should avoid internal service names, severity numbers, and team names.
  • Say what is being done, not how. “We have identified the cause and are deploying a fix” ages better than implementation detail that may turn out wrong.
  • Review templates after real incidents. The retrospective is the moment to notice a template that read badly, while the discomfort is fresh.
  • Manage them as code if your configuration is stable. Types, stages, and templates all have Terraform resources.

​
Troubleshooting

The template has no content for that stage. Add content for it, or pick a stage the template covers.
The variable name does not match an available one, or the syntax is malformed. Check it against incident variables.
A variable resolved to nothing because that field is empty on the incident — most often the summary. Fill it on the incident, then recreate the communication.
Groups or templates still reference it. Remove or reassign those first.
It exceeded a single segment. Rewrite the SMS content as a pointer with a link rather than a condensed version of the email.

Recipient Groups

The audiences a type’s templates reach.

Liquid Variables

Every incident value a template can reference.