Skip to content

Unofficial, Reverse-Engineered Node.js/TypeScript client for Meta's Threads. Supports Read and Write. Web UI Included.

License

Notifications You must be signed in to change notification settings

kodingkeun/threads-api

Β 
Β 

Repository files navigation

Threads API

NPM MIT License Prettier Code Formatting

Unofficial, Reverse-Engineered Node.js/TypeScript client for Meta's Threads.

threads-api in Action

cover

✨ The App Registry is officially live! We invite you to explore it on our website at threads.junho.io.
Modify threads-web-ui/data/apps.ts to add your projects!

cover

πŸš€ Usage (Read)

Read: Public

import { ThreadsAPI } from 'threads-api';

// or in Deno πŸ¦–:
// import ThreadsAPI from "npm:threads-api";

const main = async () => {
  const threadsAPI = new ThreadsAPI();

  const username = '_junhoyeo';

  // πŸ‘€ Details for a specific user
  const userID = await threadsAPI.getUserIDfromUsername(username);
  if (!userID) {
    return;
  }
  const user = await threadsAPI.getUserProfile(userID);
  console.log(JSON.stringify(user));
  const posts = await threadsAPI.getUserProfileThreads(userID);
  console.log(JSON.stringify(posts));
  const replies = await threadsAPI.getUserProfileReplies(userID);
  console.log(JSON.stringify(replies));

  // πŸ“– Details for a specific thread
  const postID = threadsAPI.getPostIDfromURL(
    'https://www.threads.net/t/CuX_UYABrr7/?igshid=MzRlODBiNWFlZA==',
  );
  // or use `threadsAPI.getPostIDfromThreadID('CuX_UYABrr7')`
  if (!postID) {
    return;
  }
  const post = await threadsAPI.getThreads(postID);
  console.log(JSON.stringify(post.containing_thread));
  console.log(JSON.stringify(post.reply_threads));

  const likers = await threadsAPI.getThreadLikers(postID);
  console.log(JSON.stringify(likers));
};
main();

Read: Private(Auth Required)

πŸ’‘ Get Timeline
const { items: threads, next_max_id: cursor } = await threadsAPI.getTimeline();
console.log(JSON.stringify(threads));
πŸ’‘ Get Threads/Replies from a User (with pagination)
const { threads, next_max_id: cursor } = await threadsAPI.getUserProfileThreadsLoggedIn(userID);
console.log(JSON.stringify(threads));
const { threads, next_max_id: cursor } = await threadsAPI.getUserProfileRepliesLoggedIn(userID);
console.log(JSON.stringify(threads));
πŸ’‘ Get Followers/Followings of a User (with Pagination)
const { users, next_max_id: cursor } = await threadsAPI.getUserFollowers(userID);
console.log(JSON.stringify(users));
const { users, next_max_id: cursor } = await threadsAPI.getUserFollowings(userID);
console.log(JSON.stringify(users));

πŸš€ Usage (Write)

Note
From v1.4.0, you can also call login to update your token and userID(for current credentials). Or you can just use the methods below, and they'll take care of the authentication automatically (e.g. if it's the first time you're using those).

New API (from v1.2.0)

✨ Text Threads
import { ThreadsAPI } from 'threads-api';

const main = async () => {
  const threadsAPI = new ThreadsAPI({
    username: '_junhoyeo', // Your username
    password: 'PASSWORD', // Your password
  });

  await threadsAPI.publish({
    text: 'πŸ€– Hello World',
  });
};

main();

Writing Text Threads

πŸ’‘ TIP: Use the url field in ThreadsAPIPublishOptions to render Link Attachments(link previews).

✨ Reply Control (from v1.4.6)
await threadsAPI.publish({
  text: 'πŸ€– Threads with Reply Control',
  replyControl: 'accounts_you_follow', // 'everyone' | 'accounts_you_follow' | 'mentioned_only'
});
✨ Threads with Link Attachment
await threadsAPI.publish({
  text: 'πŸ€– Threads with Link Attachment',
  attachment: {
    url: 'https://github.com/junhoyeo/threads-api',
  },
});
✨ Threads with Image
await threadsAPI.publish({
  text: 'πŸ€– Threads with Image',
  attachment: {
    image: 'https://github.com/junhoyeo/threads-api/raw/main/.github/cover.jpg',
  },
});

