Integration Troubleshooting Guide
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 keys403 Forbidden— credentials are valid but the user/role lacks permission for that operation404 Not Found— the record doesn't exist in the remote system, or the URL/domain is wrong429 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.READand.WRITEZohoCRM.modules.leads.READand.WRITEZohoCRM.modules.deals.READZohoCRM.modules.accounts.READZohoCRM.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.
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
Verify: Ask the bot "search my Monday boards for [keyword]" — it should execute the search and return results.
Was this article helpful?