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, or admin consent has not been granted.

Fix:

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

2. Click Add a permission → Dynamics CRM → Delegated permissions

3. Check user_impersonation → click Add permissions

4. Click Grant admin consent for [your organization] — this requires an Azure AD admin account

5. 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.

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.

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 Accounts → Create API Account

2. Set permissions: Catalog (Read + Write), Orders (Read + Write), Customers (Read + Write)

3. Copy the new Access Token and re-enter it in Integrations → BigCommerce

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.