ThreadsAPI.Image in attachment.image can also be type of ThreadsAPI.ExternalImage or ThreadsAPI.RawImage.

✨ Threads with Sidecar (Multiple Images)

Info
The term "sidecar" is what Threads uses to represent a group of images and/or videos that share the same post.

await threadsAPI.publish({
  text: 'πŸ€– Threads with Sidecar',
  attachment: {
    sidecar: [
      'https://github.com/junhoyeo/threads-api/raw/main/.github/cover.jpg',
      'https://github.com/junhoyeo/threads-api/raw/main/.github/cover.jpg',
      { path: './zuck.jpg' }, // ThreadsAPI.ExternalImage
      { type: '.jpg', data: Buffer.from(…) }, // ThreadsAPI.RawImage
    ],
  },
});
✨ Reply to Other Threads
const parentURL = 'https://www.threads.net/t/CugF-EjhQ3r';
const parentPostID = threadsAPI.getPostIDfromURL(parentURL); // or use `getPostIDfromThreadID`

await threadsAPI.publish({
  text: 'πŸ€– Beep',
  link: 'https://github.com/junhoyeo/threads-api',
  parentPostID: parentPostID,
});

Writing Text Threads

✨ Quote a Thread (from v1.4.2)
const threadURL = 'https://www.threads.net/t/CuqbBI8h19H';
const postIDToQuote = threadsAPI.getPostIDfromURL(threadURL); // or use `getPostIDfromThreadID`

await threadsAPI.publish({
  text: 'πŸ€– Quote a Thread',
  quotedPostID: postIDToQuote,
});
✨ Like/Unlike a Thread (from v1.3.0)
const threadURL = 'https://www.threads.net/t/CugK35fh6u2';
const postIDToLike = threadsAPI.getPostIDfromURL(threadURL); // or use `getPostIDfromThreadID`

// πŸ’‘ Uses current credentials
await threadsAPI.like(postIDToLike);
await threadsAPI.unlike(postIDToLike);
✨ Follow/Unfollow a User (from v1.3.0)
const userIDToFollow = await threadsAPI.getUserIDfromUsername('junhoyeo');

// πŸ’‘ Uses current credentials
await threadsAPI.follow(userIDToFollow);
await threadsAPI.unfollow(userIDToFollow);
✨ Repost/Unrepost a Thread (from v1.4.2)
const threadURL = 'https://www.threads.net/t/CugK35fh6u2';
const postIDToRepost = threadsAPI.getPostIDfromURL(threadURL); // or use `getPostIDfromThreadID`

// πŸ’‘ Uses current credentials
await threadsAPI.repost(postIDToRepost);
await threadsAPI.unrepost(postIDToRepost);
✨ Delete a Post (from v1.3.1)
const postID = await threadsAPI.publish({
  text: 'πŸ€– This message will self-destruct in 5 seconds.',
});

await new Promise((resolve) => setTimeout(resolve, 5_000));
await threadsAPI.delete(postID);

🏚️ Old API (Deprecated from v1.5.0, Still works for backwards compatibility)

image and url options in publish
✨ Threads with Image
await threadsAPI.publish({
  text: 'πŸ€– Threads with Image',
  image: 'https://github.com/junhoyeo/threads-api/raw/main/.github/cover.jpg',
});
✨ Threads with Link Attachment
await threadsAPI.publish({
  text: 'πŸ€– Threads with Link Attachment',
  url: 'https://github.com/junhoyeo/threads-api',
});

🏚️ Old API (Deprecated from v1.2.0, Still works for backwards compatibility)

Single string argument in publish
import { ThreadsAPI } from 'threads-api';

const main = async () => {
  const threadsAPI = new ThreadsAPI({
    username: 'jamel.hammoud', // Your username
    password: 'PASSWORD', // Your password
  });

  await threadsAPI.publish('πŸ€– Hello World');
};

