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 usually make informed decisions without extra API calls. When a workflow needs more than the page context, it can call the Propeller API with its own API key, for example to look up a company's recent orders or to modify the quote the user is viewing before it responds. 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 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).

The conversationId is generated by your webhook, not by Propeller

The first webhook request contains no conversationId. Your webhook generates one (any unique, non-blank string) and returns it in the conversationId field of its response. Propeller passes it back to your frontend in messages[].conversationId. This is because the conversation state lives in your workflow, so your workflow owns the identifier it stores that state under. Without a conversationId in the first webhook response, follow-up messages cannot be linked to the conversation.

Note that the conversation record's own id is a different value. For follow-up messages, use the conversationId from messages, not the conversation id.

Continuing a conversation​

For multi-turn agents, send subsequent messages with agentMessageCreate using the conversationId your webhook returned in 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. Each follow-up request to the webhook includes the conversationId, so the workflow can look up its conversation state and echo the same value back in its response.

See also​