API Endpoints Reference (HTTP Actions)

Relevant source files

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

• convex/http.ts
• convex/ai.ts
• convex/slackCommands.ts
• convex/slackBlocks.ts
• README.md
• PROJECT_DESCRIPTION.md
• src/App.tsx

The convex/http.ts file defines all public-facing HTTP endpoints for the TalkCRM application using Convex's httpRouter. These endpoints serve as the primary gateway for external services to interact with the backend, handling requests from voice AI agents, telephony providers, messaging platforms, and the frontend application. The router manages webhooks, AI tool calls, user authentication, and API requests for analytics and configuration.

The architecture relies on these HTTP actions to receive external triggers, which then invoke internal Convex actions and mutations to perform business logic, interact with the database, and call third-party APIs like Salesforce and Anthropic (Claude).

Sources: convex/http.ts, PROJECT_DESCRIPTION.md, README.md

Core Architecture

The HTTP router is the entry point for all external, synchronous communication. It validates requests, logs activity, and dispatches tasks to the appropriate Convex functions. A key feature is the use of signature verification for webhooks from services like ElevenLabs and Slack to ensure security.

Sources: convex/http.ts:16-21, 55-103, 1172-1209

Request Handling Flow

This diagram illustrates the general flow for an incoming HTTP request to a tool endpoint.

Sources: convex/http.ts:109-173, convex/ai.ts:164-180

AI Assistant & Tool Endpoints

These endpoints are designed to be called by the ElevenLabs Conversational AI agent. The primary endpoint, /tools/assistant, uses a powerful AI action to interpret natural language, while legacy endpoints map to specific Salesforce operations.

Sources: convex/http.ts:106-498, README.md

Primary AI Assistant Endpoint

The /tools/assistant endpoint is the main entry point for all natural language queries from the voice agent. It takes a user's message, determines the user's identity, and passes the request to the api.ai.askSalesforce action for interpretation and execution.

Sources: convex/http.ts:112-173, convex/ai.ts:164-180

Sources: convex/http.ts:112-173, convex/ai.ts:353-387

Legacy Tool Endpoints

These endpoints provide a more direct, one-to-one mapping between a tool name and a Salesforce function.

Method	Path	Handler Action	Description
POST	/tools/assistant	api.ai.askSalesforce	Interprets natural language to perform any SF action.
POST	/tools/search	api.salesforce.searchRecords	Searches for Salesforce records.
POST	/tools/get-record	api.salesforce.getRecord	Retrieves details for a specific record.
POST	/tools/create-record	api.salesforce.createRecord	Creates a new record (e.g., Task, Lead).
POST	/tools/update-record	api.salesforce.updateRecord	Updates fields on an existing record.
POST	/tools/log-call	api.salesforce.logCall	Logs a call activity against a record.
POST	/tools/my-tasks	api.salesforce.getMyTasks	Retrieves the current user's open tasks.
POST	/tools/my-pipeline	api.salesforce.getMyOpportunities	Retrieves the current user's open opportunities.
POST	/tools/my-accounts	api.salesforce.getMyAccounts	Retrieves the current user's accounts.

Sources: convex/http.ts:109-498, README.md

Webhook Endpoints

The system exposes numerous webhook endpoints to receive real-time events from integrated third-party services.

Sources: convex/http.ts:501-1169

ElevenLabs Webhooks

These webhooks manage the lifecycle of a voice conversation.

Method	Path	Handler Action	Description
POST	/webhooks/elevenlabs/conversation-start	internal.conversations.updateElevenlabsConversationId	Maps the ElevenLabs conversation_id to a TalkCRM userId.
POST	/webhooks/elevenlabs/post-call	internal.conversations.completeConversation	Receives post-call analytics, transcript, summary, and recording URL.

Sources: convex/http.ts:507-657

Twilio Webhooks

These webhooks handle incoming phone calls and subsequent recordings.

Method	Path	Handler Action	Description
POST	/webhooks/twilio/incoming	internal.users.getUserByPhoneInternal	Authenticates caller via phone number and connects them to the ElevenLabs agent.
POST	/webhooks/twilio/recording	api.recordings.fetchFromTwilio	Receives notification when a call recording is ready and fetches it.

Sources: convex/http.ts:663-775

