> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/channels-integrations/crm-service/salesforce.md).
# Salesforce CRM Service
Configure CRM Service for Salesforce.
Configure CRM Service for Salesforce when WebAgent must retrieve Salesforce information.
Before requesting the service, confirm the [shared CRM connector licensing prerequisites](/channels-integrations/crm-service.md#licensing-prerequisites).
## Request Salesforce CRM Service in OnePortal
1. Request the Salesforce CRM Service for the customer environment through the current OnePortal, delivery, or support process.
2. Confirm which UCC and WebAgent configuration must consume Salesforce data.
3. Confirm that Salesforce is the enabled CRM Service provider before changing provider settings.
4. Use [Configure CRM Service settings](/channels-integrations/crm-service/configure-crm-service-settings.md) for shared request, change, `PluginSettings`, `PluginAttributes`, and secret-handling rules.
{% hint style="info" %}
Exact OnePortal labels can differ by release. Use the current customer-specific request path instead of legacy labels.
{% endhint %}
## Prepare Salesforce
A Salesforce administrator must prepare connected-app and API-user access before CRM Service settings are completed.
CRM Service for Salesforce uses the Salesforce OAuth username-password flow. The connected app provides `ClientId` and `ClientSecret`; the Salesforce API user provides `Username` and `Password`. All four settings are required.
| Preparation item | What to prepare | Used by CRM Service |
| ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| Connected app | Salesforce connected app approved for CRM Service API access. | `ClientId` and encrypted `ClientSecret` |
| Callback URL | Configure `sfdc://oauth/restapi/success` on the connected app. | OAuth flow |
| OAuth scopes | Include `api` and `refresh_token/offline_access`. | API access and refresh-token capability |
| API user | Salesforce user with access to the objects WebAgent must display. | `Username` and encrypted `Password` |
| Endpoints | Application, API, and login endpoints approved for the environment. | `ApplicationHost`, `ApiEndPoint`, and `LoginEndPoint` |
Use current Salesforce Help and verify current UI labels before changing connected-app settings:
* [Create a connected app](https://help.salesforce.com/articleView?id=connected_app_create.htm\&type=5)
* [Connected app basics](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_basics.htm\&language=en_US\&type=5)
* [Connected app API integration settings](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_api_integration.htm\&language=en_US\&type=5)
* [OAuth scopes](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_scopes.htm\&type=5)
## Configure Salesforce CRM Service in Dialogue Cloud Neo / SharePoint
Enter or request these values in the active configuration source for `CrmService` `PluginSettings`.
| Setting | Requirement | Value |
| --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ApplicationHost` | Required | Salesforce application URL supplied for the environment, for example `https://eu6.salesforce.com/`. |
| `ApiEndPoint` | Required | Salesforce REST API endpoint supplied for the environment, for example `services/data/v37.0/`. Confirm that the API version is approved for the environment. |
| `LoginEndPoint` | Required | Salesforce login endpoint supplied for the environment, for example `https://login.salesforce.com/services/oauth2/token`. |
| `Username` and encrypted `Password` | Required | Salesforce API-user credentials. |
| `ClientId` and encrypted `ClientSecret` | Required | Salesforce connected-app values. |
Configure Salesforce field mappings in `CrmService` `PluginAttributes` when the default mapping is not sufficient for the customer data model.
{% hint style="warning" %}
Do not prescribe a legacy password tool or local encryption procedure unless support confirms that it is the current customer-facing process.
{% endhint %}
## Configure optional Salesforce settings in Dialogue Cloud Neo / SharePoint
Add optional settings with scope `CrmService`.
| Setting or mapping | Where configured | Default or value guidance |
| ----------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ShowStatus` | `PluginSettings` | Shows whether the caller is a contact, lead, or unknown. Default: `True`. |
| `DefaultPhoneNumberRegion` | `PluginSettings` | ISO 3166 alpha-2 region code. Default: `ZZ`. |
| `PhoneNumberFormat` | `PluginSettings` | Default: `Wildcard`. Supported modes include `E164`, `International`, `Rfc3966`, and `Wildcard`. Use a more exact supported format when Salesforce phone fields store numbers consistently. |
| `BaseContactQuery` | `PluginSettings` | SOQL contact query template. Default: `query/?q=SELECT {0} from Contact WHERE {1} LIMIT 100`. `LIMIT` is mandatory. |
| `BaseLeadQuery` | `PluginSettings` | SOQL lead query template. Default: `query/?q=SELECT {0} from Lead WHERE {1} LIMIT 100`. `LIMIT` is mandatory. Contacts have precedence over leads until the configured limit is reached. |
| `BaseCaseQuery` | `PluginSettings` | SOQL case query template. Default: `query/?q=SELECT {0} FROM Case WHERE {1} LIMIT 100`. `LIMIT` is mandatory. |
| `ContactCaseFilter` | `PluginSettings` | Case-to-contact filter. Default: `ContactId = '{0}'`. Attribute and value must be valid Salesforce `SystemName` values. |
| `ContactConversationFilter` | `PluginSettings` | Contact-to-conversation filter. Configure this only when the environment has a confirmed convention value; the value must be a valid `SystemName`. |
| `CaseStatus` | `PluginSettings` | Maps Salesforce case status text to WebAgent status. Default mappings: `New=Open`, `Working=Open`, `Escalated=Open`, `Closed=Closed`. Align the Salesforce status values with the customer environment. |
| `TokenRenewDelay` | `PluginSettings` | Token-renew interval. Default: `2`. Use the value approved for the environment. |
| `UseDefaultPluginAttributes` | `PluginSettings` | Default behavior: if the setting is absent or `True`, CRM Service uses default Salesforce `PluginAttributes`. Set to `False` only when all required Salesforce `PluginAttributes` will be maintained manually. |
| Salesforce `PluginAttributes` | `PluginAttributes` | Map Salesforce attributes to WebAgent account, contact, lead, contact-search, lead-search, case, and case-search output. |
Salesforce query and mapping guidance
For Salesforce `PluginAttributes`, use Salesforce attributes as `SystemName` values. If an attribute comes from a linked entity, include the alias before the attribute. Use:
* `DisplayName` for the label shown in WebAgent.
* `ShowOnExtensionWindow` to control whether WebAgent displays the value.
* `Order`; restart numbering for each `Category`.
* `FieldType` values such as `Id`, `Name`, `PhoneNumber`, `SipAddress`, `Email`, `Date`, `Search`, `Verify`, and `FormattedValue` where the mapped field requires that behavior.
* `Hyperlink` to make a value clickable; include `SystemName` placeholders in square brackets when the link needs field values.
* `ShowOnToast` to force the attribute into the query.
Account mappings keep account context for contacts and leads. Do not include the account alias in the `SystemName` column for account attributes. Set `Order` to `0` when an account attribute is stored on another entity, such as `companyname` on a lead.
Only contacts can have cases. Case mappings use fixed display areas such as title, description, date, and status; the status field must align with `CaseStatus`. Case-search mappings should contain the same items as case mappings, with search fields added where required.
When adding attributes from another Salesforce entity, also update the relevant base SOQL query so the field is returned.
Keep complete customer-specific SOQL templates and mapping records in the delivery or configuration record. Include customer-specific SOQL only when the customer must validate an object, relationship, or field mapping.
### Default `PluginAttributes`
The default Salesforce rows are used when `UseDefaultPluginAttributes` is absent or `True`. Preserve linked-entity aliases in `SystemName` values. The `{uri.Scheme}` and `{uri.Host}` placeholders are valid for predefined values; use complete URLs when overriding hyperlinks.
| DisplayName | SystemName | Category | Order | ShowOnExtensionWindow | FieldTypes | Hyperlink | ShowOnToast |
| -------------- | ------------------ | -------- | ----: | --------------------- | --------------------- | --------------------------------------------------------- | ----------- |
| Company | `companyname` | Account | 0 | No | `Name` | | Yes |
| Account ID | `accountid` | Account | 1 | No | `Id` | | No |
| Company | `name` | Account | 2 | Yes | `Name, Search` | | No |
| Phone Number | `telephone1` | Account | 3 | Yes | `PhoneNumber, Search` | | No |
| Owner | `owner.fullname` | Account | 4 | Yes | | | No |
| Case ID | `id` | Case | 1 | No | `Id` | `{uri.Scheme}://{uri.Host}/lightning/r/Case/[id]/view` | No |
| Title | `subject` | Case | 2 | Yes | `Name, Search` | | No |
| Description | `description` | Case | 3 | Yes | | | No |
| Date | `lastmodifieddate` | Case | 4 | Yes | `Date` | | No |
| Status | `status` | Case | 5 | Yes | `FormattedValue` | | No |
| Contact ID | `id` | Contact | 1 | No | `Id` | `{uri.Scheme}://{uri.Host}/lightning/r/Contact/[id]/view` | No |
| Account ID | `accountid` | Contact | 2 | No | `Id` | | No |
| Name | `name` | Contact | 3 | No | `Name` | | Yes |
| Company | `account.name` | Contact | 4 | Yes | `Name` | | Yes |
| Email | `email` | Contact | 10 | Yes | `Search, Email` | | No |
| Phone Number | `phone` | Contact | 20 | Yes | `Search, PhoneNumber` | | No |
| Phone Number 2 | `homephone` | Contact | 21 | Yes | `Search, PhoneNumber` | | No |
| Mobile Number | `mobilephone` | Contact | 22 | Yes | `Search, PhoneNumber` | | No |
| Image | `photourl` | Contact | 23 | Yes | | | Yes |
| Lead ID | `id` | Lead | 1 | No | `Id` | `{uri.Scheme}://{uri.Host}/lightning/r/Lead/[id]/view` | No |
| Name | `name` | Lead | 3 | No | `Name` | | Yes |
| Email | `email` | Lead | 10 | Yes | `Search, Email` | | No |
| Phone Number | `phone` | Lead | 20 | Yes | `Search, PhoneNumber` | | No |
| Company | `company` | Lead | 30 | Yes | `Name` | | Yes |
LeadSearch is a copy of Lead, with `Name` also receiving the `Search` field type.
## Validate Salesforce CRM Service
1. Confirm that CRM Service can reach the Salesforce endpoints.
2. Search for a known Salesforce contact, lead, or case from WebAgent.
3. Confirm that expected Salesforce fields appear in WebAgent.
4. Confirm that phone-number recognition returns the expected Salesforce record.
## References
* [Create a connected app](https://help.salesforce.com/articleView?id=connected_app_create.htm\&type=5)
* [Connected app basics](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_basics.htm\&language=en_US\&type=5)
* [Connected app API integration settings](https://help.salesforce.com/s/articleView?id=sf.connected_app_create_api_integration.htm\&language=en_US\&type=5)
* [OAuth scopes](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_scopes.htm\&type=5)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://atlas.anywhere.now/channels-integrations/crm-service/salesforce.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.