Troubleshooting Guide

Relevant source files

The following files were used as context for generating this wiki page:

• salesforce-package/POST_DEPLOY_GUIDE.md
• convex/http.ts
• convex/ai.ts
• salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html
• src/App.tsx
• README.md

This guide provides solutions for common issues encountered during the setup and operation of TalkCRM. It covers problems related to Salesforce package deployment, user authentication, voice call processing, AI interpretation, and API integrations. Each section outlines potential errors, their causes, and steps for resolution based on the system's architecture.

Setup and Installation

This section addresses common problems that may occur during the initial deployment and configuration of the TalkCRM Salesforce package.

Sources: salesforce-package/POST_DEPLOY_GUIDE.md, salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html

Common Setup Errors

The following table summarizes issues mentioned in the post-deployment guide.

Problem	Cause	Solution
OAuth fails or "Access Denied"	Logging into the wrong Salesforce org or browser cache issues.	Ensure you are logging into the correct org. Try clearing browser cache and cookies.
Phone verification code not received	Incorrect phone number entered or SMS delay.	Double-check the phone number. Wait 1-2 minutes for the SMS. In dev mode, the code appears on-screen.
"TalkCRM" not in App Launcher	The TalkCRM User permission set is not assigned to the user.	Go to Setup -> Permission Sets, select TalkCRM User, and assign it to the relevant users.
Call not recognized / "Unknown caller"	The call is not from a verified phone number.	Ensure you are calling from the number you verified in the TalkCRM Setup wizard.

Sources: salesforce-package/POST_DEPLOY_GUIDE.md:61-75

Setup Wizard Failures

The TalkCRM Setup is a multi-step Lightning Web Component. Errors can occur at each stage and will be displayed in the UI.

The setup flow is as follows:

1. Configure App: User enters the Connected App's Consumer Key and Secret.
2. Connect Salesforce: User initiates an OAuth flow to authorize TalkCRM.
3. Verify Phone: User enters a phone number and a verification code sent via SMS.
4. Ready: Setup is complete.

The UI includes a dedicated section to display error messages to the user.

<!-- Error Display -->
<template lwc:if={errorMessage}>
    <div class="slds-notify slds-notify_alert slds-alert_error slds-m-top_medium" role="alert">
        <lightning-icon icon-name="utility:error" variant="inverse" size="x-small" class="slds-m-right_x-small"></lightning-icon>
        {errorMessage}
    </div>
</template>

Sources: salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:14-20, 421-427

Authentication and User Access

Issues in this category relate to user login, Salesforce connection, and identifying users during a call or text interaction.

Unregistered Caller

When a user calls the Twilio number, the system performs a lookup to identify them by their phone number. If the caller's number is not registered in the TalkCRM system, the call is rejected with a voice message.

This diagram shows the incoming call authentication flow.

The TwiML response for an unregistered caller explicitly states the problem and the resolution path.

<Response>
  <Say voice="alice">
    Sorry, this phone number is not registered with Talk CRM.
    Please visit talk crm dot com to create an account and verify your phone number.
    Goodbye.
  </Say>
  <Hangup />
</Response>

Sources: convex/http.ts:811-819

Salesforce OAuth Failures

TalkCRM uses OAuth 2.0 to connect to a user's Salesforce account. If this process fails, it's often due to misconfiguration of the Connected App credentials.

• Web App Flow: Uses a centralized Connected App defined by environment variables (SALESFORCE_CLIENT_ID, SALESFORCE_REDIRECT_URI).
• LWC Package Flow: Uses per-org credentials stored in the orgCredentials table, which are configured in Step 1 of the setup wizard.

If the LWC flow fails, it may be because no credentials are found for the user's instanceUrl. The system will return an HTML page indicating that the Connected App is not configured.

Sources: convex/http.ts:1020-1070, salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:50-84

AI and Salesforce Action Errors

These errors occur after a user is authenticated and is interacting with the AI agent.

AI Interpretation Failure

The core AI logic resides in the askSalesforce action, which calls the interpretWithClaude function. Errors can happen at several points.

This flowchart illustrates the error handling within the askSalesforce action.

Common failure points include:

1. Anthropic API Key Missing: If ANTHROPIC_API_KEY is not set, the function throws an error: "AI service is not configured. Please contact support."
2. Claude API Error: Any error from the Anthropic API call is caught and returned to the user.
3. JSON Parsing Error: If Claude returns a response that is not valid JSON, the system returns a clarification message: "I didn't quite catch that. Could you say it another way?".

Sources: convex/ai.ts:563-566, 581-585, 588-593

Salesforce Action Failure

If the AI successfully interprets the command but the subsequent Salesforce action fails (e.g., a SOQL query is invalid, a record update fails due to validation rules), the error is caught in the main try...catch block of the askSalesforce action.

The system returns a user-friendly message that includes the specific error from the Salesforce API.

// From convex/ai.ts
} catch (error: any) {
  console.error("Salesforce action error:", error);
  // ... agent log ...
  return {
    response: `I ran into an issue: ${error.message}. Would you like me to try again?`,
  };
}

Sources: convex/ai.ts:477-485

Webhook and API Issues

TalkCRM relies on webhooks from third-party services like ElevenLabs, Twilio, and Slack. Signature verification is a common point of failure.

Invalid Webhook Signature

The system uses HMAC-SHA256 to verify signatures from webhook providers to prevent spoofing.

Provider	Verification Function	Common Failure Reasons
ElevenLabs	verifyElevenLabsSignature	Invalid ELEVENLABS_WEBHOOK_SECRET, timestamp is more than 5 minutes old (replay attack).
SendBlue	verifySendBlueSignature	Invalid SENDBLUE_WEBHOOK_SECRET.
Slack	verifySlackSignature	Invalid SLACK_SIGNING_SECRET, timestamp is more than 5 minutes old.

If signature verification fails, the convex/http.ts handler will return an HTTP 401 Unauthorized status and log an error.

Sources: convex/http.ts:77-123, 1195-1223, 1618-1673

API Error Responses

The HTTP endpoints in convex/http.ts are designed to return structured JSON responses, including for errors. A generic error during a tool execution (e.g., /tools/search) will result in an HTTP 500 response with a JSON body.

{
  "error": "Error message from the action"
}

Sources: convex/http.ts:246-252

Support

If the issues persist after following this guide, you can find further help:

• Schedule a setup call: A link is available on the installation page.
• Email support: The support email is listed in the POST_DEPLOY_GUIDE.md.

Sources: src/App.tsx:497-505, salesforce-package/POST_DEPLOY_GUIDE.md:87-89