Skip to content

X (Twitter)

How to configure X for OpenQuok

6 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start your free trial

Overview

X publishing uses OAuth 1.0a (not OAuth 2). You need an X developer app with Read and Write permissions, a Native App type, valid OAuth redirect URIs, and backend env vars X_API_KEY and X_API_SECRET.

Backend environment

OpenQuok reads X credentials only through backend/config/GlobalConfig.ts (populated via getEnv from backend/config/envHelper.ts).

Copy the X block from backend/.env.development.example into backend/.env.development.local, fill values, then restart the backend process:

# X (Twitter) — OAuth 1.0a Native App (Read + Write).
# Redirect URI on the app must match: {FRONTEND_DOMAIN_URL}/integration/oauth/x
X_API_KEY=""
X_API_SECRET=""
# Set to true to hide X analytics in API responses and dashboards.
DISABLE_X_ANALYTICS=false
VariableDescription
X_API_KEYAPI Key (Consumer Key) from the X developer portal
X_API_SECRETAPI Secret (Consumer Secret)
DISABLE_X_ANALYTICSWhen true, X analytics endpoints return empty series (connected X channels may still appear in the analytics UI)

The frontend base URL used for OAuth redirects comes from FRONTEND_DOMAIN_URL.

OAuth redirect URI

X redirects the browser back to your web app after consent. The backend builds the redirect from FRONTEND_DOMAIN_URL plus /integration/oauth/x.

https://YOUR-FRONTEND-DOMAIN/integration/oauth/x

For local development with HTTPS (recommended):

https://localhost:5173/integration/oauth/x

X developer app setup

Create a project and app

Open the X developer portal

Create New X App

Then, submit the form and the project will be created.

Set up authentication

In Developer Console → Apps -> Settings:

Configure Authentication Settings

  • App permissions: Read and Write

  • Type of App: Native App

Configure App Type and Permissions

Configure App Type and Permissions

Copy API keys

In Keys and tokens, open Consumer Keys and copy API Key and API Secret into X_API_KEY and X_API_SECRET.

Compose settings

Per-post options (composer or CLI) include:

SettingKeys
Who can replywho_can_reply_post or x.whoCanReplyPost
Communitycommunity / community_url or x.communityUrl
Made with AImade_with_ai or x.madeWithAi
Paid partnershippaid_partnership or x.paidPartnership
Thread finisherx.enabled, x.message
Thread repliesx.replies[] with delaySeconds

Standard accounts use a 280 weighted character limit; enable Verified on the channel (in channel settings) for 4000 when the account has X Premium.

Features

Supported

FeatureDetails
Text postsWeighted 280 characters (standard); 4000 when Verified is enabled on the connected channel (X Premium)
Image postsUp to four images per tweet
Video postsOne video per tweet (≤ 140 seconds validated in the composer)
Who can replyfollowing, mentionedUsers, subscribers, or verified via compose settings
Community postsOptional community URL (parsed to community_id at publish)
Content labelsMade with AI and Paid partnership toggles
Thread repliesScheduled quote-less replies via x.replies[] with per-reply delaySeconds
Thread finisherClosing reply via x.enabled and x.message
Platform analyticsAccount timeline: likes, replies, reposts, quotes, impressions (unless DISABLE_X_ANALYTICS is true)
Per-post analyticsPublic metrics for a published tweet when the post row has a release_id
Channel plugsAuto-repost and auto-plug when like thresholds are met
Cross-account repost plugRepost from other connected X channels after publish (x-repost-post-users)
@-mention lookupUnlock the X channel in custom mode, type @ plus at least two characters (or use the toolbar @ button), then pick from suggestions — backed by POST /integrations/mentions
OAuth connectOAuth 1.0a single-step flow; long-lived tokens (reconnect on auth errors)

Not supported

FeatureNotes
OAuth 2 / PKCEOpenQuok uses OAuth 1.0a only for X
Polls, quote tweets, X ArticlesNot implemented
Mixed image + videoOne media mode per post: up to four images or one video
Automatic token refreshNo refresh cron; reconnect the channel when X returns auth errors

Troubleshooting connect failures

If Add X fails with Failed to generate an authorization URL (provider returned an error)., OpenQuok never received a consent URL from X. The backend already failed on POST https://api.x.com/oauth/request_token (OAuth 1.0a step 1).

Portal checklist (same app as your env keys)

Confirm all of the following on the openquok app in the X developer portal, then click Save at the bottom of User authentication settings:

SettingRequired value
App permissionsRead and Write (not Read only)
Type of AppNative App
Callback URIhttps://www.openquok.com/integration/oauth/x for Cloud (exact match; optional https://localhost:5173/integration/oauth/x for local dev)

Your screenshot can show correct callbacks and Native App while Read and Write is still missing or unsaved — verify permissions on the same settings screen before copying keys.

X error 32 — consumer keys out of sync

When X returns code 32 (Could not authenticate you), X_API_KEY and X_API_SECRET in the deployment do not match the consumer keys for this app (stale pair, wrong app, or keys regenerated in the portal without updating Vercel).

Save authentication settings

Complete User authentication (Read and Write, Native App, production callback). Save.

Regenerate consumer keys

On Keys and tokens → Consumer Keys, copy the current API Key and API Secret, or use Regenerate and copy the new pair immediately. Do not use Access Token / Access Token Secret here — only consumer keys.

Update production env

In Vercel (backend project) → Production environment variables, set X_API_KEY and X_API_SECRET. Confirm FRONTEND_DOMAIN_URL is https://www.openquok.com. Redeploy the API.

Verify before asking users to retry

From the monorepo, after copying the same values into backend/.env.production.local:

pnpm --filter backend run check:x-oauth -- --env-file .env.production.local

Exit code 0 means X accepted request_token and Cloud connect should work. Exit code 1 with code 32 means keys or portal settings are still wrong — do not ask customers to retry yet.

Search documentation
Find a docs page
Discord Support