How to post a link with embed card on Bluesky with JavaScript

As Bluesky continues to gain popularity, more tools are being developed around it. One of the most popular applications is post scheduling and automation.

However, Bluesky's API currently doesn't offer a direct way to post links with OpenGraph cards. This can be a challenge for users who want to share links with attractive previews.

In this tutorial, we'll show you how to use JavaScript to post a link on Bluesky with a embed card. This method works around the API limitation, allowing you to share links more effectively.

Let's get started!

Posting on Bluesky using JavaScript API

Working with Bluesky API is pretty simple. The docs are pretty good. First up, we need to install the @atproto/api package from NPM:

npm install @atproto/api

Next, we create an instance of the Bluesky Agent and login with your Bluesky credencials.

I recommend creating a new App Password for your Bluesky account, rather than using your main password. This will make it easier to revoke access if needed and keep your main account secure. Also make sure to set the BLUESKY_USERNAME and BLUESKY_PASSWORD environment variables in your project.

import { AtpAgent } from "@atproto/api"

const getBlueskyAgent = async () => {
  const agent = new AtpAgent({
    service: "https://bsky.social",
  })

  await agent.login({
    identifier: process.env.BLUESKY_USERNAME!,
    password: process.env.BLUESKY_PASSWORD!,
  })

  return agent
}

Once you have the agent, you can use it to post to Bluesky which is pretty straightforward.

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string, url?: string) => {
  const agent = await getBlueskyAgent()

  await agent.post({ text })
}

And there you have it, you just sent a post to Bluesky. Unfortunately, even if you include a link in the text of your post, it isn't automatically converted into an anchor link. We'll fix that shortly.

Detect Faceted Links on Bluesky Automatically

When you include a link in your post text on Bluesky, it isn't automatically turned into an anchor link. Instead, it appears as plain text.

To fix this, you need to detect the links and convert them into faceted links.

While there are manual methods to achieve this, fortunately, ATProto provides a RichText class that can automatically detect links and convert them into faceted links.

import { RichText } from "@atproto/api"

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string) => {
  const agent = await getBlueskyAgent()
  const rt = new RichText({ text })
  await rt.detectFacets(agent)

  await agent.post({
    text: rt.text,
    facets: rt.facets,
  })
}

That's great, but we still need to add the embed card to the post. Let's do that next.

Creating an Embed Card on Bluesky

Including a link in your post is great, but it's even better if you can add a embed card.

To achieve this, we need to use the Website card embed feature of Bluesky. Essentially, you add an embed key to your post that includes, at a minimum, a URL, title, and description.

There are several ways to obtain the required data. If you know it at the time of posting, you can simply hardcode it. Otherwise, you can scrape the URL to gather the title, description, and image.

However, I find the easiest way is to use the Dub.co Metatags API to fetch the URL metadata and then create the embed card from that. Let's see how that works.

npm install @atproto/api

We created a simple function that fetches the URL metadata and then returns the data in a clear format.

Next, let's create a function that uses the metadata to upload the image to Bluesky and then create the embed card.

import { AtpAgent } from "@atproto/api"

const getBlueskyAgent = async () => {
  const agent = new AtpAgent({
    service: "https://bsky.social",
  })

  await agent.login({
    identifier: process.env.BLUESKY_USERNAME!,
    password: process.env.BLUESKY_PASSWORD!,
  })

  return agent
}

Once we have the embed card, we can add it to the post.

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string, url?: string) => {
  const agent = await getBlueskyAgent()

  await agent.post({ text })
}

Now we have a function that sends a post to Bluesky with an embed card.

Complete Example

Hopefully, if you have followed along, you should have a complete code by now. If not, here is the complete code that you can copy and paste into your project. It:

• Creates a Bluesky agent
• Fetches the URL metadata
• Creates an embed card
• Sends a post to Bluesky with the embed card and automatically detects faceted links

import { RichText } from "@atproto/api"

/**
 * Send a post to Bluesky
 * @param text - The text of the post
 */
export const sendBlueskyPost = async (text: string) => {
  const agent = await getBlueskyAgent()
  const rt = new RichText({ text })
  await rt.detectFacets(agent)

  await agent.post({
    text: rt.text,
    facets: rt.facets,
  })
}

I hope you found this tutorial helpful and that you will consider using it in your own projects.

Happy posting!

The above is the detailed content of How to post a link with embed card on Bluesky with JavaScript. For more information, please follow other related articles on the PHP Chinese website!