> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearline.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Widgets

> Launch interactive marketing sessions on customer-facing screens

Widget endpoints allow you to display interactive marketing content on customer-facing screens. Widgets are pre-configured marketing actions that customers can engage with during checkout, such as joining loyalty programs, viewing offers, or signing up for promotions.

## What are Widgets?

Widgets are interactive marketing modules that appear on customer-facing screens (CFS). Using these endpoints, you can:

* **List Available Widgets:** Get all active marketing widgets configured for a location
* **Start Widget Sessions:** Launch a widget for customer interaction
* **Show QR Codes:** Display QR codes for customers to scan and engage on mobile
* **Send Messages:** Deliver marketing content via SMS or email

## How It Works

<Steps>
  <Step title="Retrieve Widget List" icon="list">
    Call the [list widgets endpoint](/api-reference/widgets/get-widgets-list) to
    get available marketing actions for your location.
  </Step>

  <Step title="Display Widget Options" icon="display">
    Show widget choices on your customer-facing screen (e.g., "Join Loyalty
    Program", "View Special Offers").
  </Step>

  <Step title="Start Widget Session" icon="play">
    When customer selects a widget, use [start widget
    endpoint](/api-reference/widgets/start-pos-widget-session) to initiate the
    interaction.
  </Step>

  <Step title="Show QR Code or Send Message" icon="qrcode">
    Display a QR code for mobile engagement or send content directly via
    SMS/email using the respective endpoints.
  </Step>
</Steps>

## Widget Endpoints

<CardGroup cols={2}>
  <Card title="Get Widgets List" icon="list" href="/api-reference/widgets/get-widgets-list">
    Retrieve all available marketing widgets for a location
  </Card>

  <Card title="Start POS Widget Session" icon="play" href="/api-reference/widgets/start-pos-widget-session">
    Launch a widget session for customer interaction
  </Card>

  <Card title="Show QR Code" icon="qrcode" href="/api-reference/widgets/show-qr-code-for-widget-session">
    Display QR code for customers to scan and engage
  </Card>

  <Card title="Send Message" icon="envelope" href="/api-reference/widgets/send-message-for-widget-session">
    Deliver widget content via SMS or email
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Refresh Widget List Periodically" icon="arrows-rotate" defaultOpen>
    Fetch the widget list every 15-30 minutes or when your POS starts to ensure
    you display current marketing campaigns.
  </Accordion>

  <Accordion title="Filter by Context" icon="filter">
    Show widgets appropriate for the current context (checkout, idle screen,
    post-purchase) based on widget configuration.
  </Accordion>

  <Accordion title="Handle Customer Choice" icon="hand-pointer">
    Let customers choose how to engage - QR code for mobile or direct SMS/email
    delivery. Support both methods.
  </Accordion>

  <Accordion title="Track Widget Performance" icon="chart-line">
    Monitor which widgets customers interact with most to optimize your
    marketing strategy.
  </Accordion>

  <Accordion title="Timeout Inactive Sessions" icon="clock">
    If a customer doesn't interact with a widget within 30-60 seconds, timeout
    the session and return to idle state.
  </Accordion>
</AccordionGroup>

## Common Widget Types

Widgets can be configured for various marketing actions:

* **Loyalty Enrollment:** Sign up new customers for your loyalty program
* **Promotion Signup:** Register for special offers or campaigns
* **Email/SMS Collection:** Capture customer contact information
* **Coupon Delivery:** Send discount codes to customers
* **Survey/Feedback:** Collect customer feedback or preferences
* **Contest Entry:** Enable customers to enter sweepstakes or giveaways

The widget list endpoint returns configured widgets with their specific actions and display settings.

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget List API Reference" icon="code" href="/api-reference/widgets/get-widgets-list">
    View complete API specification
  </Card>

  <Card title="Manual Flow Guide" icon="book-open" href="/integration-options/checkout-integration-app/manual-flow-in-pos-system-checkout-cmc">
    Learn how to implement widget flows
  </Card>

  <Card title="Automated Flow Guide" icon="robot" href="/integration-options/checkout-integration-app/automated-flow-in-pos-system-checkout">
    Trigger widgets automatically based on events
  </Card>

  <Card title="QR Code Generation" icon="qrcode" href="/pos-integration/qr-code-generation">
    Learn about QR code display options
  </Card>
</CardGroup>