Salesforce

What your agents can doCopy Anchor Link

Helios agents call your org's Salesforce APIs, with the access token attached server-side. Agents can find and call operations of the REST API, Composite, Bulk API 1.0 and 2.0, the Tooling API, the UI API, the GraphQL API, the Connect REST API, the Data 360 Connect REST API, the Reports and Dashboards REST API, the CRM Analytics REST API, the Data Prep Recipe REST API, the Agent API, and the Models API. Access depends on the connected Salesforce user's permissions and the app's scopes.

• Find leads, contacts, accounts, and opportunities with SOQL or SOSL, and report on the pipeline
• Run reports, refresh dashboards, and query CRM Analytics datasets with SAQL or SQL
• Create and update records the connected user can access, one at a time or many in one Composite or Bulk API request
• Move opportunities between stages and record the next step from call notes
• Log calls, create follow-up tasks, and post Chatter updates
• Read object and field definitions, list views, and page layouts, so custom objects and fields are reachable too
• Call your own Apex REST services, and query metadata with the Tooling API

Agents can only reach your org's My Domain host, such as https://acme.my.salesforce.com, and the Agent API and Models API on api.salesforce.com. Every call counts toward your org's daily API request limit. See Limits.

Agents can't use the SOAP API or the Metadata API. Those APIs need the access token inside the XML body of the request, and Helios never shows the token to an agent. Helios calls API version 68.0.

AuthenticationCopy Anchor Link

Both methods use an External Client App that you create in your own org. See Integration authentication for how credentials are stored and injected.

Both methods also need your org's My Domain URL. In Setup, search for My Domain. The URL looks like https://acme.my.salesforce.com. Sandboxes and Developer Edition orgs add a label, as in https://acme--uat.sandbox.my.salesforce.com. Government Cloud Plus Defense URLs end in my.salesforce.mil, and Salesforce on Alibaba Cloud URLs end in my.sfcrmproducts.cn.

Helios doesn't ask for specific scopes. The access token gets every OAuth scope selected on the External Client App, so those scopes decide which APIs agents can use. api is required, and Your own Salesforce OAuth app also needs refresh_token.

The Agent API and the Models API accept only JSON Web Token (JWT)-based access tokens. For agents to call them, also select Issue JSON Web Token (JWT)-based access tokens for named users in the app's OAuth settings, along with sfap_api and chatbot_api.

Changed scopes apply to new tokens. For Your own Salesforce OAuth app, connect again. For Salesforce External Client App, Helios gets a new token when Salesforce rejects the current one.

Salesforce External Client AppCopy Anchor Link

You need a Salesforce admin who can create External Client Apps. The org needs API access. Professional Edition orgs need API access turned on.

1. In Setup, open External Client App Manager and click New External Client App. Set Distribution State to Local.
2. Under OAuth Settings, select Enable OAuth.
   • Add the callback URL https://api.heliosapp.com/integrations/salesforce/oauth_callback. The same app can then serve the other method too.
   • Select the scopes from the table above, at least Manage user data via APIs (api).
   • Select Enable Client Credentials Flow.
3. Save. Open the app's Policies, select Enable Client Credentials Flow, and set Run As to the user Helios acts as. Use an integration user with the API Only User permission and access to the objects your agents need.
4. Open the app's Settings, then OAuth Settings, and click Consumer Key and Secret. Salesforce emails you a verification code before it shows them.
5. In Helios, choose Salesforce External Client App. Enter the consumer key in Consumer Key and the secret in Consumer Secret.
6. Set Base URL to your My Domain URL, such as https://yourco.my.salesforce.com.
7. Save.

Helios reads your org ID when you save, and accepts outbound messages only from that org. Agents can do what the run-as user's permissions allow, within the app's scopes, and Salesforce records every change as that user.

Your own Salesforce OAuth appCopy Anchor Link

You need a Salesforce admin to create the External Client App. Any user who can use the app can then approve it.

1. Create the External Client App as in the steps above, with the callback URL, but skip the client credentials settings and the run-as user.
2. Select the scopes from the table above, including Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access). Helios sends PKCE, so PKCE can stay required.
3. Copy the consumer key and secret from Settings, OAuth Settings, Consumer Key and Secret.
4. In Helios, choose Your own Salesforce OAuth app. Enter Consumer Key and Consumer Secret.
5. Set Base URL to your My Domain URL. Helios sends you to this URL to approve access.
6. Save, then approve access in Salesforce.

Agents can do what the approving user can do, within the app's scopes, and Salesforce records changes as that user. Helios uses the refresh token at least once a week to keep it active.

TriggersCopy Anchor Link

Salesforce can start a Workflow when a record is created or updated. Helios can't register a webhook in Salesforce for you. Instead, a record-triggered flow sends records to Helios with an outbound message, which you set up once in Salesforce. Outbound messages are available in Enterprise, Performance, Unlimited, and Developer editions. On Professional Edition, Helios shows record.changed as unavailable.

1. In Helios, open the connection and click Manage, or Set up webhook on the connection card. Webhook Setup shows the webhook URL and the secret field.
2. Enter a webhook secret and save. Use a long random value of letters and digits, such as the output of openssl rand -hex 32.
3. In Setup, search for Outbound Messages, open it, and click New Outbound Message. Choose the object to watch, such as Opportunity, and click Next.
   • Name: any name, such as Helios Opportunity.
   • Endpoint URL: the webhook URL, then /, then the secret, as in https://api.heliosapp.com/integrations/salesforce/webhooks/<connection ID>/<secret>.
   • User to send as: a user who can see the records. This user decides which data the message contains.
   • Send Session ID: leave it off. Helios doesn't use it.
   • Select the fields your agents need, such as Name, StageName, and Amount, and click Add. The record ID is always sent.
4. Save the outbound message.
5. In Setup, open Flows, click New Flow, and create a Record-Triggered Flow.
   • Object: the same object.
   • Trigger the Flow When: A record is created, or A record is created or updated.
   • Entry Conditions: the records Helios should get, such as StageName equals Closed Won. For updates, choose Only when a record is updated to meet the condition requirements.
   • Optimize the Flow for: Actions and Related Records. Outbound messages aren't available with Fast Field Updates.
6. Add an Action element to the flow and choose the outbound message from step 3. Save and activate the flow.

The flow's conditions decide which records reach Helios. The trigger in Helios only filters by object.

• Object matches the API name of the record's object, such as Opportunity or Invoice__c. It's a pattern, so *__c matches every custom object. Case doesn't matter. It's optional. Without it, every record the connection receives matches.
• The payload holds the record's ID and the fields you chose on the outbound message, as text. Salesforce leaves out fields without a value, and a field it sends as nil is null. Fields with nested values, such as a compound address, are left out. Outbound messages don't say which fields changed.
• Salesforce can't send an outbound message when a record is deleted.
• Each record starts its own run. A bulk update or an import of many records starts many runs.

Outbound messages aren't signed. Helios checks the secret at the end of the URL, and accepts only messages from the org you connected.

Salesforce retries a failed delivery for up to 24 hours, with longer waits between tries, up to two hours. After 24 hours it drops the message. Retries can arrive out of order, and a message can arrive more than once. Helios ignores repeats of the same notification for 24 hours.

Deleting the connection in Helios doesn't remove the outbound message or the flow. Deactivate the flow, or Salesforce keeps sending each record to a URL that no longer works.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Salesforce rejected the credentials. See Common errors.
• A trigger:
  1. Add record.changed to a workflow with no filters.
  2. Create or update a record in Salesforce that meets the flow's entry conditions.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
• Salesforce's side: in Setup, open Outbound Messages and click View Message Delivery Status. It lists messages that haven't been delivered, with the number of attempts. Click Retry to send one again now.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• API requests: every agent call counts toward the org's total for 24 hours, shared with every other client. Developer Edition orgs get 15,000 requests. Enterprise Edition, and Professional Edition with API access, get 100,000 plus 1,000 for each Salesforce license. Unlimited and Performance editions get 100,000 plus 5,000 for each Salesforce license. See Salesforce's limits quick reference.
• Long requests: requests that take 20 seconds or longer are limited to 5 at a time in Developer Edition and trial orgs, and 25 in production orgs and sandboxes.
• Outbound messages: one message holds up to 100 records. See Understanding Notifications. Helios accepts messages up to 1 MB.