Clover POS Integration for ElevenLabs Agents

Overview

This integration enables ElevenLabs voice agents to interact with Clover POS systems for restaurant and retail order management. Agents can create orders, search menu items, and manage transactions through voice interactions.

Prerequisites

• Active Clover merchant account
• Clover API credentials
• TriLuna admin access to enable the integration

Setup Instructions

1. Obtain Clover API Credentials

For Production Environment:

1. Log into your Clover Dashboard
2. Navigate to Account & Setup → API Tokens
3. Click Create New Token
4. Set appropriate permissions:
   • Orders: Read and Write
   • Inventory: Read
   • Merchants: Read
   • Payments: Read and Write (if payment processing needed)
5. Copy the generated API token
6. Note your Merchant ID from the dashboard URL

For Sandbox Testing:

1. Create a Clover Developer Account
2. Create a test merchant
3. Generate a sandbox API token
4. Use sandbox credentials for testing

2. Configure in TriLuna Admin Panel

1. Navigate to the admin user page: https://triluna.app/admin/users/{userId}
2. Find the Clover POS Integration section
3. Click Enable Clover POS
4. Enter your credentials:
   • Merchant ID: Your Clover merchant identifier
   • API Token: The token generated in step 1
   • Environment: Select “Production” or “Sandbox”
   • Webhook Secret (optional): For secure webhook verification
5. Click Test Connection to verify credentials
6. Click Save Configuration

3. Enable for Specific Agents

1. In the admin panel, go to the agent management section
2. Select the agent you want to enable Clover for
3. Toggle Enable Clover POS to ON
4. Save the agent configuration

4. Configure Agent Tool in ElevenLabs

In your ElevenLabs agent settings, add the Clover webhook tool:

Tool Name: clover_pos_tool Method: POST URL: https://api.triluna.app/api/clover/webhook Headers: Content-Type: application/json Description: Process orders and interact with Clover POS system

Available Actions

1. Create Order

Creates a new order with line items in Clover POS.

{
  "request": "{
    \"action\": \"create_order\",
    \"agent_id\": \"your_agent_id\",
    \"items\": [
      {
        \"itemId\": \"XXXXX\",
        \"name\": \"Burger\",
        \"price\": 12.99,
        \"quantity\": 2,
        \"modifications\": [
          {\"name\": \"Extra Cheese\", \"amount\": 1.50}
        ]
      }
    ],
    \"customer_name\": \"John Doe\",
    \"customer_phone\": \"+1234567890\",
    \"note\": \"No onions please\"
  }"
}

2. Search Menu Items

Search for items in the inventory by name.

{
  "request": "{
    \"action\": \"search_items\",
    \"agent_id\": \"your_agent_id\",
    \"query\": \"burger\"
  }"
}

3. Get Menu

Retrieve the full menu/inventory list.

{
  "request": "{
    \"action\": \"get_menu\",
    \"agent_id\": \"your_agent_id\"
  }"
}

4. Get Order Details

Retrieve details of a specific order.

{
  "request": "{
    \"action\": \"get_order\",
    \"agent_id\": \"your_agent_id\",
    \"order_id\": \"ORDER_ID_HERE\"
  }"
}

5. Update Order Status

Change the status of an order (e.g., mark as paid, void, etc.).

{
  "request": "{
    \"action\": \"update_order_status\",
    \"agent_id\": \"your_agent_id\",
    \"order_id\": \"ORDER_ID_HERE\",
    \"status\": \"locked\"
  }"
}

6. Add Item to Existing Order

Add additional items to an already created order.

{
  "request": "{
    \"action\": \"add_item_to_order\",
    \"agent_id\": \"your_agent_id\",
    \"order_id\": \"ORDER_ID_HERE\",
    \"item\": {
      \"itemId\": \"ITEM_ID\",
      \"name\": \"Fries\",
      \"price\": 4.99,
      \"quantity\": 1
    }
  }"
}

7. Calculate Order Total

Get the total with tax for an order.

{
  "request": "{
    \"action\": \"calculate_total\",
    \"agent_id\": \"your_agent_id\",
    \"order_id\": \"ORDER_ID_HERE\"
  }"
}

Agent Prompt Configuration

To effectively use Clover POS in your voice agent, add these instructions to your agent’s prompt:

You have access to a Clover POS system for processing orders. When a customer wants to place an order:

1. Use search_items to find menu items by name
2. Confirm the items, quantities, and any modifications with the customer
3. Ask for the customer's name for the order
4. Use create_order to submit the order to Clover
5. Provide the order ID to the customer for reference

Available actions:
- search_items: Find menu items
- get_menu: List all available items
- create_order: Submit a new order
- get_order: Check order status
- add_item_to_order: Add items to existing order
- calculate_total: Get order total with tax

Always confirm the total price with the customer before finalizing the order.

Order Flow Example

Here’s a typical conversation flow:

1. Customer: “I’d like to order a cheeseburger with extra pickles”
2. Agent: Uses search_items with query “burger”
3. Agent: “I found our Cheeseburger for $12.99. I’ll add extra pickles. What else would you like?”
4. Customer: “Add large fries and a coke”
5. Agent: Searches for items and builds order
6. Agent: “Your order: 1 Cheeseburger with extra pickles, 1 Large Fries, 1 Coke. Total is $21.47. May I have your name?”
7. Customer: “John Smith”
8. Agent: Uses create_order to submit
9. Agent: “Perfect! Your order #ABC123 has been placed. It will be ready in 15 minutes.”

Webhook Events (Coming Soon)

Clover can send real-time updates to your system:

• Order created
• Order modified
• Payment processed
• Order completed

Configure webhook URL in Clover: https://api.triluna.app/api/clover/events

Security Considerations

• API tokens are encrypted at rest in the database
• Use webhook secrets to verify incoming requests from Clover
• Limit API permissions to only what’s needed
• Use sandbox environment for testing
• Regular audit of API access logs

Troubleshooting

Connection Failed

• Verify API token is valid and not expired
• Check merchant ID is correct
• Ensure proper environment (sandbox vs production) is selected

Items Not Found

• Verify items exist in Clover inventory
• Check that items are not hidden or out of stock
• Ensure item IDs match exactly

Order Creation Failed

• Check all required fields are provided
• Verify prices are in correct format (dollars, not cents)
• Ensure customer has necessary permissions

Permission Errors

• Verify API token has required permissions
• Check merchant account is active
• Ensure integration is enabled for the agent

API Limits

• Clover API rate limit: 16 requests per second
• Maximum items per order: 100
• Webhook timeout: 30 seconds

Support

For integration issues:

• TriLuna Support: support@triluna.app
• Clover Support: Clover Help Center

Additional Resources

• Clover API Documentation
• Clover Developer Dashboard
• Webhook Configuration Guide