SMS/Text Interaction (SendBlue)

Relevant source files

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

• convex/sendblue.ts
• convex/http.ts
• convex/ai.ts
• agent_configs/SIMPLE-Co-Sales-Agent.json
• salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html
• README.md

The SendBlue integration provides two core functionalities for TalkCRM: user authentication via SMS-based phone number verification and an AI-powered text messaging channel (iMessage & SMS) for interacting with Salesforce. This allows users to manage their CRM data through a conversational text interface, complementing the primary voice channel. The user-facing number for this service is +1 (656) 252-4906.

The system is designed to be mobile-first, enabling sales reps to interact with their CRM without needing to be at a computer. The AI agent's behavior is specifically adapted for text-based channels, emphasizing concise messages and different interaction patterns compared to voice.

Sources: convex/sendblue.ts, salesforce-package/force-app/main/default/lwc/talkCrmSetup/talkCrmSetup.html:150-156, agent_configs/SIMPLE-Co-Sales-Agent.json:20-33

Architecture and Data Flow

The SendBlue integration is centered around Convex actions and HTTP endpoints. Incoming messages from users trigger webhooks handled by convex/http.ts, which then schedule internal actions in convex/sendblue.ts for processing. Outgoing messages are sent via Convex actions that call the SendBlue API.

High-Level Data Flow

This diagram illustrates the flow of an incoming text message from a user to Salesforce and back.

Phone Number Verification

SendBlue is used to manage the user authentication flow by verifying a user's phone number. This process involves sending a one-time code via SMS and verifying it.

Verification Flow

The verification process is initiated through API endpoints and orchestrated by actions in convex/sendblue.ts.

1. Start Verification: A request to /api/auth/signup/start or /api/auth/login/start triggers the sendblue.startVerification action.
2. Create Code: The users.startPhoneVerification mutation generates a verification code and saves its hash and expiration to the database.
3. Send SMS: The sendblue.sendVerificationSMS action is called, which sends the code to the user's phone via the SendBlue API.
4. Complete Verification: The user submits the code to /api/auth/verify, which calls the sendblue.completeVerification action. This in turn calls users.verifyPhoneCode to validate the code and complete the login/signup.

This diagram shows the sequence of events for phone verification.

Key Verification Functions

Function	File	Description
sendVerificationSMS	convex/sendblue.ts	Sends an SMS with a verification code using the SendBlue API.
startVerification	convex/sendblue.ts	Orchestrates the start of the verification flow by creating a code and triggering the SMS send.
completeVerification	convex/sendblue.ts	Verifies the submitted code against the database record to finalize authentication.

Sources: convex/sendblue.ts:10-120

AI-Powered Text Conversations

The core of the text interaction feature is the ability to have an AI-powered conversation to query and update Salesforce. This is handled by a dedicated webhook and a processing pipeline.

Incoming Message Processing

The entry point for all incoming user texts is the /webhooks/sendblue/incoming HTTP endpoint.

The process is as follows:

1. Webhook Reception: SendBlue sends a POST request to the webhook.
2. Signature Verification: The verifySendBlueSignature function validates the request to ensure it's from SendBlue, using the SENDBLUE_WEBHOOK_SECRET.
3. User Identification: The system looks up the user in the database based on the from_number. If the user is not found or is inactive, a standard message is sent back with instructions.
4. Deduplication: The message_handle is checked to prevent processing the same message multiple times.
5. Asynchronous Processing: The core logic is offloaded to the internal.sendblue.processIncomingText internal action via ctx.scheduler.runAfter(0, ...) to ensure a fast response to the webhook provider.

Sources: convex/http.ts:1143-1243, convex/sendblue.ts:200-210

processIncomingText Internal Action

This internal action contains the main business logic for handling a user's text message.

Key steps within this action:

• Typing Indicator: A sendTypingIndicator action is fired immediately to provide a better user experience, showing that the AI is "thinking".
• AI Processing: It reuses the main api.ai.askSalesforce action, passing the text message and conversation history. This unifies the AI logic across both voice and text channels.
• Response Formatting: If the AI action results in a new Salesforce record being created, the URL to that record is appended to the response text.

Sources: convex/sendblue.ts:233-236, convex/sendblue.ts:257-260

AI Agent Behavior for Text

The AI agent is configured with specific instructions for text-based channels like WhatsApp (which are analogous to SMS/iMessage). These rules ensure the agent's communication style is appropriate for the medium.

Rule	Description
Conciseness	Be concise and scannable, as users read on mobile.
Message-Breaking	Break up longer explanations into multiple short messages.
Line Breaks	Use line breaks liberally to improve readability.
Quick Acknowledgments	Use short phrases like "Got it" or "Makes sense".
Scheduling	For scheduling, share the booking link (https://cal.com/team/simple) instead of using booking tools directly.

Sources: agent_configs/SIMPLE-Co-Sales-Agent.json:20-33

Webhook Integration

The system relies on several webhooks from SendBlue to maintain state and handle various events. All webhooks are defined in convex/http.ts.

Webhook Path	Method	Description
/webhooks/sendblue/incoming	POST	Handles incoming messages from users. This is the primary webhook for AI conversations.
/webhooks/sendblue/status	POST	Receives delivery status updates for outbound messages (e.g., SENT, DELIVERED, FAILED).
/webhooks/sendblue/call-logs	POST	Receives logs for calls made to or from the SendBlue number.
/webhooks/sendblue/line-blocked	POST	Triggered when a user blocks the SendBlue number.
/webhooks/sendblue/line-assigned	POST	Triggered when a new phone number is assigned to the SendBlue account.
/webhooks/sendblue/outbound	POST	Logs all outbound messages sent from the SendBlue dashboard or API for auditing.
/webhooks/sendblue/contact-created	POST	Logs the creation of new contacts within SendBlue.

Sources: convex/http.ts:1143-1454

Security

All incoming webhooks are secured using HMAC-SHA256 signature verification. The verifySendBlueSignature function in convex/http.ts computes a hash based on the request body and the SENDBLUE_WEBHOOK_SECRET environment variable, comparing it to the x-sendblue-signature header.

Sources: convex/http.ts:1111-1141

Summary

The SendBlue integration is a critical component of TalkCRM, providing a robust and secure channel for both user authentication and AI-driven CRM management via text. It leverages Convex's serverless functions and actions to create a responsive and scalable system. By reusing the core askSalesforce AI action, it ensures consistent behavior across voice and text channels, while adapting the interaction style to be optimal for a mobile, text-based experience.