graph.threads.net), which is Meta’s dedicated API for Threads. It uses an OAuth 2.0 flow with Threads-specific scopes and is entirely separate from the Facebook integration — you must connect Threads independently even if you already have Facebook connected.
The Threads API uses
https://graph.threads.net as its base URL, distinct from Meta’s Facebook Graph API at https://graph.facebook.com. Tokens and apps are not shared between the two.How the Threads OAuth flow works
Initiate the connection
Hayon’s backend (
GET /api/platform/threads/connect) builds an authorization URL targeting https://threads.net/oauth/authorize with the required scopes and your Hayon user ID in the state parameter.Authorize on Threads
You are redirected to Threads’ authorization page. Review the requested permissions and tap Authorize.
Callback
Threads redirects back to
GET /api/platform/threads/callback with a one-time code and your Hayon user ID in state.Short-lived token exchange
Hayon sends a
POST request to https://graph.threads.net/oauth/access_token to exchange the code for a short-lived access token and your Threads user ID.Long-lived token exchange
Hayon immediately exchanges the short-lived token for a long-lived token (valid ~60 days) using the
th_exchange_token grant type via GET https://graph.threads.net/access_token.Profile fetch
Hayon calls
GET https://graph.threads.net/me with fields id,username,name,threads_profile_picture_url to retrieve your profile.Required OAuth scopes
Hayon requests the following Threads permissions:| Scope | Purpose |
|---|---|
threads_basic | Read basic account information (username, profile picture, ID) |
threads_content_publish | Publish posts (text and media) to Threads |
threads_manage_insights | Read post and account-level analytics |
What Hayon stores
| Field | Description |
|---|---|
connected | true once authorized |
platformId | Your Threads user ID |
auth.accessToken | Long-lived access token (valid ~60 days) |
auth.expiresAt | Approximately 60 days from connection time |
profile.handle | Your Threads username |
profile.displayName | Your Threads display name |
profile.avatar | threads_profile_picture_url from the Threads API |
Supported content types
Threads supports text and media posts. Hayon’s integration covers:| Content type | Supported |
|---|---|
| Text-only posts | Yes |
| Single image posts | Yes |
| Carousel posts (multiple images) | Yes |
| Video posts | No |
| Replies / quote posts | No |
| Polls | No |
Character limits and constraints
- Character limit: 500 characters per Threads post.
- Images per carousel: Up to 10 images in a single carousel post.
- Image formats: JPEG, PNG.
- Maximum image size: As specified by the Threads API — images should be under 8 MB.
- Video: Video posting is not currently implemented in Hayon’s Threads integration.
Threads posts exceeding 500 characters are rejected by the Threads API. Hayon does not automatically truncate content.
Token expiry and refresh
Threads long-lived access tokens are valid for approximately 60 days. Hayon stores the expiry time inauth.expiresAt.
To manually refresh your Threads profile data while the token is valid:
Disconnecting
To disconnect Threads, navigate to Settings > Connected accounts and click Disconnect next to Threads, or call:connected: false.
To fully revoke Hayon’s access on Threads, visit your Threads account settings and remove the app from authorized applications.
Limitations
Independent from Facebook
Independent from Facebook
Even if you have Facebook connected, Threads requires a separate OAuth flow with its own app credentials. Connecting or disconnecting Facebook has no effect on your Threads connection.
Single account only
Single account only
Hayon connects one Threads account per user. Connecting a second Threads account replaces the first.
App review requirement
App review requirement
Publishing to Threads requires the
threads_content_publish scope, which requires Meta App Review approval for production use. Your Hayon deployment must have a Meta app with this scope approved.No token auto-renewal
No token auto-renewal
Unlike some OAuth 2.0 implementations, Threads long-lived tokens are not automatically renewed by Hayon. Reconnect every ~60 days to avoid interruption.
Troubleshooting
Redirect fails with 'threads_auth_failed'
Redirect fails with 'threads_auth_failed'
The authorization code was not returned by Threads (e.g. you denied access or closed the window). Click Connect again and complete the authorization.
'threads_connect_failed' after authorization
'threads_connect_failed' after authorization
Profile shows stale data
Profile shows stale data
Use the refresh endpoint (
GET /api/platform/threads/refresh) to pull updated username, display name, and avatar from the Threads API.