Skip to content
FrogUI

Cast Actions

Cast Actions let developers create custom buttons which users can install into their action bar on any Farcaster application (see the spec).

Overview

At a glance:

  1. User installs Cast Action via specific deeplink or by clicking on <Button.AddCastAction> element with a specified target .castAction route in a Frame.
  2. When the user presses the Cast Action button in the App, the App will make a POST request to the .castAction route.
  3. Frame performs any action and returns a response to the App.

Walkthrough

Here is a trivial example on how to expose an action with a frame. We will break it down below.

1. Render Frame & Add Action Intent

In the example above, we are rendering Add Action intent:

  1. action property is used to set the path to the cast action route.
  2. name property is used to set the name of the action. It must be less than 30 characters
  3. icon property is used to associate your Cast Action with one of the Octicons. You can see the supported list here.
src/index.tsx
app.frame('/', (c) => {
  return c.res({
    image: (
      <div style={{ color: 'white', display: 'flex', fontSize: 60 }}>
        Add "Log this!" Action
      </div>
    ),
    intents: [
      <Button.AddCastAction
        action="/log-this"
        name="Log This!"
        icon="log"
      >
        Add
      </Button.AddCastAction>,
    ]
  })
})
 
// ...

2. Handle /log-this Requests

Without a route handler to handle the Action request, the Cast Action will be meaningless.

Thus, let's define a /log-this route to handle the the Cast Action:

src/index.tsx
app.frame('/', (c) => {
  return c.res({
    image: (
      <div style={{ color: 'white', display: 'flex', fontSize: 60 }}>
        Add "Log this!" Action
      </div>
    ),
    intents: [
      <Button.AddCastAction
        action="/log-this"
        name="Log This!"
        icon="log"
      >
        Add
      </Button.AddCastAction>,
    ]
  })
})
 
app.castAction('/log-this', (c) => {
  console.log(
    `Cast Action to ${JSON.stringify(c.actionData.castId)} from ${
      c.actionData.fid
    }`,
  )
  return c.res({ message: 'Action Succeeded' })
})

A breakdown of the /log-this route handler:

  • c.actionData is never nullable and is always defined since Cast Actions always do POST request.
  • We are responding with a c.res response and specifying a message that will appear in the success toast.

:::

5. Bonus: Learn the API

You can learn more about the transaction APIs here: