Create the OAuth App

To use the Conversation History API, create an OAuth-enabled external client app (ECA) or connected app. Salesforce recommends using an external client app starting in Spring ‘26.

Set up an external client app (ECA) to authenticate application calls to the Conversation History API.

  1. If you don’t have a self-signed certificate, follow the steps to Create a Private Key and Self-Signed Digital Certificate. Make sure you have the certificate saved in your system. You upload the file when you create the ECA.
  2. Create an external client app.
    1. In the External Client App Name field, enter a unique name for the external client app in the format {prefix} {externalClientAppName}, for example, Partner1 ExternalClientApp1. The {prefix} can be a partner name, and {externalClientAppName} is the name you specify for the external client app. Make sure that you note the prefix because it’s used for the developerName when you create the ConversationChannelDefinition record.
      The name you enter automatically appears in the API Name field in the format {prefix}_{externalClientAppName}. Don’t change the API Name.
    2. In the Contact Email field, enter the email address of the person to notify about the external client app, such as when a Salesforce admin views the consumer key for JWT generation. You can specify your email address as the contact email.
    3. Set the distribution state.
      1. To develop an external client app for your local org, set the Distribution State to Local.
      2. To develop an external client app for packaging and distribution, set the Distribution State to Packaged.
  3. In the OAuth Settings section, select Enable OAuth.
    The OAuth Settings area expands and the OAuth settings fields are visible.
  4. Add a callback URL (endpoint), which is the same as the OAuth redirect URI. We recommend you use https://login.salesforce.com to start with.
  5. Add the OAuth scope: Access Interaction API resources (interaction_api).
  6. In the Flow Enablement section, select Enable JWT Bearer Flow.
  7. Upload your self-signed certificate.
  8. To create the ECA, click Create.
  9. In your external client app’s Policies tab, click Edit.
  10. Under OAuth policies, from the Permitted Users dropdown, select Admin approved users are pre-authorized. If you see a warning message, click OK.
  11. Under App Policies, add the System Administrator profile.
  12. Save your changes.

Starting in Spring ’26, we recommend creating an external client app (ECA) to provide authentication for the integration between your platform and Salesforce instead of creating a connected app.

If you choose to create a connected app, before you begin, contact Salesforce Support to request the ability to create connected apps.

  1. Make sure you have the public key saved in your system. You must upload the file when you create the connected app. If you don’t have a self-signed certificate, see Create a Private Key and Self-Signed Digital Certificate.
  2. From Setup, in the Quick Find box, enter External Client Apps, and then select Settings.
  3. Under Connected Apps, turn on Allow creation of connected apps, and then click New Connected App.
  4. In the Connected App Name field, enter a unique name for the connected app. The name you enter automatically appears in the API Name field. Remember the API name because it’s used for the developerName when you Invoke Conversation History API.
  5. In the Contact Email field, enter the email address of the person to notify about the connected app, such as when a Salesforce admin views the consumer secret of the connected app. This entry can be your email address.
  6. Select the Enable OAuth Settings checkbox, and configure these settings:
    1. Add a callback URL (endpoint), which is the same as the OAuth redirect URI. We recommend you use https://salesforce.com to start with.
    2. Select Use digital signatures, then click Choose File and select the public key file in your system to upload it.
    3. Add the OAuth scopes:
      • Access Interaction API resources (interaction_api)
      • Perform Requests at any time (refresh_token, offline_access)
  7. Save your changes, then click Continue.
  8. From Setup, in the Quick Find box, enter Manage Connected Apps, and then select Manage Connected Apps.
  9. Click the name of the connected app you created.
  10. To open the Connected App Edit page, click Edit Policies.
  11. In the OAuth Policies section, set Permitted Users to Admin approved users are pre-authorized. If you see a warning message, click OK.
  12. Save your changes.
  13. To open the Application Profile Assignment page, click Manage Profiles.
  14. Select System Administrator.
  15. Save your changes.

See Also