prompt | SignalWire

Defines the AI agent’s personality, goals, behaviors, and instructions for handling conversations. The prompt establishes how the agent should interact with callers, what information it should gather, and how it should respond to various scenarios.

It is recommended to write prompts using markdown formatting as LLMs better understand structured content. Additionally it is recommended to read the Prompting Best Practices guide.

Prompt types

There are three ways to define prompt content, each suited for different use cases:

Text prompt — A single string containing the full prompt. Best for simple agents where the entire personality, instructions, and rules fit naturally into one block of text.
POM (Prompt Object Model) — A structured array of sections with titles, body text, and bullet points. Best for complex prompts that benefit from clear organization. SignalWire renders the POM into a markdown document before sending it to the LLM.
Contexts — A system of named conversation flows, each with its own steps, memory settings, and transition logic. Best for multi-stage conversations where the agent needs to switch between distinct modes (e.g., greeting → support → billing). Requires a default context as the entry point. See Contexts below.

Text and POM are mutually exclusive — use one or the other. Contexts can be combined with either a text or POM prompt to add structured conversation flows on top of the base prompt.

Properties

ai.prompt

object

An object that contains the prompt parameters.

The prompt property accepts one of the following objects:

Regular Prompt

POM Prompts

prompt.text

stringRequired

The main identity prompt for the AI. This prompt will be used to outline the agent’s personality, role, and other characteristics.

prompt.temperature

numberDefaults to 1.0

Randomness setting. Float value between 0.0 and 1.5. Closer to 0 will make the output less random.

prompt.top_p

numberDefaults to 1.0

Randomness setting. Alternative to temperature. Float value between 0.0 and 1.0. Closer to 0 will make the output less random.

prompt.confidence

numberDefaults to 0.6

Threshold to fire a speech-detect event at the end of the utterance. Float value between 0.0 and 1.0. Decreasing this value will reduce the pause after the user speaks, but may introduce false positives.

prompt.presence_penalty

numberDefaults to 0

Aversion to staying on topic. Float value between -2.0 and 2.0. Positive values increase the model’s likelihood to talk about new topics.

prompt.frequency_penalty

numberDefaults to 0

Aversion to repeating lines. Float value between -2.0 and 2.0. Positive values decrease the model’s likelihood to repeat the same line verbatim.

prompt.max_tokens

integerDefaults to 256

Limits the amount of tokens that the AI agent may generate when creating its response. Valid value range: 0 - 4096.

prompt.contexts

object

An object that defines the available contexts for the AI. Each context represents a set of steps that guide the flow of the conversation. The object must include a default key, which specifies the initial context used at the start of the conversation. Additional contexts can be added as other keys within the object.

contexts.default

objectRequired

The default context used at the beginning of the conversation.

contexts.*

object

Additional contexts for specialized conversation flows. The key is user-defined (e.g., support, sales, billing).

*.steps

object[]Required

An array of step objects that define the conversation flow for this context. Steps execute sequentially unless otherwise specified. Each step contains either a text string or a pom array to provide prompt instructions.

*.isolated

booleanDefaults to false

When true, resets conversation history to only the system prompt when entering this context. Useful for focused tasks that shouldn’t be influenced by previous conversation.

*.enter_fillers

object[]

Language-specific filler phrases played when transitioning into this context.

enter_fillers[].<language_code toc={true}>

string[]

An array of filler phrases for the specified language code. One phrase is randomly selected during transitions. Possible language codes:

default - Default language set by the user in the ai.languages property
bg - Bulgarian
ca - Catalan
cs - Czech
da - Danish
da-DK - Danish (Denmark)
de - German
de-CH - German (Switzerland)
el - Greek
en - English
en-AU - English (Australia)
en-GB - English (United Kingdom)
en-IN - English (India)
en-NZ - English (New Zealand)
en-US - English (United States)
es - Spanish
es-419 - Spanish (Latin America)
et - Estonian
fi - Finnish
fr - French
fr-CA - French (Canada)
hi - Hindi
hu - Hungarian
id - Indonesian
it - Italian
ja - Japanese
ko - Korean
ko-KR - Korean (South Korea)
lt - Lithuanian
lv - Latvian
ms - Malay
multi - Multilingual (Spanish + English)
nl - Dutch
nl-BE - Flemish (Belgian Dutch)
no - Norwegian
pl - Polish
pt - Portuguese
pt-BR - Portuguese (Brazil)
pt-PT - Portuguese (Portugal)
ro - Romanian
ru - Russian
sk - Slovak
sv - Swedish
sv-SE - Swedish (Sweden)
th - Thai
th-TH - Thai (Thailand)
tr - Turkish
uk - Ukrainian
vi - Vietnamese
zh - Chinese (Simplified)
zh-CN - Chinese (Simplified, China)
zh-Hans - Chinese (Simplified Han)
zh-Hant - Chinese (Traditional Han)
zh-HK - Chinese (Traditional, Hong Kong)
zh-TW - Chinese (Traditional, Taiwan)

