Integration Troubleshooting Guide

NetSuite — OAuth authentication fails

Common cause: Token-Based Authentication is not enabled on your integration record, or the Account ID format is wrong.

Fix:

1. In NetSuite, go to Setup → Integration → Manage Integrations

2. Find your Velaro integration record and open it

3. Confirm Token-Based Authentication is checked under Authentication

4. Save the record

Finding your Account ID: It appears in the URL when you are logged in (e.g. https://1234567.app.netsuite.com → Account ID is 1234567). Or go to Setup → Company → Company Information and look for the Account ID field.

After fixing, go to Integrations → NetSuite → Test Connection to confirm.

NetSuite — Customer record access denied

Common cause: The role assigned to your token user is missing the Customers permission.

Fix:

1. Go to Setup → Users/Roles → Manage Roles

2. Find the role assigned to your Velaro token user and open it

3. Click the Permissions tab → Lists subtab

4. Find Customers — add it at View level minimum

5. For full AI write access (update customer records), set it to Create + Edit

6. Save the role

Re-test the connection after saving.

NetSuite — Support case access denied

Common cause: The token user's role is missing the Cases permission under the Support category.

Fix:

1. Go to Setup → Users/Roles → Manage Roles → open the Velaro role

2. Click Permissions → Support subtab

3. Find Cases — set it to Create + Edit level

4. Save the role

The AI skills netsuite_create_case, netsuite_get_cases, netsuite_update_case, and netsuite_add_case_note all require this permission.

NetSuite — Full permission setup (fastest path)

If you're setting up from scratch and want everything working immediately:

1. Go to Setup → Users/Roles → Manage Roles

2. Find the Full Access role → click Save As

3. Name it Velaro Integration → save

4. Assign this role to your Velaro token user

5. All 24 AI skills will work immediately

You can narrow permissions down later once you've confirmed the integration is working end-to-end.

NetSuite — REST Web Services not enabled

Common cause: The REST Web Services permission is missing from the role. This blocks ALL API calls — every request returns 403 even if all other permissions are correct.

Fix:

1. Open the Velaro role in Setup → Users/Roles → Manage Roles

2. Click Permissions → Setup subtab

3. Find REST Web Services → set it to Full

4. Save the role

This is required for every NetSuite API call. If you see 403 errors on all tools, this is the first thing to check.

NetSuite — SuiteQL permission missing

Common cause: AI skills that search orders, customers, and invoices use SuiteQL queries internally. Without this permission, all search and lookup skills fail silently or return empty results.

Fix:

1. Open the Velaro role in Setup → Users/Roles → Manage Roles

2. Click Permissions → Setup subtab

3. Find SuiteQL → set it to Full

4. Save the role

Skills affected: netsuite_search_customer, netsuite_search_orders, netsuite_get_open_invoices, netsuite_search_items, and any skill that searches rather than fetches by ID.

HubSpot — Integration disconnected after time

Common cause: HubSpot OAuth tokens are invalidated when the HubSpot account password changes, or when the Velaro app is revoked in HubSpot's Connected Apps settings.

Fix:

1. Go to Integrations → HubSpot → Disconnect

2. Click Reconnect and re-authorize through HubSpot

3. Test the connection after reconnecting

If the error message says invalid_client, the HubSpot app registration may have been deleted from your HubSpot portal. In that case, contact Velaro support with the error text — this requires re-provisioning the OAuth app on our side.

HubSpot — Missing object permissions

Common cause: The HubSpot user who authorized the connection doesn't have access to all the objects the bot needs (Contacts, Deals, Tickets, Companies).

Fix: The HubSpot user who clicks "Connect HubSpot" must have Super Admin access in HubSpot, or at minimum have object-level access to every object type the bot will use.

1. Go to Integrations → HubSpot → Disconnect

2. Have a HubSpot Super Admin re-authorize the connection

3. Re-test after reconnecting

If only some tools fail (e.g., deal tools work but ticket tools don't), the authorizing user likely has partial access.

Dynamics 365 — Tenant ID or Client ID wrong

Common cause: The Application (client) ID or Directory (tenant) ID was copied from the wrong place in Azure Portal, or has extra spaces.

Fix:

1. Go to Azure Portal → App Registrations

2. Find your Velaro app registration and click it

3. On the Overview page, copy the Application (client) ID and Directory (tenant) ID

4. Both are GUIDs in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

5. Paste them into Integrations → Dynamics 365 and save

Do not copy from App Insights, subscriptions, or resource groups — only the App Registration Overview page has the correct IDs.

Dynamics 365 — Insufficient API permissions

Common cause: The Azure app registration is missing the Dynamics CRM permission, the wrong permission type was selected, or admin consent has not been granted.

Fix:

1. Go to Azure Portal → App Registrations → your app → API Permissions

2. Click Add a permission → APIs my organization uses → search "Dynamics CRM"

3. Select Application permissions (NOT Delegated — Velaro uses client credentials / service-to-service auth)

4. Check user_impersonation → click Add permissions

5. Click Grant admin consent for [your organization] — this requires an Azure AD Global Admin or Application Admin account

6. Confirm the permission shows a green checkmark under "Admin consent required"

Without admin consent, the permission appears in the list but is not active. All API calls will return 401.

Also required — Application User in Dynamics:

The app registration alone is not enough. You must also create an Application User inside Dynamics 365 itself:

1. Go to Power Platform Admin Center → Environments → your environment → Settings → Users + permissions → Application users

2. Click New app user → Add an app → select your Velaro app registration

3. Assign a Security role — see the Dynamics 365 setup guide for the minimum required role

4. Click Create

Without the Application User, auth tokens are issued but Dynamics rejects all API calls with 403.

Shopify — Integration shows disconnected

Common cause: The Velaro app was uninstalled from your Shopify admin, or your Shopify plan changed in a way that revoked third-party app access.

Fix:

1. Go to Integrations → Shopify → Reconnect

2. Follow the OAuth flow to re-install the Velaro app on your Shopify store

3. If prompted, re-approve the requested permissions

If your shop domain changed (e.g., after a store migration), you'll need to disconnect and set up a new connection with the new domain.

Shopify — Specific AI skills return errors (missing permissions)

Unlike BigCommerce where you set scopes manually, Shopify permissions are granted automatically when you install or reconnect the Velaro app via OAuth. If specific skills fail (cancel order, create refund, return, discount creation, inventory, blog articles, etc.) while the connection itself looks healthy, the app was likely installed before those permissions were added.

Skills and the permissions they require:

Skills affected	Required permission
Cancel order, create refund, add order note, update order tags	Write Orders
Create quote, get draft orders, send invoice	Write Draft Orders
Get fulfillment orders	Read Fulfillments
Create fulfillment	Write Fulfillments
Initiate return	Write Returns
Get discount codes	Read Discounts
Create discount, apply coupon, get price rules	Write/Read Price Rules
Gift card lookup	Read Gift Cards
Blog articles, pages	Read Content
Inventory levels, locations	Read Inventory
Shipping zones, delivery profiles	Read Shipping
Markets	Read Markets

Fix — reconnect to grant all permissions:

1. Go to Integrations → Shopify

2. Click Disconnect

3. Click Connect and complete the OAuth flow — Shopify will show the updated permission list

4. Click Install app / Approve — all skills will now work

You will NOT lose your Bot Knowledge, workflow templates, or stored configuration — only the OAuth token is refreshed.

BigCommerce — 401 vs 403 errors explained

BigCommerce distinguishes these two errors differently than most APIs:

• 401 Unauthorized — the Access Token itself is wrong, expired, or revoked. The token is not recognized at all.
• 403 Forbidden — the token is valid but the API account is missing one or more required permission scopes.

If you see a 403 on the connection test or in the Activity Log, your token is fine — you just need to add scopes to the API account in BigCommerce.

Required scopes for Velaro (all 10 must be set — missing any will silently break specific AI skills):

Scope	Minimum level	Used for
Store Information	Read-Only	Connection test — without this, instant 403
Products	Read-Only	Catalog search, categories, brands, variants, inventory, reviews
Customers	Modify	Customer lookup AND create/update (Read-Only breaks create/update skills)
Orders	Read-Only	Order status, history, items, fulfillment
Order Transactions	Read-Only	Payment history
Checkouts	Modify	Cart creation, abandonment recovery, checkout management
Coupons	Read-Only	Discount and coupon lookup
Marketing	Read-Only	Promotions and banners
Fulfillments	Read-Only	Shipment tracking
Content	Modify	Widget install on your storefront

How to fix a 403:

1. Go to BigCommerce Admin → Settings → API → Store-level API accounts

2. Open the API account used for Velaro (or create a new one)

3. Under OAuth Scopes, set all 10 scopes above to the required level

4. Click Save — the existing token stays valid, only the scopes change

5. Go to Integrations → BigCommerce → Test Connection to verify

If you regenerated the token: Go to Integrations → BigCommerce → Accounts, click Update Token next to your store, and paste the new token. Your bot configuration is preserved — no need to disconnect.

BigCommerce / WooCommerce / Magento — API key errors

Common cause: The API key or access token was regenerated in the platform admin, invalidating the one saved in Velaro.

BigCommerce fix:

1. Go to BigCommerce Admin → Settings → API → Store-level API accounts

2. Open your Velaro API account (or click Create API account → Create V2/V3 API token)

3. Set all 10 required scopes: Store Information (Read-Only), Products (Read-Only), Customers (Modify), Orders (Read-Only), Order Transactions (Read-Only), Checkouts (Modify), Coupons (Read-Only), Marketing (Read-Only), Fulfillments (Read-Only), Content (Modify)

4. Save — copy the new Access Token (shown only once)

5. Go to Integrations → BigCommerce → Accounts → click Update Token → paste the new token (no full disconnect needed)

WooCommerce fix:

1. Go to WordPress Admin → WooCommerce → Settings → Advanced → REST API

2. Click Revoke on the old key, then Add Key → set Read/Write → Generate

3. Copy the Consumer Key and Consumer Secret into Integrations → WooCommerce

Magento fix:

1. Go to Magento Admin → System → Integrations

2. Find the Velaro integration → click Reauthorize

3. Copy the new Access Token into Integrations → Magento

How to check integration errors

Every integration logs its API activity. To see what went wrong:

1. Go to Integrations → [your integration] → Activity Log tab

2. Look for entries marked Error (shown in red)

3. The Message column shows the error type; the Detail column shows the raw response from the remote system

Common error patterns:

• 401 Unauthorized — credentials are wrong or expired; reconnect or re-enter API keys
• 403 Forbidden — credentials are valid but the user/role lacks permission for that operation
• 404 Not Found — the record doesn't exist in the remote system, or the URL/domain is wrong
• 429 Too Many Requests — Velaro is being rate-limited by the remote API; this resolves automatically

Click-to-Call: Calls Not Going Through

Symptoms: Visitor submits the widget but no call is received.

Common causes:

1. Velaro-hosted Twilio not configured — Check that your plan includes CTC minutes and your account isn't suspended.

2. BYOK credentials invalid — Go to Settings → Click-to-Call → Overview. Re-enter your Twilio Account SID and Auth Token. Check that the from-number is a verified Twilio voice number in E.164 format (+12125550100).

3. No teams enabled — Go to Teams tab and enable at least one team for Click-to-Call.

4. No agents available — Agents must be in Available status and have AvailableForCalls enabled in their voice settings.

Test: Submit a CTC request from your own phone. Check the Live Queue tab to confirm the request appears.

Click-to-Call: Calls Ring But Agent Hears Nothing

Cause: The visitor answered but the bridge didn't connect.

Fix: This usually means the conference bridge URL is unreachable. Check that the Velaro messaging API URL is correctly configured in App Settings (MessagingApiBaseUrl).

Click-to-Call: Status Stuck at "Ringing"

Cause: Twilio status webhooks aren't reaching the server.

Fix: Verify that your Twilio account has the status callback URL set to: https://[your-messaging-api]/api/ClickToCall/twilio-status. This is configured automatically when using Velaro-hosted Twilio.

Click-to-Call: Abuse Rejection Message

Symptoms: Visitor gets "Too many requests" error immediately.

Cause: Rate limit exceeded (default: 3 requests/hour per number, 50/hour per site).

Fix: Go to Settings → Click-to-Call → Limits & Hours to adjust the rate limits. For testing, temporarily increase the per-caller limit.

After fixing — how to test your connection

After fixing permissions, rotating API keys, or reconnecting OAuth:

1. Go to Integrations → [your integration]

2. Click Test Connection

3. Green checkmarks confirm each access level is working

4. Red items show exactly what still needs to be fixed — the label names the specific permission or scope that failed

If the test passes but specific bot skills still fail, check the Activity Log for the new error and match it against the patterns above. If the error text isn't covered here, copy it and contact Velaro support — include the full error detail, not just the status code.

Klaviyo: "Invalid API Key" or 401 Error

Cause: The Klaviyo Private API Key is wrong, expired, or has insufficient scope.

Fix:

1. Go to Klaviyo → Settings → API Keys.

2. Make sure you're using a Private API Key (not a Public Key — those start with pk_).

3. The key must have Full Access or at minimum: Profiles (read/write), Lists (read/write), Events (write).

4. Paste the new key in Integrations → Klaviyo and click Test Connection.

Klaviyo: "Profile not found" when looking up a contact

Cause: The contact's email doesn't exist in Klaviyo yet, or the klaviyo_get_profile skill was called before the profile was created.

Fix: Use klaviyo_track_event first — Klaviyo creates a profile automatically when the first event is tracked. Then klaviyo_get_profile will find them.

Uplisting: "Authentication failed" or 403 Error

Cause: The Uplisting API key is invalid, expired, or the connected account doesn't have API access.

Fix:

1. Go to Uplisting → Settings → API and regenerate the API key.

2. Paste the new key in Integrations → Uplisting and click Test Connection.

3. Make sure your Uplisting plan includes API access (Growth plan and above).

Guesty: OAuth Token Expired

Cause: Guesty access tokens expire after 24 hours. The refresh token may also have expired (30 days of inactivity).

Fix:

1. Go to Integrations → Guesty and click Reconnect.

2. Re-authenticate with your Guesty credentials.

3. After reconnecting, click Test Connection to verify all scopes are granted.

Cloudbeds: "Insufficient Permissions" on Billing Tools

Cause: The Cloudbeds OAuth application doesn't have the financials scope.

Fix:

1. Go to Integrations → Cloudbeds and click Reconnect.

2. On the Cloudbeds permissions screen, ensure Financials is checked (alongside Reservations, Guests, Rooms).

3. If you manage multiple properties, confirm the OAuth grant covers all properties you want the bot to access.

get_agent_availability: Returns "unavailable" but agents are online

Cause: Agents may be online but their LicenseStatus is not Active, or they are in a non-connectable state.

Fix: Check Account → Agents to confirm the agents have active licenses and their status shows as Available (not Busy or Away). If the skill consistently returns "unavailable" despite active agents, check the Activity Log for DB errors — the skill degrades gracefully and may be returning the safe fallback.

CRM Sync: "Contact has no email or phone — cannot sync"

Cause: The conversation contact record has neither an email address nor a phone number. Sync requires at least one to perform a CRM lookup.

Fix: Collect email or phone during the conversation (bot or agent) so the contact record is populated before sync runs. Check Conversations → Contact panel to confirm the field is populated.

CRM Sync: Sync button does nothing / returns error

Cause: Integration credentials have expired, or the CRM user account behind the integration lacks write permissions.

Fix:

1. Go to Integrations → [HubSpot or Dynamics] and click Test Connection.

2. If the test fails, reconnect or re-enter API credentials.

3. For HubSpot: the connected user needs CRM contacts write scope.

4. For Dynamics: the connected service account needs the Contact and Lead entity create/update permissions.

CRM Sync: Duplicate records in Dynamics after bot chat

Cause: The bot created a Lead mid-conversation (via the create_lead skill), then the post-chat sync ran and created a second Lead because it only searched Contacts.

Status: Fixed. The sync pipeline now searches both Contacts and Leads before creating. If a matching Lead already exists, it returns existing_lead and does not create a duplicate.

If you see duplicates in an existing account: manually merge them in Dynamics. Going forward, duplicates will not be created.

CRM Sync: Conflict review panel not showing

Cause: Conflicts are only shown if both the CRM value and the incoming chat value are non-empty and different. If either is blank, the safe value is written automatically with no conflict queued.

To check: In the conversation, open the HubSpot or Dynamics sidebar panel → Contact tab. If the amber panel does not appear, either there are no conflicts or the previous conflicts were already approved/discarded. The panel only shows pending items.

CRM Sync: Approved conflict not appearing in CRM

Cause: The CRM write failed after approval — usually a permissions error or the CRM record was deleted between sync and approval.

Fix:

1. Click Sync → again to re-run the full sync.

2. Check Activity Log → Integrations for the specific field write error.

3. Verify the CRM record still exists and the integration credentials have write access.

Pipedrive: "Pipedrive is not configured for this site"

Cause: The Pipedrive integration is not connected or has been disabled.

Fix:

1. Go to Integrations → Pipedrive.

2. Enter your Pipedrive API token (found in Pipedrive → Personal Preferences → API).

3. Toggle Enable and click Save.

4. Test: ask the bot "Find a contact in Pipedrive" — if it returns results or "no contact found," the connection is working.

Pipedrive: Bot returns "Pipedrive person search could not be completed"

Cause: API token is invalid or expired, or the Pipedrive account is on a plan that restricts API access.

Fix:

1. Go to Integrations → Pipedrive → Edit and re-enter a fresh API token.

2. Confirm the Pipedrive user account is active (not suspended or downgraded to a plan without API access).

3. Check Activity Log → Integrations for the HTTP status code — 401 = bad token, 403 = plan restriction.

QuickBooks Online: "QuickBooks is not configured for this site"

Cause: The OAuth connection has not been completed or the token has expired and cannot be refreshed.

Fix:

1. Go to Integrations → QuickBooks → Connect QuickBooks Online.

2. Complete the OAuth authorization flow in your Intuit account.

3. If the connection was previously active but stopped working, click Disconnect then reconnect — this forces a fresh token pair.

Note: QuickBooks access tokens expire after 1 hour; refresh tokens expire after 100 days. If the site was inactive for more than 100 days, a full reconnect is required.

QuickBooks Online: Bot cannot find a customer

Cause: The customer name in QuickBooks may differ from the name used in the chat. QuickBooks search is case-insensitive but requires an exact substring match.

Fix: Ask the customer to provide the name or email address exactly as it appears on their QuickBooks invoices. The bot will retry the search automatically.

Zoho CRM: "Zoho CRM is not configured for this site"

Cause: The OAuth authorization has not been completed or the access token expired.

Fix:

1. Go to Integrations → Zoho CRM → Connect Zoho CRM.

2. Select the correct data center region (US = zohoapis.com, EU = zohoapis.eu, etc.).

3. Complete the OAuth authorization.

4. If previously connected, disconnect and reconnect to generate a fresh token.

Zoho CRM: Bot returns "Zoho contact/lead search could not be completed"

Cause: Usually an invalid or expired access token, or the Zoho user account lacks the required module permissions.

Required Zoho CRM permissions:

• ZohoCRM.modules.contacts.READ and .WRITE
• ZohoCRM.modules.leads.READ and .WRITE
• ZohoCRM.modules.deals.READ
• ZohoCRM.modules.accounts.READ
• ZohoCRM.modules.notes.WRITE

Fix: In Zoho CRM, go to Setup → Developer Hub → Connected Apps and verify the Velaro app has all required scopes. Reconnect if scopes are missing.

Toast POS: "Toast POS is not configured for this site"

Cause: Toast Client ID, Client Secret, or Restaurant GUID has not been saved, or the credentials are invalid.

Fix:

1. Go to Integrations → Toast POS.

2. Enter the Client ID and Client Secret from Toast Developer Portal → Your App → Credentials.

3. Enter the Restaurant GUID (found in Toast Web → Restaurant Settings → General → GUID).

4. Click Save. The bot fetches a token automatically on first use.

Toast POS: Bot cannot retrieve menu or hours

Cause: The Toast credentials are valid but the restaurant GUID is wrong, or the Toast account is in a sandbox environment that does not return live data.

Fix:

1. Verify the Restaurant GUID in Toast Web → Restaurant Settings matches what was entered in Velaro.

2. Check Activity Log → Integrations — a 404 usually means a wrong GUID; a 401 means the client credentials are invalid.

3. Ensure the Toast app credentials have restaurants:read and menus:read scopes enabled in the Toast Developer Portal.

Toast POS: Dietary tag search returns no results

Cause: Menu items in Toast do not have dietary tags or properties set, or the tag name used by the guest doesn't match the labels in Toast.

Fix:

1. In the Toast menu editor, open each relevant menu item and add dietary properties (vegan, gluten-free, vegetarian, dairy-free, etc.) under the item's Tags or Dietary Properties section.

2. The bot matches on partial strings — "gluten" will match "gluten-free" — but the tags must exist in Toast first.

3. After updating Toast, the bot picks up the new tags on the next API call (no restart required).

Toast POS: Modifier lookup returns no options

Cause: The menu item does not have modifier groups attached in Toast, or the item name provided doesn't match any item in the menu.

Fix:

1. In the Toast menu editor, open the item and verify it has modifier groups assigned.

2. If the item name is slightly different from what the guest typed, the bot may not find the item. Encourage guests to use the exact name as shown on the menu.

3. Test with toast_get_menu_item first to confirm the item exists by name before troubleshooting modifiers.

Toast POS: Shift info returns 403 or no data

Cause: The toast_get_shift_info tool requires the Toast Labor API scope (labor:read), which is not included in standard menu-only API credentials.

Fix:

1. In the Toast Developer Portal, open your app credentials.

2. Add the labor:read scope to the credential set.

3. Save and re-enter the credentials in Velaro Integrations → Toast POS.

4. Verify by asking the bot "Who is working right now?" — if it returns shift data, the scope is active.

Toast POS: Table order lookup returns "No open orders"

Cause: Either no active order exists for that table, or the table name/number format used by the guest doesn't match Toast's table naming convention.

Fix:

1. In Toast, check what the table is named (e.g., "Table 5" vs "5" vs "T5"). The bot matches on the exact string.

2. Test with a table that has an active open order to confirm the integration is working.

3. Table orders are only available for dine-in orders with an open check — closed/paid orders won't appear.

Mindbody: "Mindbody is not configured for this site"

Cause: The Mindbody API key and/or Mindbody Site ID have not been saved, or the integration is disabled.

Fix:

1. Go to Integrations → Mindbody.

2. Enter the API key (from Mindbody → Manage → Developer Tools → API Keys).

3. Enter the Mindbody Site ID — this is the numeric ID for your studio (visible in your Mindbody login URL or support docs).

4. Toggle Enable and click Save.

Mindbody: "No classes found" or "No client found"

Cause for classes: The date range queried (next 7 days for upcoming, next 30 for search) has no classes scheduled. Check the Mindbody calendar directly to confirm.

Cause for client lookup: The email address provided does not match any Mindbody client record. Mindbody stores the email exactly as entered — one typo returns no results.

Fix: Ask the visitor to confirm the email address used when signing up for Mindbody. The bot will re-search with the corrected address.

Mindbody: Booking fails — "could not complete booking"

Cause: Most common causes: class is full (TotalBooked ≥ MaxCapacity), the class was cancelled, or the client does not have a valid pricing option (membership or class pack) to cover the booking.

Fix:

1. Check Activity Log → Integrations for the HTTP status and Mindbody error detail.

2. If the class is full, the bot should offer to search for other available classes — verify the workflow includes this fallback.

3. If the client has no valid pricing option, they will need to purchase a class pack or membership before booking via chat.

Monday.com: "Invalid token" or "Test Connection fails"

Cause: The Personal API Token is incorrect, expired, or has insufficient permissions.

Fix:

1. Go to your Monday.com profile → Developers → My Access Tokens

2. Copy the token exactly — no extra spaces or line breaks

3. Paste it in Integrations → Monday.com → API Token in Velaro

4. Click Test Connection — if successful, your Monday.com account name and email will appear

5. If your Monday.com account uses IP allowlisting, add the Velaro API server IP to the allowlist

Verify: The Test Connection button returns "Connected as [your name]" with a green checkmark.

Monday.com: Lead capture creates item but email or phone is empty

Cause: The monday_push_lead tool auto-detects email and phone columns by their Monday.com column type. Plain text columns are not detected as email or phone fields.

Fix:

1. Open your lead board in Monday.com

2. Add a column of type Email (not "Text") and a column of type Phone

3. The bot will automatically populate these columns on the next lead creation

Verify: Create a test lead via chat and confirm the item has populated email and phone columns in Monday.com.

Monday.com: "Board not configured" error from monday_push_lead

Cause: No Default Board ID is set in the Monday.com integration settings.

Fix:

1. Open the board you want to receive leads in Monday.com

2. Copy the board ID from the URL: https://app.monday.com/boards/{BOARD_ID}

3. Paste only the numeric ID (e.g., 1234567890) in Integrations → Monday.com → Default Board ID

4. Enable Push Leads to Board and click Save

Verify: Test with monday_push_lead from a bot conversation — a new item should appear on the board within seconds.

Monday.com: Skills not available in bot

Cause: Monday.com Skills are not enabled in the bot's AI settings.

Fix:

1. Go to Bots → [Your Bot] → AI Settings → Integrations

2. Toggle Monday.com Skills to enabled

3. Save and republish the bot

Clover POS: API Token Invalid (401 Unauthorized)

Cause: The Personal Access Token is incorrect, expired, or was generated for a different Clover app or environment.

Fix:

1. Go to clover.com/developers and sign in with your Clover account.

2. Open the app you created for the Velaro integration.

3. Under API Access, look for your existing token — if it shows as expired, click Regenerate Token.

4. Copy the new token and paste it in Integrations → Clover POS → API Token in Velaro.

5. Make sure the token has full merchant-level access — a restricted app-scoped token will return 401 on some calls even if it authenticates.

6. Click Save & Test Connection.

Verify: The Test Connection button returns your merchant name and account details with a green checkmark.

Clover POS: Merchant ID Not Found (404)

Cause: The Merchant ID saved in Velaro does not match your Clover account.

Fix:

1. Log in to your Clover Dashboard at clover.com/dashboard.

2. Click your merchant name in the top-right corner, then go to Account → About This Business.

3. Find the Merchant ID field — it is a 13-character alphanumeric string.

4. Copy it exactly (no extra spaces) and paste it in Integrations → Clover POS → Merchant ID in Velaro.

5. Click Save & Test Connection.

Note: If you manage multiple Clover locations, each location has its own Merchant ID. Make sure you are using the ID for the specific location you want the bot to access.

Verify: After saving the correct Merchant ID, the Test Connection response includes the merchant name and address matching that location.

Clover POS: No Items Returned from Menu Search

Cause: Items are archived, hidden, or not assigned to a category visible via the API.

Fix:

1. Log in to your Clover Dashboard.

2. Go to Inventory → Items.

3. Check the filter at the top — make sure Show Archived is OFF. Archived items are excluded from API responses.

4. For any item that should appear but does not, open it and confirm Hidden is toggled off.

5. If items belong to a hidden category, go to Inventory → Categories, open the category, and confirm it is visible.

After fixing item or category visibility in Clover, the changes are reflected in Velaro immediately — no reconnection is needed.

Verify: Ask the bot "What items do you have?" or use clover_search_items with a broad keyword — the item should now appear in results.

Jobber: API Token Invalid (401 Unauthorized)

Cause: The API token is incorrect, has been revoked, or was regenerated in Jobber since it was saved in Velaro.

Fix:

1. In Jobber, click your company name in the top-right corner.

2. Go to Settings → Connected Apps → API.

3. If your existing token is listed, check whether it shows as revoked or expired. If so, click Generate Token to create a new one.

4. Copy the new token immediately — Jobber only shows it once.

5. Paste it in Integrations → Jobber → API Token in Velaro.

6. Click Save & Test Connection.

Verify: The Test Connection response shows your Jobber company name and account ID with a green checkmark.

Jobber: GraphQL Query Errors

Cause: Jobber's API is GraphQL-based and evolves over time. Field names, types, or query structures can change between API versions, causing queries to fail after a Jobber API update.

Fix:

1. Check the Activity Log → Integrations in Velaro for the specific GraphQL error message — it will name the field or query causing the failure.

2. Review the current Jobber API schema at developer.getjobber.com to confirm field names and types match what Velaro is querying.

3. If the error persists after confirming your token is valid, contact Velaro support with the error detail from the Activity Log — a skill update may be needed to match the current Jobber API schema.

Verify: After a fix is applied, use Test Connection and run a test query via the bot ("Look up my account" or "What jobs do I have scheduled?") to confirm the skill works end-to-end.

Jobber: Create Service Request Failed

Cause: The jobber_create_request skill requires a valid client name and phone number. Invalid phone formats or missing required fields cause the request submission to fail.

Fix:

1. Check the Activity Log → Integrations for the specific validation error from Jobber.

2. Confirm the bot workflow collects and passes all required fields: first name, last name, and phone number.

3. Phone numbers must be in a standard format (e.g., (555) 867-5309 or +15558675309). If your bot stores phone in a non-standard format, add a normalization step before the skill call.

4. If a client name was not collected (the visitor skipped the question), add a required validation step in the workflow before calling jobber_create_request.

Verify: Submit a test service request through the bot using a real name and a valid phone number. Confirm the new Request appears in your Jobber inbox within seconds.

Verify: Ask the bot "search my Monday boards for [keyword]" — it should execute the search and return results.

SAP: 401 Unauthorized on Service Layer

Cause: Invalid credentials, expired session, or the SAP Business One Service Layer user account is locked.

Fix:

1. Verify the username and password in Integrations → SAP → Edit.

2. Log in to the SAP Business One client directly with the same credentials to confirm the account is not locked.

3. Confirm the Service Layer URL includes the correct port (default: https://yourserver:50000).

4. Check that the Service Layer is running: https://yourserver:50000/b1s/v1/$metadata should return XML.

Verify: Save the connection and ask the bot to "look up a customer" — it should return SAP data without a 401 error.

SAP: Connection Refused / Timeout

Cause: The SAP server URL is unreachable from the internet, or the Service Layer port is blocked by a firewall.

Fix:

1. Confirm the SAP server URL in Integrations → SAP includes the correct protocol and port (https://yourserver:50000).

2. Check that the firewall/NAT allows inbound connections from Velaro's IP range to port 50000.

3. If SAP is on a private network, you'll need a VPN tunnel or reverse proxy to expose the Service Layer.

Verify: The Activity Log should show successful authentication with no connection timeout errors.

SAP: Empty Results on Business Partner Search

Cause: The company DB name is wrong, or the SAP user lacks read access to business partner records.

Fix:

1. Confirm the Company DB in Velaro matches your SAP database name exactly (it is case-sensitive).

2. In SAP Business One, check that the Service Layer user has at least Read access to Business Partners (BP module).

3. Try the Service Layer endpoint directly: GET /b1s/v1/BusinessPartners?$filter=startswith(CardName,'Test')&$top=1.

Verify: Ask the bot to search for a known customer name — it should return the matching SAP record.

SAP: Create Sales Order / Service Call Fails

Cause: Missing required fields, or the SAP user lacks Write access to the relevant module.

Fix:

1. Check the Activity Log → Integrations for the specific SAP error message (SAP returns structured errors with a message and code).

2. For sales orders: confirm all item codes exist in the SAP item master and that the business partner CardCode is correct.

3. For service calls: confirm the SAP user has Write access to the Service module.

4. If the error is "No matching records found" for an item code, use sap_search_items first to verify the exact code.

Verify: Create a test order or service call through the bot and confirm it appears in SAP Business One.