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 an order detail view in the Sales Hub the automatic payload includes:

  • Order details including orderId, status, source, creation date and tenderId
  • Contact and company including name, email, phone, tax number, chamber of commerce number and pricesheets
  • Addresses for delivery and invoice
  • Line items with cost price, customer price, margin, discount, quantity, SKU, supplier, tax info, inventory levels, bundle and cross/upsell metadata, and any child items (accessories, options, surcharges)
  • Totals including subtotal, total gross/net, tax and discount amounts
  • Shipping with available carriers and pricing
  • Payment with available payment methods and current payment status
  • Revisions with order revision history, timestamps and status snapshots

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 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​