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: "+15551234567"
      live: "+15559876543"

  - 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.

Variables

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

See how deterministic code can set variables and trigger SMS sending. Open functions
SMS setup (platform)

Configuring SMS channels, sender numbers, opt-out handling, and full template options. Open SMS setup
Conversation object reference (platform)

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