Getting Started with Heroku AppLink and Agentforce

Introduction

Heroku AppLink (formerly Heroku Integration) exposes your Heroku apps as API services in Salesforce. This guide helps you set up the Heroku AppLink add-on via the Heroku CLI and the Heroku AppLink CLI plugin. To get some ideas of what you can use Heroku AppLink for, see the Use Cases section.

In this guide, we create and publish a Heroku app to Salesforce and execute the generated agent actions in Agentforce.

This guide assumes that you have:

• A verified Heroku account
• An Eco dynos plan subscription (recommended)
• All the dependencies based on your language of choice
• A Salesforce developer org, a Salesforce sandbox org, or a scratch org
• Agentforce enabled in your Salesforce org
• (Optional) Install the Salesforce CLI to work with your Salesforce org

{
 "orgName": "Acme",
 "edition": "Enterprise",
 "features": ["HerokuApplink","Einstein1AIPlatform"]
}

Install the Heroku AppLink Plugin

You must have the Heroku CLI installed before adding the Heroku AppLink CLI plugin. See Heroku CLI for instructions.

To install the plugin, run the CLI command:

$ heroku plugins:install @heroku-cli/plugin-applink

You can view the plugin info with the command:

$ heroku plugins:inspect @heroku-cli/plugin-applink
└─ @heroku-cli/plugin-applink
...
  ├─ commands
   │  ├─ applink:authorizations
   │  ├─ applink:authorizations:info
   │  ├─ applink:connections
   │  ├─ applink:connections:info
   │  ├─ datacloud:authorizations:add
   │  ├─ datacloud:authorizations:remove
   │  ├─ datacloud:connect
   │  ├─ datacloud:data-action-target:create
   │  ├─ datacloud:disconnect
   │  ├─ salesforce:authorizations:add
   │  ├─ salesforce:authorizations:remove
   │  ├─ salesforce:connect
   │  ├─ salesforce:connect:jwt
   │  ├─ salesforce:disconnect
   │  ├─ salesforce:publications
   │  └─ salesforce:publish
...

Prepare Your App

Create a local copy of the sample app by executing the following commands in your local command shell or terminal:

$ git clone -b https://github.com/heroku-examples/heroku-agentforce-tutorial-java
$ cd heroku-agentforce-tutorial-java

This Git repository contains a sample Java app with the following structure:

• api-spec.yaml: (Required) This sample API specification file lets you publish the app into Salesforce as an external service. We support OpenAPI 3.0. See External Services and OpenAPI for more info.
• BadgeCreator.java: This file provides functionality for generating custom badges with a logo, rotated text box, and text.
• Procfile: The Heroku Procfile that defines what’s executed by the app on startup. In the Procfile, heroku-applink-service-mesh starts the app.

Create Your App

To prepare Heroku to receive your source code, create an app:

$ heroku create
Creating app... done, ⬢ applink-agent-app
http://applink-agent-app.herokuapp.com/ | https://git.heroku.com/applink-agent-app.git

If you don’t specify a name, Heroku generates a random name for your app. In the guide, our app is called applink-agent-app.

Install the Heroku AppLink Buildpack

The Heroku Buildpack for Heroku AppLink Service Mesh installs the Heroku AppLink Service Mesh to handle the authentication and authorization for your app. The service mesh is a proxy in front of your app that intercepts incoming Salesforce and Data Cloud requests to validate and authenticate.

To install, run the command:

$ heroku buildpacks:add heroku/heroku-applink-service-mesh

Additionally, for the java project, set the heroku/java buildpack:

$ heroku buildpacks:add heroku/java
Buildpack added. Next release on applink- will use:
  1. https://github.com/heroku/heroku-buildpack-heroku-applink-service-mesh
  2. heroku/java
Run git push heroku main to create a new release using these buildpacks.

Provision the Heroku AppLink Add-on

To provision the add-on, run the command:

$ heroku addons:create heroku-applink
Creating heroku-applink on ⬢ applink-agent-app... free
Your add-on is being provisioned.
applink-regular-78506 is being created in the background. The app will restart when complete...
Use heroku addons:info applink-regular-78506 to check creation progress
Use heroku addons:docs applink-agent-app to view documentation

After provisioning, the add-on creates the config vars:

• HEROKU_APPLINK_URL: contains the base URL for the CLI to make requests
• HEROKU_APPLINK_TOKEN: contains the access token

You can get your config vars with the heroku config command:

$ heroku config
=== applink-agent-app Config Vars

HEROKU_APPLINK_API_URL: https://heroku-applink.heroku.com/addons/894792c1-c1e8-4f34-ba32-00000000000
HEROKU_APPLINK_TOKEN: af0a7e7984d4ef28948db6431dc036ae383fcb2f02064cbb0000000000000000

Deploy Your Heroku App

Next, deploy your app:

$ git push heroku main
...
2025-07-07T14:09:33.845077+00:00 heroku[web.1]: State changed from provisioning to starting
2025-07-07T14:09:49.304734+00:00 app[web.1]: time=2025-07-07T14:09:49.304Z level=INFO msg=environment app=applink-app source=heroku-applink-service-mesh go_version:=go1.24.3 os=linux arch=amd64 http_port=31835 version=v0.2.2 environment=local app_host=http://127.0.0.1 app_port=3000
2025-07-07T14:09:49.304754+00:00 app[web.1]: time=2025-07-07T14:09:49.304Z level=INFO msg="Heroku AppLink Service Mesh is up!" app=applink-app source=heroku-applink-service-mesh port=31835
2025-07-07T14:09:49.833835+00:00 app[web.1]:
2025-07-07T14:09:49.833839+00:00 app[web.1]: > applink-app@1.0.0 start
2025-07-07T14:09:49.833840+00:00 app[web.1]: > fastify start -o -a 0.0.0.0 -p $APP_PORT -l debug src/app.js
2025-07-07T14:09:49.833840+00:00 app[web.1]:
2025-07-07T14:09:50.482717+00:00 heroku[web.1]: State changed from starting to up
2025-07-07T14:09:51.111131+00:00 app[web.1]: {"level":30,"time":1751897391110,"pid":63,"hostname":"dyno-bcad42a8-33d4-447f-9adb-0000000000","msg":"Server listening at http://0.0.0.0:3000"}
...
remote: Verifying deploy... done.
To https://git.heroku.com/applink-app.git
 * [new branch]      main -> main

See Deployment for other options for deploying Heroku apps.

Assign User Permissions

To perform operations with Heroku AppLink, you must have deploy or operate permissions in Heroku, or be the owner of the Heroku app. To configure Agentforce, you must also give your user the user permissions needed to Create a Custom Agent Action.

You must also have the Heroku AppLink permission in Salesforce. To add the permission in Salesforce, create a permission set in Salesforce:

1. From Salesforce Setup, in the Quick Find box, enter and select Permission Sets.
2. Select New and give the permission set a name.
3. Select Save.
4. In the Find Settings… box, enter and select Manage Heroku AppLink.
5. At the top of the Systems Permissions page, select Edit.
6. Select the checkbox next to Manage Heroku AppLink and select Save, and Save again.
7. On the navigation bar of the Systems Permissions page, select Manage Assignments.
8. Select Add Assignments.
9. Select the checkbox next to the user you want to add the permission set to, select Next, then Assign.

Connect to Salesforce

Next, create a connection to your Salesforce org with the command:

$ heroku salesforce:connect agent-org --addon applink-regular-78506 -a applink-agent-app
Opening browser to https://login.salesforce.com/services/oauth2/authorize?client_id=…
Press any key to open up the browser to connect ⬢ applink-agent-app to agent-org, or q to exit:
Connecting Salesforce org agent-org to ⬢ applink-agent-app... Connected

To view the info on your connection, run the command:

$ heroku applink:connections:info agent-org -a applink-agent-app --addon applink-regular-78506

=== agent-org on ⬢ app applink-agent-app
Connection Type:  Salesforce Org
Created By:       admin@heroku.com
Created Date:     2025-05-30T18:55:42.863808Z
Id:               127291fa-34c6-4a31-9e19-4dbdfed243af
Instance URL:     https://login.test1.my.pc-rnd.salesforce.com
Last Modified:    2025-05-30T18:56:02.282284Z
Last Modified By: admin@heroku.com
Org ID:           00Dbc0000000000000
Status:           Connected

Publish Your Heroku App

You can publish your app to Salesforce as an external service and then use those external service actions in Agentforce. To publish your app, run the command:

$ heroku salesforce:publish api-spec.json --client-name BadgeService --connection-name agent-org --authorization-connected-app-name BadgeServiceConnectedApp --authorization-permission-set-name BadgeServicePermissions

Publishing ⬢ applink-agent-app to agent-org as BadgeService via https://applink.herokudev.com/addons/1c6bb699-2a91-47b3-b55e-8f2e37254684/connections/salesforce/agent-org/apps... done

The --authorization-permission-set-name flag creates a permission set called BadgeServicePermissions. Assign this permission set to your invoking users to control access to your app from the org.

After publishing your app, you can see the app and its input and output parameters from Salesforce Setup. From the setup page:

1. Search for Heroku in the Quick Find and select Apps.
2. Select the app you published.

If publishing your app fails, review the Deployment Status in the Salesforce Setup for more details.

To view the info on your publication, run the command:

$ heroku salesforce:publications -a applink-agent-app
=== Salesforce publications for app ⬢ applink-agent-app
Connection Name  Org ID             Created Date          Created By      Last Modified         Last Modified By
──────────────── ────────────────── ──────────────────── ──────────────── ───────────────────── ────────────
agent-org            00Dbc0000000000000 2025-05-30T17:34:56Z  admin@heroku.com  2025-05-30T17:34:56Z    Admin Heroku

