> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS templates

<p className="lead">
  SMS templates define reusable text messages that the agent can send during a conversation, such as confirmations, links, or verification codes.
</p>

Templates support dynamic content through variables stored in conversation state.

<Warning>
  **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.
</Warning>

## Location

SMS templates are defined in:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup>
  <Card title="In rules, topics, and flows">
    Use `{{twilio_sms:template_name}}` to tell the agent which SMS should be sent.
  </Card>

  <Card title="In code">
    Call a function that triggers the SMS through `conv` or the platform API.
  </Card>

  <Card title="With variables">
    Use `{{vrbl:...}}` placeholders to insert values from conversation state.
  </Card>
</CardGroup>

## In prompts and instructions

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
{{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:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
{{vrbl:customer_name}}
```

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

For example:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<Tip>
  **Treat templates as reusable resources**

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

## Related pages

<CardGroup>
  <Card title="Variables" href="/adk/reference/variables">
    Learn how values are stored in `conv.state` and referenced with `{{vrbl:...}}`.
  </Card>

  <Card title="Functions" href="/adk/reference/functions">
    See how deterministic code can set variables and trigger SMS sending.
  </Card>

  <Card title="SMS setup (platform)" href="https://docs.poly.ai/sms/introduction">
    Configuring SMS channels, sender numbers, opt-out handling, and full template options.
  </Card>

  <Card title="Conversation object reference (platform)" href="https://docs.poly.ai/tools/classes/conv-object">
    Full reference for `conv.send_sms_template`, `conv.send_sms`, and all other `conv` methods.
  </Card>
</CardGroup>