SendBlue Webhooks (SMS/Text Messaging)

This suite of endpoints manages AI-powered interactions over SMS via SendBlue.

Method	Path	Handler Action	Description
POST	/webhooks/sendblue/incoming	internal.sendblue.processIncomingText	Receives incoming text messages and triggers an AI response.
POST	/webhooks/sendblue/status	internal.textMessages.updateMessageStatus	Updates the status of an outbound message (e.g., delivered, failed).
POST	/webhooks/sendblue/call-logs	-	Logs call activity from a SendBlue number.
POST	/webhooks/sendblue/line-blocked	-	Handles notifications when a user blocks the SendBlue number.
POST	/webhooks/sendblue/line-assigned	-	Logs when a new phone number is assigned to the account.
POST	/webhooks/sendblue/outbound	-	Logs all outbound messages sent from the SendBlue platform for audit.
POST	/webhooks/sendblue/contact-created	-	Logs when a new contact is created within SendBlue.

Sources: convex/http.ts:1000-1169

Slack Webhooks

These endpoints handle all interactions from the Slack platform, including slash commands, events, and interactive components.

Method	Path	Handler Action	Description
POST	/webhooks/slack/events	internal.slackCommands.handleAppMention	Handles event subscriptions like app mentions and direct messages.
POST	/webhooks/slack/commands	internal.slackCommands.handleSlashCommand	Receives and processes slash commands (e.g., /crm search).
POST	/webhooks/slack/actions	-	Handles interactive component payloads like button clicks.

Sources: convex/http.ts:1212-1367, convex/slackCommands.ts:68-124

Salesforce OAuth Endpoints

These endpoints manage the multi-tenant OAuth 2.0 flow for connecting users' Salesforce organizations to TalkCRM. The flow supports both a web-based connection and an in-package setup from a Salesforce LWC.

Sources: convex/http.ts:1506-1801

Salesforce OAuth Flow

The diagram below shows the sequence for connecting a Salesforce org from within the TalkCRM package.

Sources: convex/http.ts:1545-1623, 1629-1801

OAuth Endpoint Summary

Method	Path	Description
GET	/auth/salesforce/connect	Initiates web-based OAuth flow for a user from the TalkCRM web app.
GET	/auth/salesforce/initiate	Initiates OAuth flow from within the Salesforce package (LWC).
GET	/auth/salesforce/callback	Handles the callback from Salesforce, exchanges the code for tokens, creates/updates the user, and stores auth credentials.

Sources: convex/http.ts:1506-1801

User Authentication & Management API

These endpoints provide a custom phone-based authentication system and user/org management functionalities.

Sources: convex/http.ts:778-1503

Authentication Endpoints

Method	Path	Handler Action	Description
POST	/api/auth/signup/start	api.sendblue.startVerification	Starts the signup process by sending a verification code via SMS.
POST	/api/auth/verify	api.sendblue.completeVerification	Verifies the SMS code to complete signup or login.
POST	/api/auth/login/start	api.sendblue.startVerification	Starts the login process for an existing user by sending an SMS code.
POST	/api/auth/add-phone	api.users.startPhoneVerification	Initiates the process of adding a new phone number to an existing user.

Sources: convex/http.ts:784-909

User & Org Management Endpoints

Method	Path	Handler	Description
GET	/api/user	api.users.getUser	Retrieves a user's profile information.
POST	/api/org/register	internal.orgCredentials.create/update	Registers or updates a Salesforce Connected App's credentials for an org.
POST	/api/org/sync-metadata	internal.orgMetadata.syncFromSalesforce	Manually triggers a synchronization of an org's Salesforce schema.
GET	/api/org/metadata	internal.orgMetadata.getAvailableObjects	Retrieves the available custom and standard objects for a user's org.

Sources: convex/http.ts:912-942, 1400-1503

Conclusion

The convex/http.ts file is the central nervous system for TalkCRM's external communications. It provides a well-structured and secure set of endpoints for a wide range of integrations, including voice AI, telephony, messaging, and CRM platforms. By leveraging Convex's httpRouter and httpAction, the application can efficiently handle incoming webhooks, process API requests, and manage complex authentication flows, all within a serverless environment.

Sources: convex/http.ts