Skip to main content

Actions - Request vs. Callback Actions

There are two types of actions. You may think of them as twins, but they’re fraternal not identical. This doc will explain how.

Every action shares a common set of properties, like name. The way the two action types differ is in the specification of how they do their job.

Request Actions​

Request actions leverage an API endpoint. That might be a public API endpoint that you make available to customers, or an internal API endpoint. Either way, the “business logic” of a request action is calling an API endpoint with a payload that you can shape within the CommandBar studio.

When should I use a request action?​

The nice thing about a request action is that it requires no code; you can create the full action end-to-end from the Studio, so long as you know the API endpoint needed and the payload you need to provide to it, so it can do its thing.

Callback Actions​

Callback actions are very similar to request actions, except that they use JavaScript provided to CommandBar in place of an API endpoint. This usually means a couple of things:

  1. You’ll need a developer to add some code (specifically a CommandBar.addCallback call) to supply the callback to CommandBar. This needs to happen before the action will work for end users.
  2. Your developer will also need to tell you what payload the callback expects to receive. Callbacks are usually more poorly documented than API endpoints.

When should I use a callback action?​

If no API endpoint exists for the action you want to create, then you probably need to use a callback action and should get a developer involved to figure out which one is best for your purpose. You might need the developer to write a new custom callback. (But fear not! This often involves just repackaging some pre-existing logic).

Another sign that you need to use a callback action is if you want the UI to change immediately in response to the action. For example, take an action to add seats. For this, you probably don’t need the UI to respond to the user’s action. It’s probably sufficient for Copilot to tell them “You successfully added seats!”

Take an action like “Add an element to my canvas”. If you’re in the canvas, you probably expect the element to appear in the canvas, which you’re looking at, after it completes. In this case, a callback is probably warranted.

(Technical note: there are some situations in which an API request action will be able to update the UI. The most common one is if your application uses WebSockets to update the UI in response to backend changes).