Skip to main content

Conversations

When a user interacts with an agent, Propeller creates a conversation. The conversation handles sending page context to the webhook and displaying the response. How the conversation starts and whether it supports follow-up messages depends on the agent's trigger type and interaction mode.

Trigger and interaction mode​

Trigger type (CHAT or BUTTON) and interaction mode (SINGLE_TURN or MULTI_TURN) are fully independent settings. All four combinations are valid:

TriggerModeBehavior
CHATSINGLE_TURNUser sends one message, gets one response. No follow-up
CHATMULTI_TURNUser sends messages back and forth in an ongoing conversation
BUTTONSINGLE_TURNUser clicks a button, gets one response immediately
BUTTONMULTI_TURNUser clicks a button to trigger the first interaction, then continues chatting in the modal that opens

Chat trigger​

A chat-triggered agent presents a text input where the user types a message. In single-turn mode the agent responds once and the conversation ends. In multi-turn mode the user can keep asking follow-up questions.

Example: An "AI Sales Assistant" (CHAT + MULTI_TURN) that helps a sales rep find cross-sell opportunities on an order through back-and-forth conversation.

Button trigger​

A button-triggered agent fires when the user clicks it. In single-turn mode the result is displayed immediately with no further interaction. In multi-turn mode the button opens a modal where the user can continue the conversation after the initial response.

Example: A "Margin Validator" (BUTTON + SINGLE_TURN) that analyzes margins on a quote and returns an instant approval or rejection.

How context is passed​

When an agent is invoked, Propeller sends a requestMetadata.payload object to the webhook containing the full context of the current view. In the built-in Sales Hub and Backoffice this payload is assembled automatically. When embedding agents in a custom frontend you build the payload yourself (see Embedding agents in your frontend).

For Sales Hub and Backoffice agent types the payload includes the full context of the current view: order/quote data with line items, pricing, margins, customer and company information, addresses, available carriers and payment methods, and revision history.

The agent's webhook receives all of this so the external workflow can make informed decisions without needing to call back into the Propeller API. For the complete field reference per agent type, see Agent payloads.

For chat agents the user's message is included as requestMessage. For button agents no user message is needed since the action is implicit.

Starting a conversation​

Create a new conversation with agentConversationCreate. This sends the agent ID, the current page context and (for chat agents) the user's first message to the webhook.

mutation AgentConversationCreate($input: AgentConversationCreateInput!) {
  agentConversationCreate(input: $input) {
    id
    messages {
      conversationId
      responseMessage
      responseMetadata
    }
  }
}

The response includes a conversationId and the agent's first reply. The responseMessage is the text shown to the user. The responseMetadata can contain structured data (for example margin calculations, approval status or timestamps).

Continuing a conversation​

For multi-turn agents, send subsequent messages with agentMessageCreate using the conversationId from the first response:

mutation AgentMessageCreate($input: AgentMessageCreateInput!) {
  agentMessageCreate(input: $input) {
    conversationId
    responseMessage
    responseMetadata
  }
}

The full page context is sent again with each message so the webhook always has up-to-date information.

See also​