*.exit_fillers

object[]

Language-specific filler phrases played when leaving this context. Same format as enter_fillers.

Examples

Basic prompt

1 version: 1.0.0
2 sections:
3   main:
4     - ai:
5         prompt:
6           text: |
7             You are a friendly customer service agent for a telecommunications company.
8             Your name is Alex. Always greet the caller warmly and ask how you can help.
9 
10             ## Rules
11             - Be polite and professional at all times
12             - If the caller asks about billing, offer to transfer them to the billing department
13             - If you cannot help with a request, apologize and suggest alternatives
14           temperature: 0.8
15           top_p: 0.9
16           confidence: 0.6

POM prompt

1 version: 1.0.0
2 sections:
3   main:
4     - ai:
5         prompt:
6           text: "Prompt is defined in pom"
7           pom:
8             - title: "Agent Personality"
9               body: "You are a friendly and engaging assistant. Keep the conversation light and fun."
10               subsections:
11                 - title: "Personal Information"
12                   numberedBullets: true
13                   bullets:
14                     - "You are a AI Agent"
15                     - "Your name is Frank"
16                     - "You work at SignalWire"
17             - title: "Task"
18               body: "You are to ask the user a series of questions to gather information."
19               bullets:
20                 - "Ask the user to provide their name"
21                 - "Ask the user to provide their favorite color"
22                 - "Ask the user to provide their favorite food"
23                 - "Ask the user to provide their favorite movie"
24                 - "Ask the user to provide their favorite TV show"
25                 - "Ask the user to provide their favorite music"
26                 - "Ask the user to provide their favorite sport"
27                 - "Ask the user to provide their favorite animal"

Rendered prompt

The above POM example will render the following markdown prompt:

1 ## Agent Personality
2 
3 You are a friendly and engaging assistant. Keep the conversation light and fun.
4 
5 ### Personal Information
6 
7 1. You are a AI Agent
8 2. Your name is Frank
9 3. You work at SignalWire
10 
11 ## Task
12 
13 You are to ask the user a series of questions to gather information.
14 
15 - Ask the user to provide their name
16 - Ask the user to provide their favorite color
17 - Ask the user to provide their favorite food
18 - Ask the user to provide their favorite movie
19 - Ask the user to provide their favorite TV show
20 - Ask the user to provide their favorite music
21 - Ask the user to provide their favorite sport
22 - Ask the user to provide their favorite animal

Basic context

1 version: 1.0.0
2 sections:
3   main:
4     - ai:
5         prompt:
6           text: You are a helpful assistant that can switch between different expertise areas.
7           contexts:
8             default:
9               steps:
10                 - name: greeting
11                   text: Greet the user and ask what they need help with. If they need technical support, transfer them to the support context.
12                   valid_contexts:
13                     - support
14             support:
15               isolated: true
16               enter_fillers:
17                 - en-US: ["Switching to technical support", "Let me connect you with support"]
18                   es-ES: ["Cambiando a soporte técnico", "Permítame conectarlo con soporte"]
19               exit_fillers:
20                 - en-US: ["Leaving support mode", "Returning to main menu"]
21                   es-ES: ["Saliendo del modo de soporte", "Volviendo al menú principal"]
22               steps:
23                 - name: troubleshoot
24                   text: Help the user troubleshoot their technical issue. When finished, ask if they need anything else or want to return to the main menu.
25                   valid_contexts:
26                     - default

Advanced multi-context

This example demonstrates multiple contexts with different AI personalities, voice settings, and specialized knowledge domains:

