threads-ts

A TypeScript SDK for the Threads API, making it easy to interact with Threads in your TypeScript/JavaScript projects.

Official Threads Documentation:

https://developers.facebook.com/docs/threads

Table of Contents

• Installation
• Usage
• API Reference
• Contributing
• License

Installation

Install the package using npm:

npm install threads-ts

Or using yarn:

yarn add threads-ts

Usage

First, import and initialize the ThreadsAPI class:

import { ThreadsAPI, ThreadsAPIConfig } from "threads-ts";

import { env } from "@/env.mjs";

const config: ThreadsAPIConfig = {
	clientId: env.THREADS_APP_ID,
	clientSecret: env.THREADS_APP_SECRET,
	redirectUri: env.CALLBACK_URL,
	scope: [
		"threads_basic",
		"threads_content_publish",
		"threads_manage_replies",
		"threads_read_replies",
		"threads_manage_insights",
	],
};

export const threads = new ThreadsAPI(config);

Authentication

Generate an authorization URL:

const authUrl = threadsAPI.getAuthorizationUrl();
console.log('Authorize your app:', authUrl);

Exchange the authorization code for an access token:

const code = 'AUTHORIZATION_CODE';

// Get the short lived token
const { access_token: shortLivedToken } = await threads.getAccessToken(code);
// Convert the short lived token to a long term access token
const { access_token: accessToken, expires_in: expiresIn } = await threads.getLongLivedToken(shortLivedToken);

// Store the access token in your db

// Now we can do stuff like get the User profile
const profile = await threads.getUserProfile({
	userId: "me",
	fields: ["id", "username", "name", "threads_profile_picture_url"],
});

Creating and Publishing a Thread

const userId = 'USER_ID';

// Create a media container
const creationId = await threadsAPI.createMediaContainer({
  userId,
  mediaType: 'TEXT',
  text: 'Hello, Threads!'
});

// Publish the media container
const threadId = await threadsAPI.publishMediaContainer({
  userId,
  creationId
});

console.log('Published Thread ID:', threadId);

Retrieving User Threads

const userId = 'USER_ID';
const fields = ['id', 'text', 'username', 'timestamp'];

const userThreads = await threadsAPI.getUserThreads({
  userId,
  fields,
  options: { limit: 10 }
});

console.log('User Threads:', userThreads);

Retrieving User Profile

const userId = 'USER_ID';
const fields = ['id', 'username', 'name', 'threads_profile_picture_url'];

const userProfile = await threadsAPI.getUserProfile({
  userId,
  fields
});

console.log('User Profile:', userProfile);

Retrieving Replies to a Thread

const mediaId = 'THREAD_ID';
const fields = ['id', 'text', 'username', 'timestamp'];

const replies = await threadsAPI.getReplies({
  mediaId,
  fields
});

console.log('Replies:', replies);

Responding to a Reply

const userId = 'USER_ID';
const replyToId = 'THREAD_ID_TO_REPLY_TO';

const replyId = await threadsAPI.respondToReply({
  userId,
  mediaType: 'TEXT',
  text: 'This is my response!',
  replyToId
});

console.log('Reply ID:', replyId);

Retrieving Media Insights

const mediaId = 'THREAD_ID';
const metrics = ['engagement', 'impressions', 'reach'];

const insights = await threadsAPI.getMediaInsights({
  mediaId,
  metrics
});

console.log('Media Insights:', insights);

API Reference

For a complete list of available methods and their parameters, please refer to the API documentation.

Contributing

We welcome contributions to the threads-ts SDK! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Acknowledgements

• Thanks to the Threads team for providing the API
• All the contributors who have helped improve this SDK

---

Made with ❤️ by solojungle