Embedding agents in your frontend

Agents are not limited to the Propeller Sales Hub and Backoffice. As an implementation partner you can embed agents in any custom frontend (webshop, customer portal, mobile app) by defining your own agent types and using the GraphQL conversation API.

How custom types work

The types field on an agent accepts any value in SCREAMING_SNAKE_CASE format. The built-in types like SALES_HUB_ORDER_EDITOR are conventions used by the Propeller UI. You can create agents with custom types that only your frontend knows about.

Step 1: Create an agent with a custom type

Use the Backoffice Agents page or the agentCreate mutation. The type can be anything you define:

{
  "input": {
    "names": [{ "language": "EN", "value": "Shopping Assistant" }],
    "descriptions": [{ "language": "EN", "value": "Helps customers with product questions" }],
    "trigger": "CHAT",
    "interactionMode": "MULTI_TURN",
    "active": true,
    "types": ["FRONTEND_SHOPPING_BASKET"],
    "webhookUrl": "https://your-workflow-engine.com/webhook/shopping-assistant",
    "webhookTimeoutMs": 15000,
    "welcomeMessages": [
      { "language": "EN", "value": "Hi! Need help with your order?" }
    ]
  }
}

Step 2: Query agents from your frontend

On page load (or when a chat component mounts) query for active agents matching your custom type:

query agents($input: AgentSearchInput) {
  agents(input: $input) {
    items {
      id
      names { language value }
      trigger
      interactionMode
      welcomeMessages { language value }
      buttonLabels { language value }
    }
  }
}

{
  "input": {
    "types": ["FRONTEND_SHOPPING_BASKET"],
    "active": true
  }
}

This returns all agents configured for your shopping basket view. You might get a chat assistant and a "Check stock availability" button agent.

Step 3: Render in your UI

How you present the agents is up to you. Some patterns:

Display chat agents as a floating chat widget or inline chat panel
Display button agents as action buttons in a toolbar or card
Use welcomeMessages as the initial greeting in a chat bubble
Use buttonLabels as the button text
Show or hide agents based on user role, cart contents or any other frontend logic

Step 4: Start and continue conversations

When the user interacts with an agent, call agentConversationCreate with the agent ID and the relevant page context. You build the requestMetadata.payload yourself with whatever data the webhook needs:

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

The requestMetadata.payload is freeform. In the Propeller Backoffice it contains the full order data, but in your frontend you can pass anything: cart contents, product details, user preferences or whatever your webhook needs to generate a useful response.

For multi-turn agents, send follow-up messages with agentMessageCreate using the conversationId from the first response.

Example: custom types for a webshop

A single webshop might use several custom agent types across different pages:

Custom Type	Where	Example Agent
`WEBSHOP_PRODUCT_DETAIL`	Product page	"Ask about this product" chat
`WEBSHOP_SHOPPING_BASKET`	Cart page	"Check delivery time" button
`WEBSHOP_CHECKOUT`	Checkout flow	"Apply best discount" button
`CUSTOMER_PORTAL_ORDERS`	Order history	"Track my order" chat
`CUSTOMER_PORTAL_RETURNS`	Returns page	"Start a return" button + chat

Each type maps to a different set of agents with different webhook backends. The frontend queries for the right type on each page and renders whatever comes back.

How custom types work​

Step 1: Create an agent with a custom type​

Step 2: Query agents from your frontend​

Step 3: Render in your UI​

Step 4: Start and continue conversations​

Example: custom types for a webshop​

See also​