Template functions | SignalWire

Template functions provide simple text transformations for common operations like converting to lowercase, URL encoding, and date formatting. They complement JavaScript expressions by handling specific formatting tasks that don’t require complex logic.

For information about variable scopes, see the Variables Reference. For JavaScript expressions and data manipulation, see the Expressions Reference.

Template functions are only available in SWAIG (SignalWire AI Gateway) contexts, specifically within:

AI function data_map processing (expressions, webhooks, output)
Webhook responses to SWAIG functions
AI prompt variable expansion

They are not available in regular SWML methods or general variable contexts. For regular SWML variable manipulation, use JavaScript expressions with the ${expression} syntax instead.

Reference

lc

string

Converts a string to lowercase. Commonly used to normalize user input for case-insensitive comparisons or ensure consistent casing when accessing object properties dynamically.

Syntax: ${lc:<value>}

Example:

1 SWAIG:
2     functions:
3       - function: lookup
4         description: Look up department contact
5         parameters:
6           type: object
7           properties:
8             department:
9               type: string
10               description: Department name from user
11         data_map:
12           expressions:
13             - string: '${meta_data.contacts.${lc:args.department}}'
14               pattern: '\w+'
15               output:
16                 response: "Found contact for ${args.department}"
17         meta_data:
18           contacts:
19             sales: '+12025551234'
20             support: '+12025555678'

enc:url

string

Encodes a string for safe use in URLs by converting special characters to percent-encoded equivalents. Always use this when including variables in URL query parameters or paths to prevent special characters from breaking URLs or causing unexpected behavior.

Syntax: ${enc:url:<value>}

Example:

1 SWAIG:
2     functions:
3       - function: search
4         description: Search external knowledge base
5         parameters:
6           type: object
7           properties:
8             query:
9               type: string
10               description: User's search query
11         data_map:
12           webhooks:
13             - url: 'https://api.example.com/search?q=${enc:url:args.query}'
14               method: GET
15               output:
16                 response: "Found ${results.total} results for ${args.query}"

strftime_tz

string

Formats the current date and time using standard strftime format codes with timezone support. This generates timestamps at the moment the template is evaluated, not when the SWML script was created.

Syntax: @{strftime_tz <timezone> <format>}

Common format codes:

Code	Description	Example
`%Y-%m-%d`	ISO date	2025-01-15
`%H:%M:%S`	24-hour time	14:30:45
`%I:%M %p`	12-hour time	02:30 PM
`%A, %B %d, %Y`	Full readable date	Monday, January 15, 2025

Example:

1 SWAIG:
2     functions:
3       - function: log_call
4         description: Log call details with timestamp
5         data_map:
6           webhooks:
7             - url: 'https://api.example.com/logs'
8               method: POST
9               params:
10                 timestamp: '@{strftime_tz America/Chicago %Y-%m-%d %H:%M:%S}'
11                 call_id: '${call.call_id}'
12                 from: '${call.from}'
13               output:
14                 response: "Call logged successfully"

fmt_ph

string

Formats a phone number using specified international format standards. Supports multiple format types for different use cases, with optional separators for improved text-to-speech pronunciation.

Syntax: @{fmt_ph <format> <phone_number>} or @{fmt_ph <format>:sep:<separator> <phone_number>}

Available formats:

national - National format (default)
international - International format with country code
RFC3966 - RFC 3966 format (tel: URI)
e164 - E.164 format (+1234567890)

Example:

1 SWAIG:
2     functions:
3       - function: format_number
4         description: Format phone number for speech
5         data_map:
6           output:
7             response: |
8               International format: @{fmt_ph international ${call.from}}
9               Spaced format: @{fmt_ph national:sep:- ${call.from}}

expr

string

Evaluates simple arithmetic expressions with literal numbers. Supports addition, subtraction, multiplication, division, and parentheses for grouping. Only works with literal numbers and cannot reference variables.

Syntax: @{expr <expression>}

Example:

1 SWAIG:
2     functions:
3       - function: calculate_discount
4         description: Calculate discount amount
5         data_map:
6           output:
7             response: "The discount is @{expr (100 - 25) / 5} dollars"

echo

string

Returns the argument unchanged. Primarily useful for debugging template evaluation or forcing explicit variable expansion in complex nested scenarios.

Syntax: @{echo <text>}

Example:

1 SWAIG:
2     functions:
3       - function: debug_value
4         description: Debug template evaluation
5         parameters:
6           type: object
7           properties:
8             input:
9               type: string
10               description: Value to debug
11         data_map:
12           output:
13             response: "Debug value: @{echo ${args.input}}"

separate

string

Inserts spaces between each character in a string to improve text-to-speech pronunciation. Particularly useful for spelling out confirmation codes, license plates, serial numbers, or any text that should be read character-by-character.

Syntax: @{separate <text>}

Example:

1 SWAIG:
2     functions:
3       - function: spell_code
4         description: Spell out confirmation code
5         parameters:
6           type: object
7           properties:
8             code:
9               type: string
10               description: Confirmation code to spell
11         data_map:
12           output:
13             response: "Your code is @{separate ${args.code}}"

In this example, if code is “ABC123”, the AI will pronounce “A B C 1 2 3” instead of trying to say “ABC123” as a word.

sleep

string

Pauses execution for the specified number of seconds. Can be used for rate limiting, timing coordination, or testing purposes.

Syntax: @{sleep <seconds>}

Use sparingly in production environments. Excessive delays can cause timeouts, impact call quality, and degrade user experience. Best suited for development, testing, or specific rate-limiting scenarios.

Example:

1 SWAIG:
2     functions:
3       - function: delayed_task
4         description: Execute with delay for rate limiting
5         data_map:
6           output:
7             response: "Executed after @{sleep 2} second delay"

Function chaining

Prefix functions (using ${...} syntax) can be chained together to apply multiple transformations in sequence. The transformations are applied from left to right.

Syntax: ${func1:func2:func3:<value>}

Example:

1 SWAIG:
2   functions:
3     - function: search
4       description: Search external knowledge base
5       parameters:
6         type: object
7         properties:
8           query:
9             type: string
10             description: User's search query
11       data_map:
12         webhooks:
13           # First converts to lowercase, then URL encodes
14           - url: 'https://api.example.com/search?q=${lc:enc:url:args.query}'
15             method: GET
16             output:
17               response: "Found results for ${args.query}"

Full example

1 version: 1.0.0
2 sections:
3   main:
4     - answer: {}
5     - ai:
6         prompt:
7           text: |
8             You help users access department resources.
9             When they specify a department, use the lookup function.
10         SWAIG:
11           functions:
12             - function: lookup
13               description: Look up department contact
14               parameters:
15                 type: object
16                 properties:
17                   department:
18                     type: string
19                     description: Department name from user
20               data_map:
21                 expressions:
22                   - string: '${meta_data.contacts.${lc:args.department}}'
23                     pattern: '\w+'
24                     output:
25                       response: "Found contact for ${args.department}"
26               meta_data:
27                 contacts:
28                   sales: '+12025551234'
29                   support: '+12025555678'