Skip to content

Chat settings

Chat settings configure how the agent behaves on the web chat channel. They are defined in chat/configuration.yaml.

Platform-provisioned — update only

Chat settings are created automatically when a project is created. They can be updated with poly push but not created from scratch. See the equivalent note on agent settings for details.

Location

chat/
├── configuration.yaml
└── safety_filters.yaml       # Optional

What chat settings control

  • Greeting

    The first message the agent sends when a chat session starts.

  • Style prompt

    Channel-specific instructions that shape how the agent writes in chat.

  • Safety filters

    Optional chat-channel content safety filter overrides.

Greeting

The greeting is the first message the agent sends when a chat session starts.

Fields

Field Required Description
welcome_message Yes Text of the greeting. Supports {{attr:...}}, {{vrbl:...}}, and {{tn:...}} references.
language_code Yes BCP-47 language code, for example en-GB or en-US.

Example

greeting:
  welcome_message: Hi there! How can I help you today?
  language_code: en-GB

A start function utterance replaces the greeting

If start_function.py produces an utterance on the first turn (via conv.say() or a returned string), it replaces welcome_message — the configured greeting is not sent, and no error is raised.

Style prompt

The style prompt contains channel-specific instructions that shape how the agent writes.

Use this for chat-specific guidance such as:

  • keeping responses concise
  • using bullet points for lists
  • adjusting formatting for readability

This is separate from the agent's broader persona. Use it to control how the agent communicates specifically in web chat.

Fields

Field Required Description
prompt No Free-text style instructions. Resource references are not allowed.

Example

style_prompt:
  prompt: You are a helpful and professional web chat assistant. Keep responses concise and use formatting where appropriate.

Keep chat guidance channel-specific

Use the style prompt for instructions that only apply to chat, such as formatting, brevity, or written tone. Use agent settings for broader identity and behavioral guidance.

Safety filters

chat/safety_filters.yaml is an optional file that overrides the project-level safety filter settings for the chat channel. When present, it takes precedence over agent_settings/safety_filters.yaml for chat interactions.

See the Safety filters reference for the full schema, field descriptions, and examples.

Validation

Chat greeting, style prompt, and safety filters are validated as a set: if any one of chat/configuration.yaml's greeting or style_prompt sections or chat/safety_filters.yaml is present locally, the other two must be present as well. poly push fails with a "Webchat config resources must all be present together" error if one is missing.

Full example

greeting:
  welcome_message: Hi! How can I help you today?
  language_code: en-GB
style_prompt:
  prompt: You are a helpful and professional web chat assistant. Keep responses concise.

  • Safety filters

    Configure content safety filtering at the project and channel level. Open safety filters

  • Agent settings

    Define the agent's overall identity, role, and rules. Open agent settings

  • Voice settings

    Configure the equivalent behavior for the voice channel. Open voice settings