Salesforce Integration

Connect Agents to Salesforce to automate CRM tasks, update opportunities, and streamline your sales workflows.

Overview

The Salesforce integration enables workflows to:

• Create tasks associated with opportunities, contacts, or accounts
• Update opportunities with meeting outcomes and next steps
• Query records for workflow decisions
• Log activities from meetings

Prerequisites

Before connecting Salesforce:

1. Salesforce account (any edition with API access)
2. API access enabled for your user profile
3. Permission to install connected apps (or admin assistance)

Connecting Salesforce

Step 1: Navigate to Integrations

1. Go to Workspace Settings
2. Select Integrations
3. Find Salesforce in the list

Step 2: Authorize Connection

1. Click Connect
2. Log in to your Salesforce org
3. Review the requested permissions
4. Click Allow

Step 3: Verify Connection

After authorization:

• Connection status shows "Connected"
• Your Salesforce instance URL is displayed
• You can test the connection

Required Permissions

The Salesforce integration requires these permissions:

Profile Configuration

Ensure your Salesforce profile has:

1. API Enabled checkbox selected
2. Object permissions for objects you want to access
3. Field-level security for fields you want to read/update

Available Actions

Create Salesforce Task

Create a task in Salesforce associated with a record.

Configuration:

Example:

[AI: Extract follow-up tasks] ──▶ [Create Salesforce Task]

With configuration:

• what_id: {{ json.opportunityId }}
• subject: {{ json.taskTitle }}
• description: {{ json.taskDescription }}
• activity_date: {{ json.dueDate }}

Update CRM (Opportunity)

Update opportunity fields after meetings.

Configuration:

Common updatable fields:

• Name - Opportunity name
• Amount - Deal value
• StageName - Pipeline stage
• CloseDate - Expected close date
• NextStep - Next step text
• Description - Opportunity description
• Custom fields - Any custom opportunity fields

Working with Salesforce IDs

ID Format

Salesforce IDs come in two formats:

• 15-character - Case-sensitive
• 18-character - Case-insensitive (recommended)

Always use 18-character IDs when possible for reliability.

Finding Object IDs

From meeting context:

{{ json.meeting.externalServiceObjects | where: "type", "DEAL" | first | map: "externalId" }}

From Deal Room:

{{ json.dealRoom.salesforceOpportunityId }}

Object Types

Pipeline Stages

Stage Names

Unlike HubSpot (which uses stage IDs), Salesforce uses stage names directly:

{
  "StageName": "Proposal/Price Quote"
}

Finding Stage Names

1. Go to Salesforce Setup
2. Navigate to Object Manager → Opportunity → Fields & Relationships
3. Click on "Stage"
4. View picklist values

Common default stages:

• Prospecting
• Qualification
• Needs Analysis
• Value Proposition
• Id. Decision Makers
• Perception Analysis
• Proposal/Price Quote
• Negotiation/Review
• Closed Won
• Closed Lost

Field Mappings

Standard Fields

Custom Fields

Access custom fields by their API name (ending in __c):

1. Go to Setup → Object Manager → [Object] → Fields & Relationships
2. Find your custom field
3. Copy the API Name (e.g., Custom_Field__c)
4. Use in field_values

Example:

{
  "Custom_Field__c": "value",
  "Meeting_Notes__c": "Notes from latest meeting"
}

Task Configuration

Task Subtypes

By default, tasks are created with TaskSubtype: 'Call'. This appears as a "Call" activity type in Salesforce.

WhatId vs WhoId

Salesforce tasks have two relationship fields:

Example - Task on Opportunity:

{
  "WhatId": "0061234567890abcdef",
  "Subject": "Send proposal"
}

Example - Task for Contact:

{
  "WhoId": "0031234567890abcdef",
  "Subject": "Schedule demo"
}

Example Workflows

Post-Meeting Task Creation

[Event: MEETING_ENDED]
        │
        ▼
[Load Meeting]
        │
        ▼
[AI: Extract action items]
        │
        ▼
[Select Many: action items]
        │
        ▼
[Create Salesforce Task]

Task Configuration:

• what_id: {{ json.meeting.salesforceOpportunityId }}
• subject: {{ json.item.title }}
• description: {{ json.item.description }}
• activity_date: {{ json.item.dueDate | date: "%Y-%m-%d" }}

Opportunity Stage Update

[Event: MEETING_ENDED]
        │
        ▼
[Load Meeting]
        │
        ▼
[If: has Salesforce opportunity?]
        │
        ├── Yes ──▶ [AI: Analyze deal progress]
        │                    │
        │                    ▼
        │           [AI: Recommend stage]
        │                    │
        │                    ▼
        │           [CRM Update Opportunity]
        │
        └── No ───▶ [Sink]

Update Next Step After Meeting

[Event: MEETING_ENDED]
        │
        ▼
[Load Meeting]
        │
        ▼
[AI: Identify next steps]
        │
        ▼
[CRM Update Opportunity]
    field_values:
      NextStep: "{{ json.nextStep }}"

Best Practices

1. Use 18-Character IDs

Always prefer 18-character Salesforce IDs to avoid case-sensitivity issues.

2. Validate Stage Names

Stage names are case-sensitive and must match exactly. Test with actual values from your org.

3. Handle Picklist Restrictions

Salesforce may have restricted picklists. If you encounter "INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST":

• Verify the value exists in the picklist
• Check for organization-specific picklist values
• Use exact spelling and case

4. Date Formatting

Salesforce expects dates in YYYY-MM-DD format:

{{ json.date | date: "%Y-%m-%d" }}

For datetime fields, use ISO 8601:

{{ json.datetime | date: "%Y-%m-%dT%H:%M:%SZ" }}

5. Check Field-Level Security

If updates silently fail:

1. Verify the user has field-level edit access
2. Check if the field is read-only
3. Verify the field is not formula-based

Troubleshooting

Common Errors

Token Refresh Issues

Salesforce tokens are automatically refreshed. If auth consistently fails:

1. Disconnect the Salesforce integration
2. Clear browser cookies for Salesforce
3. Reconnect and re-authorize
4. Test with a simple workflow

Query Limits

Salesforce has API limits based on your edition:

Monitor usage in Setup → Company Information → API Requests.

Field Access Issues

If you can't update a field:

1. Check field-level security - Your profile may not have edit access
2. Check page layouts - Field might not be on your layout
3. Check validation rules - A rule may be blocking the update
4. Check workflow rules - A rule may be overwriting your value

Security Considerations

Data Access

The integration respects Salesforce's security model:

• Profile permissions - Can only access objects your profile allows
• Field-level security - Can only read/write fields your profile allows
• Sharing rules - Can only see records shared with your user
• Record types - Respects record type assignments

Token Storage

• OAuth tokens are encrypted at rest
• Tokens are automatically refreshed using the refresh token
• Instance URLs are stored to route requests correctly

Sandbox Support

You can connect to Salesforce sandboxes for testing:

1. When connecting, select "Login to Sandbox" if available
2. Or modify the login URL during OAuth

SOQL Considerations

When workflows query Salesforce data, queries are built with:

• Parameterized inputs - Prevents SOQL injection
• Limited fields - Only requested fields are queried
• Pagination - Large result sets are paginated

Related

• Create Salesforce Task Node
• CRM Update Node
• HubSpot Integration