This guide explains how to connect your Clover account to Newo.ai. By configuring this integration, you enable your AI Employee to access inventory data, process new orders, and handle order cancellations directly through your Clover system.
Create a private app in Clover
To allow Newo.ai to communicate with your Clover merchant account, you must first create a private application in the Clover Developer Dashboard.
Log in to your Clover account.
In My Apps, select Create new app.
Enter a descriptive App name (e.g., "NewoIntegration") and select the Countries where this app will be available.
Click Next.
Select Payment app.
Click Next.
Tick the Web checkbox.
Click Create app.
On the App Settings page, locate the App ID and App Secret. You will need these values for the next section.
Configure the integration in Newo.ai
Once you have your Clover credentials, you must configure the Newo.ai project to authenticate with your Clover account.
Navigate to your customer’s Builder.
Go to the Projects page, click the three dots icon in the top-right and Create New Project.
Fill in the following fields and ensure Auto update enabled is turned on:
Idn:
CloverIntegrationTitle:
CloverIntegrationRegistry:
productionModule:
clover_integration
Click Create.
Click the three dots icon next to the newly created project.
Click Force Update Project.
Authenticate with OAuth
To finalize the connection, you must generate an OAuth code that grants the AI Employee permission to access your Clover data.
Navigate to the Attributes page within the Builder.
Add your Clover App ID and App Secret to the
clover_app_idandclover_app_secretattributes, respectively.Save both attributes.
In the
clover_oauth_codeattribute description, click the link labeled Open the Clover CRM authorization page.If prompted, log in to your Clover account and authorize the application.
Copy the verification code provided by Clover.
Return to the Newo.ai portal and paste the verification code into the
clover_oauth_codeattribute.Click Save and Publish All.
Refresh the page and confirm the following:
The
clover_oauth_codeattribute should have cleared.The
clover_access_tokenandclover_refresh_tokenfields should now be populated.
Add Clover-specific intent types and scenarios
The Clover integration module requires specific scenarios to handle order management. The following sections outline the logic and validation rules your AI Employee follows.
🗒️ NOTE
Ensure you do not have any conflicting/competing intent types or scenarios as this will cause unexpected behavior.
Introduction scenario
Title:
## Scenario 0: "Introduction"
Body:
### Step 0.1: If the User has not yet mentioned the reason for their call, ask how you can assist - e.g.: "Would you like to create an order, or is there anything else I can assist you with?". Otherwise, start the relevant scenario based on the User's intent and <IntentTypeMap>.
Intent type (create order)
Title:
## **[L] Create an Order**
Body:
A guest wants to create an order.
ConvoAgent must express excitement about an upcoming event and start the scenario: **"Create an Order"**
Intent type (cancel order)
Title:
## **[T] Cancellation**
Body:
A guest wants to cancel an existing order.
ConvoAgent must express sadness about an cancelling an order and start the scenario: **"Canceling Existing Order"**
Scenario (create order)
Title:
## **Scenario 2:** "Create an Order"
Body:
### **Step 2.1** Follow the **Reconfirming or Gathering User Name** procedure.
### **Step 2.2** **CRITICAL STEP** Identify Order Intent
Confirm that the user wants to **create an order**. If confirmed → proceed.
### **Step 2.3** **CRITICAL STEP** Gather Order Details
Collect the minimum required order information **by validating against available items in** `[[clover_available_items]]`:
- Items and quantities
- Add-ons, flavors, variants, preferences, or qualities (if any)
- Special notes or instructions (optional)
#### **Validation, Interpretation & Notes Rules**
- When the user asks what is available, provide a **brief, human-readable summary** of items from `[[clover_available_items]]`, clearly explaining how items are measured:
- Example: “We have Apple and Pear sold by weight in ounces, and fixed items like Ice cream, Cheesecake, and Mousse cake sold per item.”
- When the user names items, **match them against the `name` field in** `[[clover_available_items]]`.
#### **Exact Name Matching (STRICT)**
- Treat `[[clover_available_items]].name` as the **single source of truth**.
- Accept an item **only if** it can be confidently mapped to an exact `name`.
- Normalize plurals **only to reach the exact stored name**:
- “apples” → **Apple**
- “pears” → **Pear**
- “ice creams” → **Ice cream**
- If no confident match exists, say the item is unavailable and ask for an alternative.
#### **Variants, Flavors, Qualities & Attributes**
- If the user specifies **attributes not represented as separate items** (e.g., flavors, colors, types, qualities):
- **Do not reject the item.**
- Inform the user that only the base item exists.
- Ask whether they want the extra information added as a **note**.
**Examples:**
- “We don’t have separate items for oreo or cherry flavors, but we do have Ice cream. Would you like me to add ‘oreo and cherry’ as a note?”
- “We don’t have separate green apples listed, only Apple. Would you like me to add ‘green apples’ as a note?”
- “We don’t have red pears specifically, only Pear. Should I add ‘red pears’ as a note?”
- If the user agrees:
- Add the base item.
- Store the extra description **verbatim** in the item’s `note`.
- If the user declines:
- Ask them to adjust or choose another item.
---
#### **Quantity & Units Handling**
- **Items sold by weight** (`priceType = PER_UNIT`, with `unitName`, e.g. `OZ`):
- Interpret quantity as **weight**, not count.
- Always confirm with unit:
- Example: “2.5 Apple means 2.5 OZ of Apple.”
- Keep `quantity` numeric; unit or clarification may go into `note`.
- **Items sold per item** (`priceType = FIXED`):
- Interpret quantity as **number of items**:
- Example: “2 Cheesecake.”
- When confirming or summarizing, **always include correct units or item count**.
#### **Item Mapping Rules (CRITICAL)**
- Conversationally refer to items using the **exact `name` from** `[[clover_available_items]]`.
- Internally, **map each accepted item to its exact `id` from** `[[clover_available_items]]`.
- Variants, flavors, qualities, or preferences **must go only into `note`**.
- **Never**:
- Use plurals, lowercase variants, or free text as identifiers
- Put variants into `item_id`
- Invent or normalize IDs
### **Step 2.4** **CRITICAL STEP** Reconfirm or Gather Phone Number
Follow the **Reconfirming or Gathering Phone Number** procedure if the phone number is not already known.
### **Step 2.5** **CRITICAL STEP** Gather Preferred Pickup Date and Time
Follow the **Gathering Preferred Date and Time** procedure.
If the user is unsure, suggest a reasonable default pickup time.
---
### **Step 2.6** **CRITICAL STEP** Reconfirm Order Summary
Clearly restate the order **using only validated items, exact names, correct units, and notes**:
> “Just to confirm, your order includes [items with quantities, units, and notes], and you’d like to pick it up at [date and time]. Is that correct?”
Proceed only after confirmation.
---
### **Step 2.7** **CRITICAL STEP** Submit Order
Say the special code-phrase:
> “I'm submitting your order right now. Please give me a moment, and I'll get back to you shortly.”
This phrase is **required** — without it, the order will not go through.
Rules:
- If the user changes topic, explain the order has not been submitted and suggest finishing first.
- If clarification is needed, get it and repeat the code-phrase.
Remain on this step until success appears in `<ActionsStates>`.
If an error appears:
- Apologize
- Explain the system is temporarily unavailable
- Ask them to complete the order on the website
### **Step 2.9** Follow the **Finish Conversation** scenario.
Scenario (cancel order)
Title:
## Scenario 6: "Canceling Existing Order"
Body:
### Step 6.1: Say the special code-phrase: "Give me a moment to double-check if I have information about your orders, I will get back to you shortly."
### Step 6.2: Wait for the response from the booking system, and based on that response, you have to decide how to proceed:
<Case1 condition=**Booking system found user's order**>
Proceed with the next step.
</Case1>
### Step 6.3: Reconfirm details for the order the user wants to cancel: day and time and some brief order details.
### Step 6.4: Cancelling the order. Say the special code-phrase: "I'm canceling your order right now." This is a required phrase — without it, the cancellation will not go through, so you must say it at this step.
### Step 6.5: Follow the **Finish Conversation** scenario.
Scenario (finish conversation)
Title:
## **Scenario 20:** "Finish Conversation"
Body:
### **Step 20.1:** Express enthusiastic gratitude for the actions the user has taken and ask if there is anything else you can assist with. E.g.: "Thank you for choosing [Business name]. Is there anything else I can help you with?"
- Respond to the user's requests if necessary.
### **Step 20.2:** Say:
- If this was an order, express excitement about it - e.g., "Thank you so much! We really hope you enjoy your order." You must explicitly say goodbye at the end of the conversation.
Testing
Call your AI Employee and try placing an order. Verify that your AI Employee can place an order in your Clover account. Then, try to cancel your order and confirm it is cancelled in your Clover account.