threads-graph-api
v0.1.0
Published
A library to interface with the official Instagram Threads API
Downloads
75
Maintainers
Readme
threads-graph-api
A Javascript library to interface with the official Instagram Threads API. Built by Spool, a Threads creator toolkit with AI-assisted content generation, seamless cross-platform posting, advanced post composing, and more!
Maintainers: @tonypeng, @ishaanbuildsthings
⚠️ Warning!
This is an unstable early preview release. Some endpoints may not work and the API is subject to change. Please submit an issue or a pull request if you encounter any issues.
Overview
The threads-graph-api
repository provides a TypeScript client for interacting with the Instagram Threads API. This library simplifies the process of accessing Instagram's public and authenticated endpoints for managing media, retrieving user profiles, metrics, and more.
Installation
Install the package with your favorite package manager:
$ yarn add threads-graph-api
or
$ npm install threads-graph-api
Usage
threads-graph-api
follows the official Threads API documentation for endpoints and parameters. See types.ts for all request and response schemas.
Initializing the Client
There are two types of clients provided by the library:
ThreadsPublicApiClient
ThreadsAuthenticatedApiClient
Public API Client
The ThreadsPublicApiClient
allows access to endpoints that do not require authentication.
import {ThreadsPublicApiClient} from 'threads-graph-api';
const baseUrl = 'https://graph.threads.net';
const publicClient = new ThreadsPublicApiClient(
baseUrl, // optional
);
Authenticated API Client
The ThreadsAuthenticatedApiClient
allows access to endpoints that require authentication.
import {ThreadsAuthenticatedApiClient} from 'threads-graph-api';
const accessToken = 'your-access-token';
const userId = 'your-user-id';
const baseUrl = 'https://graph.threads.net'; // you can set this to your own server for testing
const authenticatedClient = new ThreadsAuthenticatedApiClient(
accessToken,
userId,
baseUrl, // optional
);
Authentication
Creating Authorization URL
To create an authorization URL:
const clientId = 'your-client-id';
const redirectUri = 'your-redirect-uri';
const scope = ['threads_basic', ...];
const baseUrl = 'https://www.threads.net'; // you can set this to your own server for testing
const authUrl = publicClient.createAuthorizationUrl(
clientId,
redirectUri,
scope,
baseUrl, // optional
);
Exchanging an Authorization Code
To exchange an authorization code for an access token:
const clientSecret = 'your-client-secret';
const code = 'auth-code';
const response = await publicClient.exchangeAuthorizationCode(clientId, clientSecret, redirectUri, code);
Using the API
Creating a media container
To create a media container:
const params = {
mediaType: 'TEXT',
text: 'Hello, World!',
};
const response = await authenticatedClient.createMediaContainer(params);
Publishing media
To publish a media container:
const params = {
creationId: 'media-creation-id',
};
const response = await authenticatedClient.publish(params);
Getting a user's threads
To get user threads:
const params = {
id: 'user-id',
fields: ['id', 'media_type', 'media_url'],
};
const response = await authenticatedClient.getUserThreads(params);
Getting a media object
To get a media object:
const params = {
id: 'media-id',
fields: ['id', 'media_type', 'media_url'],
};
const response = await authenticatedClient.getMediaObject(params);
Getting a user's profile
To get a user's profile:
const params = {
id: 'user-id',
fields: ['id', 'username', 'threads_profile_picture_url'],
};
const response = await authenticatedClient.getUserProfile(params);
Getting a user's threads publishing limit
To get a user's threads publishing limit:
const params = {
id: 'user-id',
fields: ['reply_quota_usage', 'reply_config'],
};
const response = await authenticatedClient.getUserThreadsPublishingLimit(params);
Getting thread replies
To get a thread's replies:
const params = {
id: 'media-id',
fields: ['id', 'text', 'username'],
reverse: true,
};
const response = await authenticatedClient.getReplies(params);
Getting a thread conversation
To get a thread's conversation:
const params = {
id: 'conversation-id',
fields: ['id', 'text', 'username'],
reverse: true,
};
const response = await authenticatedClient.getConversation(params);
Managing a reply
To manage a reply:
const params = {
id: 'reply-id',
hide: true,
};
const response = await authenticatedClient.manageReply(params);
Getting media metrics
To get media metrics:
const params = {
id: 'media-id',
metrics: ['views', 'likes'],
};
const response = await authenticatedClient.getMediaMetrics(params);
Getting account metrics
To get account metrics:
const params = {
id: 'user-id',
metrics: ['followers_count'],
};
const response = await authenticatedClient.getAccountMetrics(params);
Handling errors
The ThreadsApiError
class is thrown when the Threads API returns an error. The message
field of the returned error is accessible from the error
field on the ThreadsApiError
object. To access other fields, use getThreadsError()
to retrieve the full error object returned by the Threads API:
try {
const response = await authenticatedClient.getUserProfile(params);
} catch (error) {
if (error instanceof ThreadsApiError) {
console.error('Threads API Error:', error.message, error.getThreadsError());
} else {
console.error('Unexpected Error:', error);
}
}
Contributing
Contributions are welcome (and encouraged)! Please open an issue or submit a pull request.
License
This project is licensed under the MIT License. See the LICENSE file for details.