Chat Component

Function

a!chatField( title, helpTooltip, messages, height, shape, saveInto, showWhen, placeholder, showBorder, streamingUuid, streamingSaveInto, backgroundColor )

Displays an interactive chat interface that lets users send and receive messages in real time.

The chat component gives users an interactive way to work with AI and serves as a core building block for designing many types of chat experiences. It includes key user experience features like automatic scrolling and pressing Enter to send a message, while giving you complete control over the conversation's logic and appearance. By default, it uses Appian's chosen language model through the call language model function: a!callLanguageModel. However, it also supports using your preferred AI model.

You control how the chat behaves and looks. This includes managing chat history, setting conversational context, and customizing the style of messages.

Parameters

Considerations

Keep the following considerations in mind when configuring the chat component.

• Using the default call language model function, a!callLanguageModel(), is the simplest option and requires less setup. See the example on the Call Language Model Function page for details.
• When using your own preferred AI model, make sure your integration handles authentication, request formatting, and error handling.
• Switching AI model providers may alter response quality. Always test your configuration before deploying to production.

Manage chat history

You are responsible for managing the state and history of the conversation. To ensure a coherent user experience, consider the following:

• Persistence: To create a continuous conversation, save the chat history into a record type or database after each interaction.
• Context: Most AI models are stateless. To provide context, you must send the relevant chat history along with the user's new message in every request.
• Threading: To support multiple concurrent conversations, create a mechanism (such as a list of threads) that allows the user to switch contexts. When a user selects a thread, populate the messages parameter with the history for that specific conversation.

Chat streaming

Chat streaming allows the interface to display AI-generated text in real-time as it is created. When a user sends a message, a typing animation appears, and text displays progressively.

Streaming is supported only for text outputs generated by Large Language Models (LLMs) when using default styling. It does not support structured data, image generation, or custom message displays.

Using the messages parameter

The messages parameter requires a single a!chatMessage object or a list of a!chatMessage objects. Each message must be constructed using a!chatMessage(). The messages parameter allows you to control the look and feel of the chat log. The messageContent within each a!chatMessage can be:

• Plain text: For a standard chat appearance with default styling.
• Custom components: Use interface components such as cardLayout or sideBySideLayout for a richer experience. This allows you to:
  • Display custom avatars for the user and the AI.
  • Apply rich text formatting.
  • Include interactive elements, such as copy or edit buttons.

Limitations

• Configuration: You must configure the chat component using expression mode. The design view configuration pane is not currently available for this component.

AI Guardrails behavior

When AI Guardrails are enabled and a Block action triggers during a chat interaction, the chat component displays the administrator-configured block message to the user instead of the AI model's response. The conversation can continue after a block—the user can send a new message.

Use the chat component with your preferred AI model

You can connect the chat component to an external AI provider instead of the default Appian model.

Prerequisites:

• A connected system for your AI provider.
• Permissions to create integrations and expression rules.

To connect a custom model:

1. Create an integration object that connects to your AI provider's API.
2. Create an expression rule that calls this integration. The rule must return the model's response.
3. In your interface, locate the saveInto parameter of the a!chatField.
4. Call your expression rule within the saveInto parameter to handle the user's input and update the chat history.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
a!localVariables(
  local!chatMessages: {
    a!chatMessage(
      role: "ASSISTANT",
      messageContent: "Hello! How can I help you today?"
    )
  },
  local!chatResponse: null,

  a!chatField(
    title: "Chat with Support",
    helpTooltip: "Type your question to start chatting.",
    messages: local!chatMessages,
    height: "MEDIUM",
    shape: "ROUNDED",
    saveInto: {
      a!save(
        local!chatMessages,
        append(
          local!chatMessages,
          a!chatMessage(role: "USER", messageContent: save!value)
        )
      ),
      a!save(
        local!chatResponse,
        rule!MY_CUSTOM_LLM_RESPONSE(
          userPrompt: save!value
        )
      ),
      a!save(
        local!chatMessages,
        append(
          local!chatMessages,
          a!chatMessage(role: "ASSISTANT", messageContent: local!chatResponse)
        )
      )
    },
    placeholder: "Type your question to get started",
    showBorder: true
  )
)

Examples

To experiment with these examples, copy, and paste the expression into an interface object.

