Skip to main content

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-onlyThe 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:
FieldDescription
nameIdentifier for the template. Referenced in prompts as {{twilio_sms:template_name}}.
textMessage body. Supports {{vrbl:variable_name}} placeholders from conv.state.
env_phone_numbersOptional sender phone numbers for different environments.

​
Environment-specific sender numbers

If needed, you can define different sender numbers for different environments:
EnvironmentDescription
sandboxSender number for sandbox use
pre_releaseSender number for pre-release use
liveSender 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 resourcesSMS 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:...}}.

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.
Last modified on July 9, 2026