Chat Component

Function

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

Creates a chatbot for building conversations powered by AI.

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 choosing how to configure 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 change the behavior or quality of responses. Test your configuration before deploying to production.

Manage chat conversations

You are responsible for managing the state and history of the conversation. This gives you full control over the user experience. Key responsibilities include:

• Persistent chat history: To create a continuous conversation, you must save the chat history. A common way to do this is to save the list of messages into a record type after each interaction.
• Conversational awareness: Most AI models are stateless. To ensure the model has context of the ongoing conversation, you must send the relevant chat history along with the user's latest message in each request.
• Multiple chat threads: You can build an interface that supports multiple, distinct conversations. To do this, create a mechanism (like a list of threads) that allows the user to select a thread, which then populates the messages parameter with the history for that specific conversation.

Using the messages parameter

The messages parameter is highly flexible and allows you to control the appearance of the chat log.

• Simple text: For a standard chat look, you can provide a simple list of text values. The component will apply default styling.
• Custom layouts: For a richer experience, you can pass a list of other components, such as a cardLayout or sideBySideLayout. This allows you to:
  • Add custom avatars for the user and the chatbot.
  • Apply rich text formatting to messages.
  • Include interactive elements, such as a button to edit or copy a message.

Limitations

• No asynchronous streaming: The chat component does not support streaming responses from the AI model in real-time. The full response must be received before it can be displayed in the interface.
• Expression-based configuration: The chat component must be configured using expression mode. A custom configuration experience in the design view is not currently available.

Use the chat component with your preferred AI model

You can use your preferred AI model by connecting the component to your AI model provider.

Before you start, make sure you have the following:

• Access to Appian Designer.
• A connected system for your chosen AI model provider.
• Permission to create integrations and expression rules.

Follow these steps to connect the chat component to your preferred AI model provider.

1. Create an integration object that connects to the orchestration layer for your provider.
2. Create an expression rule that calls the integration you created. The rule should return responses from your provider's language model.
3. Edit the interface that contains the chat component.
4. In the saveInto parameter, call the expression rule you created in step 2.

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
a!localVariables(
  local!chatMessages: {
    "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,
        /* step 1: user message */
        append(local!chatMessages, save!value)
      ),
      a!save(
        local!chatResponse,
        /* step 2: call custom expression rule that wraps your provider integration */
        rule!MY_CUSTOM_LLM_RESPONSE(
          userPrompt: save!value
        )
      ),
      a!save(
        local!chatMessages,
        /* step 3: add AI response */
        append(local!chatMessages, local!chatResponse) 
      )
    },
    showWhen: true,
    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 a local variable. The a!save() function in the saveInto parameter appends both the user's new message and a placeholder "…" response to the local messages variable, simulating a conversation.

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
a!localVariables(
  local!chatMessages: {
    "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,
        /* user message */
        append(local!chatMessages, save!value)
      ),
      a!save(
        local!chatResponse,
        a!callLanguageModel(
          prompt: "Default Prompt: " & save!value
        )
      ), /* get model response */
      a!save(
        local!chatMessages,
        /* add AI response */
        append(local!chatMessages, local!chatResponse) 
      )
    },
    showWhen: true,
    placeholder: "Type your question to get started",
    showBorder: true
  )
)

Displays the following:

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

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.

• Connect Document Viewer to an AI Chat Response:

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

Feedback