Basic chat interface

This example demonstrates a simple chat setup. It stores the conversation history in local variables. When a user sends a message, the message is added to the local!messages variable. Then, a!callLanguageModel runs with the full message history as context. The AI model's response is saved to local!modelResponse and added to the local!messages list, which updates the interface with the new response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
a!localVariables(
  local!messages: {},
  local!roles: {},
  local!modelResponse: "",
  a!chatField(
    title: "Chat",
    messages: a!forEach(
      local!messages,
      a!chatMessage(
        messageContent: fv!item,
        role: local!roles[fv!index]
      )
    ),
    placeholder: "Ask a question...",
    saveInto: {
      /* 1. Append the user's message */
      a!save(local!messages, append(local!messages, save!value)),
      a!save(local!roles, append(local!roles, "USER")),
      /* 2. Call the language model */
      a!save(
        local!modelResponse,
        a!callLanguageModel(
          messages: a!forEach(
            local!messages,
            a!map(
              messageContent: fv!item,
              role: local!roles[fv!index]
            )
          ),
          prompt: "You are a helpful assistant."
        )
      ),
      /* 3. Append the model's response */
      a!save(local!messages, append(local!messages, local!modelResponse)),
      a!save(local!roles, append(local!roles, "ASSISTANT"))
    }
  )
)

Displays the following:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Chat interface with streaming

This example demonstrates streaming functionality for real-time AI responses. The streaming response appears progressively as it's generated.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
a!localVariables(
  /* Conversation history */
  local!messages: {},

  /* Holds the partial streaming response */
  local!streamedResponse: a!map(done: true(), text: ""),

  /* Tracks the active streaming request */
  local!streamingUuid,

  a!chatField(
    title: "Streaming chat example",
    height: "TALL",

    /* Show full history plus any partial streaming text */
    messages: if(
      a!isNotNullOrEmpty(local!streamedResponse.text),
      append(
        a!forEach(
          items: local!messages,
          expression: a!chatMessage(
            role: fv!item.role,
            messageContent: fv!item.messageContent
          )
        ),
        a!chatMessage(
          role: "ASSISTANT",
          messageContent: local!streamedResponse.text
        )
      ),
      a!forEach(
        items: local!messages,
        expression: a!chatMessage(
          role: fv!item.role,
          messageContent: fv!item.messageContent
        )
      )
    ),

    saveInto: {
      /* Save the user message as a plain map */
      a!save(
        local!messages,
        append(
          local!messages,
          a!map(role: "USER", messageContent: save!value)
        )
      ),

      /* Start a streaming call with the plain map messages */
      a!save(
        local!streamingUuid,
        a!callLanguageModel(
          prompt: "You are a helpful assistant.",
          isStreaming: true(),
          messages: local!messages
        )
      )
    },

    streamingUuid: local!streamingUuid,

    /* Update the UI as each streaming event arrives */
    streamingSaveInto: a!localVariables(
      local!event,
      {
        a!save(local!event, save!value),

        if(
          local!event.done,
          {
            /* When streaming finishes, add the full response to history as a plain map */
            a!save(local!streamedResponse, a!map()),
            a!save(
              local!messages,
              append(
                local!messages,
                a!map(role: "ASSISTANT", messageContent: local!event.text)
              )
            )
          },
          /* While streaming, show the partial response text */
          a!save(local!streamedResponse, local!event)
        )
      }
    )
  )
)

Custom chat interface

You can build a custom chat-style interface by using the cardLayout component to give each message a distinct visual style. A common approach is to store each message as an object with a sender and text field. Then, apply conditional formatting to display different icons and styles depending on the sender.

For a step-by-step implementation, see the recipe Build a Custom Chat Interface.

Example

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Feature compatibility

Related recipes

The following recipes include usage of the Chat Component.

• Build a Chatbot with Persistent History (Chat, AI):

  Create a chatbot that maintains conversation continuity by storing and retrieving message history from a record type.

• Build an AI Chat with Real-Time Streaming and Persistent History (Chat, AI):

  Build an AI chat interface with real-time streaming responses and persistent conversation history using the Chat Field component.

• Connect Document Viewer to an AI Chat Response:

  This pattern illustrates how to connect a!documentViewerField component to an AI chat response.

Feedback