X/Twitter API
Options for posting using the X API
JSON for a basic post with a link and image to X/Twitter:
X/Twitter will automatically preview the link in the Tweet unless there is an image or video included. In the above example the image will show. Removing the image will cause the link preview to show.
If your video doesn’t end in a known video extension such as mp4, please use the
isVideo
parameter. See the /post endpoint for details.X/Twitter also supports sending media without post text. If you do not want post text included send an empty String
post: ""
You may upload up to 4 images or videos in a single Tweet. Please see the important guidelines and restrictions posting Twitter videos.
Publish Long Form Posts
Users with Premium X accounts, such as Premium or Premium Plus, have the ability to post longer posts of up to 25,000 characters. Ayrshare automatically allows long from posts for users with Premium X accounts.
If the user changes their X Premium status, please wait 24-hours for it to reflect in Ayrshare. You can check the Premium subscription status of a user with the /user or /analytics endpoints.
You may also force a long form post to be accepted with the longPost
body parameter. This can be done by including the following JSON in your request:
However, if a user without a Premium account attempts to post a long tweet, the system will return a code: 111
error.
Upload Long Videos
Business or Enterprise Plan required.
X/Twitter requires videos have a maximum video length of 2 minutes and 20 seconds. However, if you have a have been approved by X/Twitter to upload longer videos, such as in the Amplify Partner Program, you can post videos up to 10 minutes in length.
In addition to X/Twitter approving your account for long videos, your Ayrshare account must be enabled for long Twitter videos. Please contact us to enable this feature.
After your Ayrshare account is enabled for long videos and X/Twitter has approved your access, use the longVideo
twitterOptions parameter when posting:
X/Twitter Mentions
Mention another X/Twitter handle by adding @handle in the post text. For example:
Please review the important rules on mentions.
Post X/Twitter Thread (TweetStorm)
A X/Twitter Thread or TweetStorm can be posted via the API. A thread is a post broken up into a set of reply threads and link in X/Twitter with a line.
thread: true
to automatically break apart the post text into threads based on line breaks.threadNumber: true
to automatically add numbers at the end of threads in the format of 1/n. For example the 2nd of 5 threads will have appended: 2/5mediaUrls: [array of urls]
to add each media object, an image or video, to a thread in order. Only one media object will be added to a thread in order.
If the post is sent as a X/Twitter Thread, the returned post analytics will be an array of Tweets, "twitter": []
. See Post Analytics 200 Response for more information.
Skip Images and Multiple Media URLs
Skip an image for the thread by using null
in the array. For example:
["https://site.com/image1.png", null, "https://site.com/image2.png"]
This will place image1 on the first Tweet, no image on the second Tweet, and image2 on the third Tweet.
Multiple images can be added to a Tweet in a Thread by adding an object {}
with the media URLs in the mediaUrls
array. Any unique object keys can be used. For example:
In this example, the first Tweet will contain photo-1.jpg, the second Tweet photo-2.jpg and photo-3.jpg, and the third Tweet photo-4.jpg.
Thread Output
Ayrshare automatically breaks up the post text into appropriate length tweet (> 280 characters). Add paragraphs with \n\n
to the post text to indicate a unique thread should be created. For example:
will result in two Tweets in the thread.
If you want to add paragraphs, but not break into Tweets, use \u2063\n\u2063\n
will result in one Tweet with two paragraphs since the post is below 280 characters.
Delete X/Twitter Thread
To delete a Tweet Storm, call the /post delete endpoint with the top level post ID returned in the response. All threads will be deleted.
Alternative Text for Images
Add alternative text, also known as alt text, to a Tweet’s image. X/Twitter alt text is an accessibility feature used for additional user info and screen readers.
Use the altText
in the twitterOptions
object.
Each alt text must correspond to an image in the mediaUrls
array. The alt text will be applies to each image in order.
Alt text can not be applied to videos. If a video is included in the mediaUrls
with altText
, the video will not be posted.
Alt text must be 1,000 characters or less.
Quote Tweet
You can quote another Tweet by specifying the low-level Tweet ID. The ID can be retrieved via the /post
response in the postIds
field, get history, or directly from the Tweet URL: https://twitter.com/Ayrshare/status/1651601430669664256
X/Twitter Polls
Conduct a Twitter Poll with the twitterOptions
poll
parameter.
duration
: A number of minutes specifying the duration the poll will be conducted.options
: An array of strings of the poll options.
Subtitles / Captions for Videos
You can add subtitles, also known as captions, to videos by including an SRT file. Use the subTitleUrl
field in the twitterOptions
object to specify the URL to your SRT file.
subTitleUrl
: A valid SRT file. The URL must start withhttps://
and end in.srt
and be a valid SRT file.subTitleLanguage
: Optional: The language of the subtitles. Much be a valid language code. Default: “en”.subTitleName
: Optional: The name of the caption track. The name is intended to be visible to the user as an option during playback. The maximum name length supported is 150 characters. Default: “English”.
X/Twitter Video Compatibility
Some video software creates MP4 files that are not compatible with X/Twitter. For example, Camtasia versions older than 2019.0.9 create MP4 files that X/Twitter rejects. Also more than one audio track often causes problems.
If you receive back the following message while posting, it indicates the video is not compatible with Twitter and needs to be re-encoded.
"file is currently unsupported"
Please check your video software for compatibility. For example, Adobe Media Encoder has an export preset for Twitter 1080p Full HD.
Please see here for more X/Twitter API examples.