1 sections:
2   main:
3     - ai:
4         hints:
5           - StarWars
6           - StarTrek
7         languages:
8           - name: Ryan-English
9             voice: elevenlabs.patrick
10             code: en-US
11           - name: Luke-English
12             voice: elevenlabs.fin
13             code: en-US
14           - name: Spock-English
15             voice: elevenlabs.charlie
16             code: en-US
17         prompt:
18           text: Help the user transfer to the Star Wars or Star Trek expert.
19           contexts:
20             default:
21               steps:
22                 - name: start
23                   text: |+
24                     Your name is Ryan. You are a receptionist. Your only purpose is to change the context to starwars or startrek.
25                   step_criteria: |+
26                     Introduce yourself as Ryan.
27                     Ask the user if he would like to talk to a star wars or star trek expert until they provide an adequate answer.
28                 - name: transfer
29                   text: You will now successfully transfer the user to the Star Wars or Star Trek expert.
30                   step_criteria: If the user has chosen a valid context, transfer them to the appropriate expert.
31                   valid_contexts:
32                     - starwars
33                     - startrek
34             starwars:
35               steps:
36                 - name: start
37                   text: |+
38                     The user has been transferred to the Star Wars expert.
39                     Until told otherwise, your name is Luke. Change the language to Luke-English.
40                     Your current goal is to get the user to tell you their name.
41                     Unless told otherwise, refer to the user as 'Padawan {users_name}'.
42                   step_criteria: |+
43                     Introduce yourself as Luke, the Star Wars expert.
44                     The user must tell you their name if they only say one word assume that is their name.
45                 - name: question
46                   text: |+
47                     Your goal is to get the user to choose one of the following options.
48                     - Jedi Order (advance to jedi_order step)
49                     - The ways of the Force (advance to force step)
50                     - Talk to the star trek expert. (change context to startrek)
51                   step_criteria: +|
52                     The user must provide a valid answer to continue.
53                     Refer to the user as 'Padawan {users_name}' for the rest of the conversation.
54                   valid_steps:
55                     - jedi_order
56                     - force
57                   valid_contexts:
58                     - startrek
59                 - name: jedi_order
60                   text: |+
61                     Limit the topic to the Jedi Order.
62                     Inform the user they can say they want to change the topic at any time, if they do move to the question step.
63                   step_criteria: The user says they want to change the topic.
64                   valid_steps:
65                     - question
66                 - name: force
67                   text: |+
68                     Limit the topic to the force.
69                     Inform the user they can say they want to change the topic at any time, if they do move to the question step.
70                   step_criteria: The user says they want to change the topic.
71                   valid_steps:
72                     - question
73             startrek:
74               steps:
75                 - name: start
76                   text: |+
77                     The user has been transferred to the Star Trek expert.
78                     Until told otherwise, your name is Spok. Change the language to Spok-English.
79                     Your current goal is to get the user to tell you their name.
80                     Unless told otherwise, refer to the user as 'Ensign {users_name}'.
81                   step_criteria: |+
82                     Introduce yourself as Spok, the Star Trek expert.
83                     The user must tell you their name if they only say one word assume that is their name.
84                 - name: question
85                   text: |+
86                     Your goal is to get the user to choose one of the following options.
87                     - Vulcan Culture (advance to vulcan_culture step)
88                     - Federation (advance to federation step)
89                     - Talk to the star wars expert. (change context to starwars)
90                   step_criteria: +|
91                     The user must provide a valid answer to continue.
92                     Refer to the user as 'Ensign {users_name}' for the rest of the conversation.
93                   valid_steps:
94                     - vulcan_culture
95                     - federation
96                   valid_contexts:
97                     - starwars
98                 - name: vulcan_culture
99                   text: |+
100                     Limit the topic to Vulcan Culture.
101                     Inform the user they can say they want to change the topic at any time, if they do move to the question step.
102                   step_criteria: The user says they want to change the topic.
103                   valid_steps:
104                     - question
105                 - name: federation
106                   text: |+
107                     Limit the topic to the Federation of Planets.
108                     Inform the user they can say they want to change the topic at any time, if they do move to the question step.
109                   step_criteria: The user says they want to change the topic.
110                   valid_steps:
111                     - question

Variable Expansion

Use the following syntax to expand variables into your prompt.

${call_direction}

string

Inbound or outbound.

${caller_id_number}

string

The caller ID number.

${local_date}

string

The local date.

${spoken_date}

string

The spoken date.

${local_time}

string

The local time.

${time_of_day}

string

The time of day.

${supported_languages}

string

A list of supported languages.

${default_language}

string

The default language.