SMS templates

SMS templates define reusable text messages that the agent can send during a conversation, such as confirmations, links, or verification codes.

Templates support dynamic content through variables stored in conversation state.

SMS templates are ADK-only

The Agent Studio UI does not currently expose an editor for config/sms_templates.yaml. Define templates through the ADK and push them with poly push. Template references of the form {{twilio_sms:template_name}} only resolve inside ADK-managed files (rules.txt, topic actions, flow prompts) — pasting them into a UI-editable field does not work at runtime.

Location

SMS templates are defined in:

config/sms_templates.yaml

Templates are listed under the sms_templates key.

What an SMS template contains

Each template can include the following fields:

Field	Description
name	Identifier for the template. Referenced in prompts as {{twilio_sms:template_name}}.
text	Message body. Supports {{vrbl:variable_name}} placeholders from conv.state.
env_phone_numbers	Optional sender phone numbers for different environments.

Environment-specific sender numbers

If needed, you can define different sender numbers for different environments:

Environment	Description
sandbox	Sender number for sandbox use
pre_release	Sender number for pre-release use
live	Sender number for production use

Example

sms_templates:
  - name: booking_confirmation
    text: "Hi {{vrbl:customer_name}}, your booking for {{vrbl:booking_date}} is confirmed. Reference: {{vrbl:booking_ref}}"
    env_phone_numbers:
      sandbox: "[phone]"
      live: "[phone]"

  - name: verification_code
    text: "Your verification code is {{vrbl:verification_code}}. It expires in 10 minutes."

How SMS templates are used

In rules, topics, and flows

Use {{twilio_sms:template_name}} to tell the agent which SMS should be sent.

In code

Call a function that triggers the SMS through conv or the platform API.

With variables

Use {{vrbl:...}} placeholders to insert values from conversation state.

In prompts and instructions

SMS templates can be referenced in rules, topics, and related instructions using:

{{twilio_sms:template_name}}

This lets you reference the correct template by name without embedding the full message body in prompt text.

Using variables

Template text can include placeholders drawn from conv.state, for example:

{{vrbl:customer_name}}

Before the SMS is sent, the corresponding state variables should already be set in code.

For example:

conv.state.customer_name = "Alice"
conv.state.booking_date = "12 March"
conv.state.booking_ref = "ABC123"

Best practices

• set required state variables before the SMS is triggered
• use separate templates for different purposes such as confirmation, verification, and follow-up
• keep templates short and clear
• configure env_phone_numbers when sender numbers differ between environments
• prefer template references over hard-coded SMS text in prompts

Treat templates as reusable resources

SMS templates are easier to manage when each template has one clear purpose and a stable name.

Related pages

Variables

Learn how values are stored in conv.state and referenced with {{vrbl:...}}.

Functions

See how deterministic code can set variables and trigger SMS sending.

SMS setup (platform)

Configuring SMS channels, sender numbers, opt-out handling, and full template options.

Conversation object reference (platform)

Full reference for conv.send_sms_template, conv.send_sms, and all other conv methods.