Salesforce CRM

The Salesforce integration lets your chatbot push leads, fetch accounts, update opportunities, and run arbitrary SOQL queries — all from a chat conversation. OAuth tokens, SOQL execution, and refresh logic live on Hilal’s backend; the frontend is a thin permission-gated dispatcher.

In this guide:

• What the bot can do with Salesforce
• Connect via Salesforce OAuth
• Available chat actions
• Permissions
• Disconnect

What the bot can do

Four chat actions ship out of the box:

The first three are typed and validated. SOQL is a generic projection surface — the bot can query whatever objects the connected user has access to.

Step 1: Connect Salesforce

On your chatbot detail page, go to Actions → Integrations. Find the Salesforce card.

Screenshot: The Salesforce integration card with the Connect button.

Click Connect. You’re redirected through Salesforce OAuth — sign in (production or sandbox; controlled by Hilal Chatbot’s backend), approve permissions:

• Read & write basic data (api).
• Refresh access token (refresh_token).

After approval you return to Hilal Chatbot with ?salesforce=success and the card shows Connected.

Step 2: Use chat actions

Once connected, the bot picks up Salesforce actions automatically when the conversation calls for them. Example flows:

• “I’d like to learn more about your enterprise plan.” → bot collects name/email → triggers Create Lead with the captured info.
• “What’s the status of opportunity OPP-123?” → bot triggers Get Account then surfaces relevant fields.
• “Move opportunity OPP-456 to Closed Won.” → bot triggers Update Opportunity (typically destructive — see Confirmation flows (New)).
• “How many open opportunities have we won this quarter?” → bot triggers Run SOQL with SELECT COUNT() FROM Opportunity WHERE IsWon = true AND CloseDate = THIS_QUARTER.

For bots that need finer control over which actions fire when, use the AI actions framework directly to define custom Salesforce actions.

Step 3: Configure permissions

Per-action permissions live in SALESFORCE_ACTIONS:

• CREATE_OAUTH / READ_INTEGRATIONS / DELETE_INTEGRATIONS — connect / inspect / disconnect.
• CREATE_LEAD / READ_ACCOUNT / UPDATE_OPPORTUNITY / RUN_SOQL — per-chat-action.

Granting any one of the four chat-action permissions unlocks the integration’s dispatcher. For maximum safety, only grant CREATE_LEAD and READ_ACCOUNT to public-facing bots; reserve RUN_SOQL and UPDATE_OPPORTUNITY for internal bots.

Step 4: Disconnect

In Actions → Integrations, click the Salesforce card menu → Disconnect. Hilal’s stored OAuth token is revoked. Subsequent chat actions return 403.

Production vs. Sandbox

Salesforce orgs come in production and sandbox flavors. Hilal Chatbot’s backend selects the OAuth host based on the type of org you connect — there’s no UI toggle to flip between them. To connect a sandbox separately, use a different chatbot or a different organization in Hilal Chatbot.

SOQL safety

SOQL is powerful — and dangerous. The bot can read whatever the connected user can read, including potentially sensitive fields. Three guardrails:

1. Permission gating. RUN_SOQL is the highest-privilege action; restrict it.
2. No DML via SOQL. SOQL is read-only. Writes must use the typed actions (CREATE_LEAD, UPDATE_OPPORTUNITY).
3. Confirmation flows. Configure the bot to require human confirmation before any non-trivial SOQL or update — see Confirmation flows.

Troubleshooting

• “Not connected” but I just clicked Connect. OAuth may have completed but the redirect was lost. Click Connect again.
• Action returns 502. Backend Salesforce token may have expired. Disconnect and reconnect.
• SOQL syntax errors. SOQL is strict — single quotes for strings, Id fields are 18 characters. Test in Salesforce’s Developer Console first.

Out of scope (not yet supported)

• Bidirectional contact sync (background) — coming separately.
• Configurable field-mapping UI — coming separately.
• Salesforce → chatbot real-time webhooks — see Real-time sync for the equivalent on Shopify; Salesforce coming.

What’s next