Skip to main content

Flic Button Integration Guide

This guide explains how to connect a Flic button to the Attendant API and test the webhook endpoint.

Overview​

The Flic integration allows Flic buttons to trigger task creation in the Attendant API. When a Flic button is pressed, it sends a JWT-signed webhook request to the API, which creates a task.

Endpoint Details​

Production:

POST https://attendant-api-v2.retailsvc-test.com/api/v1/tasks/integrations/vendors/flic

Query Parameters:

  • tenantId (required) - Your tenant ID
  • businessUnitId (required) - Your business unit ID

Request Body:

{
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The token is a JWT signed by Flic with ES256 algorithm containing button information.

Setting Up a Flic Button​

1. Connect Your Flic Button​

  1. Download the Flic app on your mobile device (iOS or Android)
  2. Open the Flic app and follow the setup instructions to pair your Flic button
  3. Ensure your button is connected and working

2. Configure the Button in Flic Device Manager​

  1. Go to Flic Device Manager
  2. Select your button or create a button group
  3. Add the following metadata fields as a JSON string:
{
  "__fcb_action": "CLOUD_LOCATION",
  "__fcb_icon": "https://flic-device-manager.s3.amazonaws.com/icons/5XlT9Gc9JT",
  "__fcb_webhook": "https://attendant-api-v2.retailsvc-test.com/api/v1/tasks/integrations/vendors/flic?tenantId=YOUR_TENANT_ID&businessUnitId=YOUR_BUSINESS_UNIT_ID",
  "__fcb_webview": "https://your-webview-url.com",
  "__fcb_name": "Attendant Task Button"
}

Field Descriptions:

  • __fcb_action: Set to "CLOUD_LOCATION" to include geolocation data, or "CLOUD" without location
  • __fcb_icon: URL to a PNG image (max 512x512px) for the button icon
  • __fcb_webhook: The webhook URL that will receive button press events
  • __fcb_webview: URL to a webpage displayed when tapping the button in the app
  • __fcb_name: Optional custom name for the button

Important: Replace YOUR_TENANT_ID and YOUR_BUSINESS_UNIT_ID with your actual values.

3. Verify Button Configuration​

After saving the metadata:

  1. The button should appear in your Flic app with the custom icon
  2. The button should be recognized as a "Cloud Button"
  3. Pressing the button will trigger the webhook

Testing the Endpoint​

Method 1: Using the Flic Button​

  1. Press your configured Flic button
  2. The button will send a webhook request to the endpoint
  3. Check the API logs to verify the request was received
  4. A task should be created in the system

Method 2: Using curl (Manual Testing)​

You can manually test the endpoint using curl:

curl -X POST "https://attendant-api-v2.retailsvc-test.com/api/v1/tasks/integrations/vendors/flic?tenantId=YOUR_TENANT_ID&businessUnitId=YOUR_BUSINESS_UNIT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_JWT_TOKEN_HERE"
  }'

Note: You'll need a valid JWT token signed by Flic. The token must be generated by a real Flic button press or signed with Flic's private key.

Example Response:

{
  "status": "ok",
  "info": {},
  "error": {},
  "details": {}
}

Success Response:

  • Status: 200 OK
  • Body: { "message": "Task created" }
  • Header: Task-Id - Contains the UUID of the created task

JWT Token Structure​

The JWT token contains the following payload:

{
  "exp": 1769666776,
  "buttonUuid": "d6ba41a53ba14f319c51cd53d72d9a79",
  "buttonSerialNumber": "BJ42-G52285",
  "buttonName": "BJ42-G52285",
  "buttonBatteryStatus": "high",
  "pressedAt": "2026-01-29T07:06:16+02:00",
  "clickType": "click"
}

Fields:

  • exp: Token expiration timestamp
  • buttonUuid: Unique identifier for the button
  • buttonSerialNumber: Serial number of the button
  • buttonName: Name of the button
  • buttonBatteryStatus: Battery level (unknown, low, medium, or high)
  • pressedAt: ISO 8601 timestamp when the button was pressed
  • clickType: Type of click (click, double_click, or hold)

Authentication​

The endpoint uses JWT signature verification to authenticate requests:

  1. The token must be signed with ES256 algorithm
  2. The signature must match the configured Flic production public key

Troubleshooting​

401 Unauthorized Error​

Problem: The JWT signature doesn't match any configured public keys.

Solutions:

  1. Verify the token is signed by Flic
  2. Check that your tenant ID is correct
  3. Ensure the token hasn't expired

400 Bad Request Error​

Problem: The JWT payload is missing required fields or has invalid format.

Check:

  • All required fields are present: buttonUuid, buttonSerialNumber, buttonBatteryStatus, clickType, pressedAt
  • pressedAt is in ISO 8601 format
  • Token hasn't expired (check exp field)

Button Not Triggering Webhook​

Check:

  1. Button is connected and paired in the Flic app
  2. Metadata is correctly configured in Flic Device Manager
  3. Webhook URL is correct and accessible
  4. Button is recognized as a "Cloud Button" in the app
  5. Check Flic app logs for any errors

Task Not Created​

Check:

  1. API logs show the webhook was received
  2. JWT validation passed (validSignature: true in logs)
  3. Database connection is working
  4. Check for any errors in the task creation process

Logs​

The service logs the following information when a webhook is received:

{
  "message": "Flic webhook triggered",
  "tenantId": "CIR7nQwtS0rA6t0S6ejd",
  "businessUnitId": "123",
  "validSignature": true,
  "decodedToken": {
    "header": { "alg": "ES256", "typ": "JWT" },
    "payload": { ... }
  }
}

Check the logs to verify:

  • validSignature is true
  • Token payload contains expected fields
  • No errors occurred during processing

References​

Support​

If you encounter issues:

  1. Check the API logs for detailed error messages
  2. Verify your button configuration in Flic Device Manager
  3. Ensure your tenant ID and business unit ID are correct
  4. Contact your team lead or check internal documentation