View Logs

You can view your app’s logs with heroku logs –tail:

$ heroku logs --tail
---
2024-10-28T16:02:15.215250+00:00 app[web.1]: time=2024-10-28T16:02:15.215Z level=INFO msg="Processing request to /accounts..." app=local source=heroku-applink-service-mesh request-id=00Dbc0000000000000-f2f3ed60-2dbd-4edd-b707-9dee97d89c7c
...
2024-10-28T16:02:15.215332+00:00 app[web.1]: time=2024-10-28T16:02:15.215Z level=INFO msg="Authenticating Salesforce request for org 00Dbc0000000000000, domain https://mydomain.demo.my.salesforce.com..." app=local source=heroku-applink-service-mesh request-id=00Dbc0000000000000-f2f3ed60-2dbd-4edd-b707-9dee97d89c7c
...
2024-10-28T16:02:15.398893+00:00 app[web.1]: {"level":30,"time":1730131335396,"pid":37,"hostname":"dyno-f34267e3-3d00-453d-a3b4-a16ab26a773b","reqId":"00Dbc0000000000000-f2f3ed60-2dbd-4edd-b707-9dee97d89c7c","msg":"Querying invoking org (00Dbc0000000000000) Accounts..."}
...
2024-10-28T16:02:15.482442+00:00 app[web.1]: {"level":30,"time":1730131335482,"pid":37,"hostname":"dyno-f34267e3-3d00-453d-a3b4-a16ab26a773b","reqId":"00Dbc0000000000000-f2f3ed60-2dbd-4edd-b707-9dee97d89c7c","res":{"statusCode":200},"responseTime":86.56547299958766,"msg":"request completed"}

Create an Agentforce Action

To create an agent action:

1. From Salesforce Setup, in the Quick Find box, enter and select Agentforce Actions.
2. Select the Actions tab, then New Agent Action.

3. Configure the action with the fields and values and select Next.

   Field	Value
   Reference Action Type	API
   Reference Action Category	Heroku
   Reference Action	Generate Badge
   Agent Action Label	Generate Badge
   Agent Action API Name	Generate_Badge

4. In the instructions window, fill out the following fields:

   Field	Value
   Agent Action Instructions	Use this action in response to requests for a Heroku badge with a name on it.
   Input - Instructions	Name to be placed on the badge.
   Input - Collect data from user	Selected
   Output - Instructions	This is the Heroku badge the user requested.
   Output - Filter from agent action	Deselected
   Output - Show in conversation	Selected
   Output - Output Rendering	Rich Text

5. Select Finish.

Invoke Your Published App Actions with Agentforce

Next, add the action you created to an agent:

1. From Salesforce Setup, in the Quick Find box, enter and select Agentforce Agents.
2. In the Enable the Agentforce (Default) Agent section, turn on the toggle to enable the default Agentforce (Default) agent.
3. Open the dropdown for the Agentforce (Default) agent and select Open in Builder.
4. Select Deactivate in the top right of the window if it’s there.
5. In the Topics tab, select New and Add from Asset Library.
6. Search for and add the General CRM topic, then Finish.
7. Select the General CRM topic, then New Version.
8. Select the Topic Configuration tab and add Also including requests for badges. in the current Classification Description field, then Save.
9. Select the This Topic's Actions tab, then New and Add from Asset Library.
10. Search for and add the action you created, Generate Badge, then Finish.
11. Select Activate in the top right of the screen.

Now you can test the action in your agent. In the Conversation Preview panel, enter Generate a badge for Astro or try it out with your own example.

Delete Your Connections, Authorizations, Published Apps, and Add-on

Remove Your Connection

To remove a connection from a Salesforce org, run the command:

$ heroku salesforce:disconnect agent-org -a applink-agent-app
 ›   Warning: Destructive action
 ›   This command disconnects the connection agent-org from add-on applink-regular-78506 on app ⬢ applink-agent-app.
 ›
To proceed, type agent-org or re-run this command with --confirm agent-org: agent-org

Disconnecting Salesforce org agent-org from applink-agent-app ... done

Delete Your Published App

Delete your published app from Salesforce by selecting the arrow in the service’s Actions column, and selecting Delete. You can also select Delete on the published app page.

Remove Your Add-on

To remove your Heroku AppLink add-on, run the command:

$ heroku addons:destroy heroku-applink

Additional Reading

Try our other Heroku AppLink getting started guides:

• Getting Started with Heroku AppLink and Salesforce
• Getting Started with Heroku AppLink and Data Cloud

Here’s some recommended reading:

• Heroku AppLink category
• Heroku AppLink Integration Patterns
• Getting Started with Heroku Events (Pilot)