main();

You can also provide custom deviceID (Default is android-${(Math.random() * 1e24).toString(36)}).

const deviceID = `android-${(Math.random() * 1e24).toString(36)}`;

const threadsAPI = new ThreadsAPI({
  username: 'jamel.hammoud',
  password: 'PASSWORD',
  deviceID,
});

Installation

yarn add threads-api
# or with npm
npm install threads-api
# or with pnpm
pnpm install threads-api
// or in Deno πŸ¦–
import ThreadsAPI from 'npm:threads-api';

const threadsAPI = new ThreadsAPI.ThreadsAPI({});

Roadmap

  • βœ… Read public data
    • βœ… Fetch UserID(314216) via username(zuck)
    • βœ… Read timeline feed
    • βœ… Read User Profile Info
    • βœ… Read list of User Threads
      • βœ… With Pagination (If auth provided)
    • βœ… Read list of User Replies
      • βœ… With Pagination (If auth provided)
    • βœ… Fetch PostID(3140957200974444958) via ThreadID(CuW6-7KyXme) or PostURL(https://www.threads.net/t/CuW6-7KyXme)
    • βœ… Read Threads via PostID
    • βœ… Read Likers in Thread via PostID
    • βœ… Read User Followers
    • βœ… Read User Followings
  • βœ… Write data (i.e. write automated Threads)
    • βœ… Create new Thread with text
      • βœ… Make link previews to get shown
    • βœ… Create new Thread with a single image
    • βœ… Create new Thread with multiple images
    • βœ… Reply to existing Thread
    • βœ… Quote Thread
    • βœ… Delete Thread
  • βœ… Friendships
    • βœ… Follow User
    • βœ… Unfollow User
  • βœ… Interactions
    • βœ… Like Thread
    • βœ… Unlike Thread
  • πŸ΄β€β˜ οΈ Restructure the project as a monorepo
    • πŸ΄β€β˜  Add Demo App with Next.js
    • πŸ΄β€β˜ οΈ Cool CLI App to run Threads in the Terminal

Projects made with threads-api

Add yours by just opening an pull request!

NPM MIT License Prettier Code Formatting

Embed Static Threads in your React/Next.js application. UI components for Meta's Threads. Powered by junhoyeo/threads-api.

cover

Demo

Warning
Vercel Deployment is currently sometimes unstable. πŸ΄β€β˜ οΈ

cover

πŸ΄β€β˜ οΈ threads-api CLI (WIP)

To use the threads-api command line interface, run the following command:

$ npx threads-api --help
Usage: threads-api [command] [options]

Options:
  -v, --version                                                                   output the current version
  -h, --help                                                                      display help for command

Commands:
  help                                                                            display help for command
  getUserIDfromUsername|userid|uid|id <username>                                  det user ID from username
  getUserProfile|userprofile|uprof|up <username> <userId> [stringify]             get user profile
  getUserProfileThreads|uthreads|ut <username> <userId> [stringify]               get user profile threads
  getUserProfileReplies|userreplies|ureplies|ur <username> <userId> [stringify]   get user profile replies
  getPostIDfromURL|postid|pid|p <postURL>                                         get post ID from URL
  getThreads|threads|t <postId> [stringify]                                       get threads
  getThreadLikers|threadlikers|likers|l <postId> [stringify]                      get thread likers

Screenshot (84)

parameter demo
Default (_junhoyeo's account) _junhoyeo Badge
Custom Text and Colors Alternative Count Badge
Scale Badge Size https://www.threads.net/@zuck

License

MIT Β© Junho Yeo

If you find this project intriguing, please consider starring it(⭐) or following me on GitHub (I wouldn't say Threads). I code 24/7 and ship mind-breaking things on a regular basis, so your support definitely won't be in vain.

About

Unofficial, Reverse-Engineered Node.js/TypeScript client for Meta's Threads. Supports Read and Write. Web UI Included.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 95.1%
  • JavaScript 3.0%
  • CSS 1.9%