0
# Tweet Operations
1

2
Complete tweet lifecycle management including posting, retrieving, deleting, and retweeting.
3

4
## Core Tweet Operations
5

6
### Tweet Posting
7

8
Post new tweets with text, media, and metadata.
9

10
```java { .api }
11
interface TweetsResources {
12
    /**
13
     * Post a simple text tweet
14
     * @param status Tweet text (max 280 characters)
15
     * @return Posted tweet status
16
     */
17
    Status updateStatus(String status) throws TwitterException;
18
    
19
    /**
20
     * Post a tweet with advanced options using StatusUpdate
21
     * @param statusUpdate Tweet parameters including media, location, reply settings
22
     * @return Posted tweet status
23
     */
24
    Status updateStatus(StatusUpdate statusUpdate) throws TwitterException;
25
}
26
```
27

28
**Usage Examples:**
29

30
```java
31
TwitterV1 v1 = twitter.v1();
32

33
// Simple text tweet
34
Status tweet = v1.tweets().updateStatus("Hello Twitter API!");
35

36
// Tweet with advanced options
37
StatusUpdate update = StatusUpdate.of("Check out this image!")
38
    .possiblySensitive(false)
39
    .placeId("place_id_here")
40
    .displayCoordinates(true);
41
    
42
Status tweetWithOptions = v1.tweets().updateStatus(update);
43
```
44

45
### Tweet Retrieval
46

47
Retrieve individual tweets and collections of tweets.
48

49
```java { .api }
50
interface TweetsResources {
51
    /**
52
     * Get a single tweet by ID
53
     * @param id Tweet ID
54
     * @return Tweet status object
55
     */
56
    Status showStatus(long id) throws TwitterException;
57
    
58
    /**
59
     * Get multiple tweets by their IDs
60
     * @param ids Array of tweet IDs (max 100)
61
     * @return List of tweet status objects
62
     */
63
    ResponseList<Status> lookup(long... ids) throws TwitterException;
64
    
65
    /**
66
     * Get retweets of a specific tweet
67
     * @param statusId Original tweet ID
68
     * @return List of retweet status objects (max 100)
69
     */
70
    ResponseList<Status> getRetweets(long statusId) throws TwitterException;
71
}
72
```
73

74
**Usage Examples:**
75

76
```java
77
// Get single tweet
78
Status tweet = v1.tweets().showStatus(1234567890L);
79
System.out.println(tweet.getText());
80

81
// Get multiple tweets
82
ResponseList<Status> tweets = v1.tweets().lookup(1234567890L, 9876543210L);
83
for (Status status : tweets) {
84
    System.out.println(status.getUser().getScreenName() + ": " + status.getText());
85
}
86

87
// Get retweets of a tweet
88
ResponseList<Status> retweets = v1.tweets().getRetweets(1234567890L);
89
System.out.println("Retweet count: " + retweets.size());
90
```
91

92
### Tweet Deletion
93

94
Delete tweets from authenticated user's timeline.
95

96
```java { .api }
97
interface TweetsResources {
98
    /**
99
     * Delete a tweet
100
     * @param statusId ID of tweet to delete
101
     * @return Deleted tweet status
102
     */
103
    Status destroyStatus(long statusId) throws TwitterException;
104
}
105
```
106

107
**Usage Example:**
108

109
```java
110
// Delete a tweet
111
Status deletedTweet = v1.tweets().destroyStatus(1234567890L);
112
System.out.println("Deleted: " + deletedTweet.getText());
113
```
114

115
### Retweet Operations
116

117
Retweet and unretweet functionality.
118

119
```java { .api }
120
interface TweetsResources {
121
    /**
122
     * Retweet a tweet
123
     * @param statusId ID of tweet to retweet
124
     * @return Retweet status object
125
     */
126
    Status retweetStatus(long statusId) throws TwitterException;
127
    
128
    /**
129
     * Remove a retweet (unretweet)
130
     * @param statusId ID of original tweet to unretweet
131
     * @return Original tweet status
132
     */
133
    Status unRetweetStatus(long statusId) throws TwitterException;
134
    
135
    /**
136
     * Get user IDs who retweeted a specific tweet
137
     * @param statusId Tweet ID
138
     * @param cursor Cursor for pagination (-1 for first page)
139
     * @return User IDs with pagination cursors
140
     */
141
    IDs getRetweeterIds(long statusId, long cursor) throws TwitterException;
142
    
143
    /**
144
     * Get user IDs who retweeted a specific tweet with count limit
145
     * @param statusId Tweet ID
146
     * @param count Maximum number of IDs to return (max 5000)
147
     * @param cursor Cursor for pagination (-1 for first page)
148
     * @return User IDs with pagination cursors
149
     */
150
    IDs getRetweeterIds(long statusId, int count, long cursor) throws TwitterException;
151
}
152
```
153

154
**Usage Examples:**
155

156
```java
157
// Retweet a tweet
158
Status retweet = v1.tweets().retweetStatus(1234567890L);
159
System.out.println("Retweeted: " + retweet.getRetweetedStatus().getText());
160

161
// Unretweet
162
Status originalTweet = v1.tweets().unRetweetStatus(1234567890L);
163

164
// Get retweeter IDs
165
IDs retweeterIds = v1.tweets().getRetweeterIds(1234567890L, -1);
166
for (long userId : retweeterIds.getIDs()) {
167
    System.out.println("Retweeted by user ID: " + userId);
168
}
169
```
170

171
## Media Upload
172

173
Upload images, videos, and GIFs to include in tweets.
174

175
```java { .api }
176
interface TweetsResources {
177
    /**
178
     * Upload media file for use in tweets
179
     * @param mediaFile Media file to upload
180
     * @return Uploaded media object with media ID
181
     */
182
    UploadedMedia uploadMedia(File mediaFile) throws TwitterException;
183
    
184
    /**
185
     * Upload media from input stream
186
     * @param fileName Name of the media file
187
     * @param media Input stream of media data
188
     * @return Uploaded media object with media ID
189
     */
190
    UploadedMedia uploadMedia(String fileName, InputStream media) throws TwitterException;
191
    
192
    /**
193
     * Upload large media files using chunked upload (for videos > 15MB)
194
     * @param fileName Name of the media file
195
     * @param media Input stream of media data
196
     * @return Uploaded media object with media ID
197
     */
198
    UploadedMedia uploadMediaChunked(String fileName, InputStream media) throws TwitterException;
199
}
200
```
201

202
**Usage Examples:**
203

204
```java
205
// Upload image file
206
File imageFile = new File("photo.jpg");
207
UploadedMedia media = v1.tweets().uploadMedia(imageFile);
208

209
// Tweet with uploaded media
210
StatusUpdate update = StatusUpdate.of("Check out this photo!")
211
    .mediaIds(media.getMediaId());
212
Status tweet = v1.tweets().updateStatus(update);
213

214
// Upload from input stream
215
try (FileInputStream fis = new FileInputStream("video.mp4")) {
216
    UploadedMedia videoMedia = v1.tweets().uploadMediaChunked("video.mp4", fis);
217
    
218
    StatusUpdate videoTweet = StatusUpdate.of("Here's a video!")
219
        .mediaIds(videoMedia.getMediaId());
220
    v1.tweets().updateStatus(videoTweet);
221
}
222
```
223

224
## Tweet Embedding
225

226
Get oEmbed data for embedding tweets in web pages.
227

228
```java { .api }
229
interface TweetsResources {
230
    /**
231
     * Get oEmbed data for a tweet
232
     * @param req oEmbed request parameters
233
     * @return oEmbed response data
234
     */
235
    OEmbed getOEmbed(OEmbedRequest req) throws TwitterException;
236
}
237
```
238

239
**Usage Example:**
240

241
```java
242
// Get oEmbed data for a tweet
243
OEmbedRequest request = OEmbedRequest.of(1234567890L)
244
    .maxWidth(550)
245
    .hideMedia(false)
246
    .hideThread(false)
247
    .omitScript(false)
248
    .align("center")
249
    .related("twitterapi,twitter")
250
    .lang("en");
251

252
OEmbed oEmbed = v1.tweets().getOEmbed(request);
253
System.out.println("HTML: " + oEmbed.getHtml());
254
System.out.println("Width: " + oEmbed.getWidth());
255
System.out.println("Height: " + oEmbed.getHeight());
256
```
257

258
## Status Update Builder
259

260
Comprehensive tweet composition with media, location, and reply settings.
261

262
```java { .api }
263
class StatusUpdate {
264
    /**
265
     * Create basic status update with text
266
     * @param status Tweet text
267
     * @return StatusUpdate builder
268
     */
269
    static StatusUpdate of(String status);
270
    
271
    /**
272
     * Set tweet as reply to another tweet
273
     * @param inReplyToStatusId ID of tweet being replied to
274
     * @return StatusUpdate with reply settings
275
     */
276
    StatusUpdate inReplyToStatusId(long inReplyToStatusId);
277
    
278
    /**
279
     * Set geographic location for tweet
280
     * @param location Latitude/longitude coordinates
281
     * @return StatusUpdate with location
282
     */
283
    StatusUpdate location(GeoLocation location);
284
    
285
    /**
286
     * Set place ID for tweet location
287
     * @param placeId Twitter place ID
288
     * @return StatusUpdate with place
289
     */
290
    StatusUpdate placeId(String placeId);
291
    
292
    /**
293
     * Set whether to display exact coordinates
294
     * @param displayCoordinates True to show coordinates publicly
295
     * @return StatusUpdate with coordinate display setting
296
     */
297
    StatusUpdate displayCoordinates(boolean displayCoordinates);
298
    
299
    /**
300
     * Mark tweet as possibly sensitive content
301
     * @param possiblySensitive True if content may be sensitive
302
     * @return StatusUpdate with sensitivity flag
303
     */
304
    StatusUpdate possiblySensitive(boolean possiblySensitive);
305
    
306
    /**
307
     * Attach media to tweet using media IDs
308
     * @param mediaIds Media IDs from uploadMedia() calls
309
     * @return StatusUpdate with attached media
310
     */
311
    StatusUpdate mediaIds(long... mediaIds);
312
    
313
    /**
314
     * Enable automatic reply metadata population
315
     * @param autoPopulateReplyMetadata True to auto-populate reply data
316
     * @return StatusUpdate with reply metadata setting
317
     */
318
    StatusUpdate autoPopulateReplyMetadata(boolean autoPopulateReplyMetadata);
319
    
320
    /**
321
     * Exclude reply user IDs from automatic reply metadata
322
     * @param excludeReplyUserIds User IDs to exclude from reply
323
     * @return StatusUpdate with exclusion settings
324
     */
325
    StatusUpdate excludeReplyUserIds(long... excludeReplyUserIds);
326
    
327
    /**
328
     * Add attachment URL (for quote tweets)
329
     * @param attachmentUrl Quote tweet URL
330
     * @return StatusUpdate with attachment
331
     */
332
    StatusUpdate attachmentUrl(String attachmentUrl);
333
}
334
```
335

336
## oEmbed Request Builder
337

338
Configure tweet embedding options.
339

340
```java { .api }
341
class OEmbedRequest {
342
    /**
343
     * Create oEmbed request for tweet ID
344
     * @param statusId Tweet ID to embed
345
     * @return OEmbedRequest builder
346
     */
347
    static OEmbedRequest of(long statusId);
348
    
349
    /**
350
     * Create oEmbed request for tweet URL
351
     * @param url Tweet URL to embed
352
     * @return OEmbedRequest builder
353
     */
354
    static OEmbedRequest of(String url);
355
    
356
    /**
357
     * Set maximum width for embedded tweet
358
     * @param maxWidth Maximum width in pixels
359
     * @return OEmbedRequest with width setting
360
     */
361
    OEmbedRequest maxWidth(int maxWidth);
362
    
363
    /**
364
     * Hide media in embedded tweet
365
     * @param hideMedia True to hide media attachments
366
     * @return OEmbedRequest with media visibility setting
367
     */
368
    OEmbedRequest hideMedia(boolean hideMedia);
369
    
370
    /**
371
     * Hide conversation thread in embedded tweet
372
     * @param hideThread True to hide thread context
373
     * @return OEmbedRequest with thread visibility setting
374
     */
375
    OEmbedRequest hideThread(boolean hideThread);
376
    
377
    /**
378
     * Omit JavaScript from oEmbed HTML
379
     * @param omitScript True to exclude script tags
380
     * @return OEmbedRequest with script setting
381
     */
382
    OEmbedRequest omitScript(boolean omitScript);
383
    
384
    /**
385
     * Set alignment of embedded tweet
386
     * @param align Alignment ("left", "right", "center", "none")
387
     * @return OEmbedRequest with alignment
388
     */
389
    OEmbedRequest align(String align);
390
    
391
    /**
392
     * Set related accounts for embedded tweet
393
     * @param related Comma-separated list of related screen names
394
     * @return OEmbedRequest with related accounts
395
     */
396
    OEmbedRequest related(String related);
397
    
398
    /**
399
     * Set language for embedded tweet
400
     * @param lang Language code (e.g., "en", "es", "fr")
401
     * @return OEmbedRequest with language
402
     */
403
    OEmbedRequest lang(String lang);
404
}
405
```
406

407
## Response Types
408

409
### Status Object
410

411
Core tweet data model with full metadata.
412

413
```java { .api }
414
interface Status extends TwitterResponse {
415
    /**
416
     * Tweet creation date and time
417
     */
418
    LocalDateTime getCreatedAt();
419
    
420
    /**
421
     * Unique tweet ID
422
     */
423
    long getId();
424
    
425
    /**
426
     * Tweet text content
427
     */
428
    String getText();
429
    
430
    /**
431
     * Tweet source application
432
     */
433
    String getSource();
434
    
435
    /**
436
     * Whether tweet text is truncated
437
     */
438
    boolean isTruncated();
439
    
440
    /**
441
     * ID of tweet being replied to (if reply)
442
     */
443
    long getInReplyToStatusId();
444
    
445
    /**
446
     * ID of user being replied to (if reply)
447
     */
448
    long getInReplyToUserId();
449
    
450
    /**
451
     * Screen name of user being replied to (if reply)
452
     */
453
    String getInReplyToScreenName();
454
    
455
    /**
456
     * Author of the tweet
457
     */
458
    User getUser();
459
    
460
    /**
461
     * Geographic coordinates (if enabled)
462
     */
463
    GeoLocation getGeoLocation();
464
    
465
    /**
466
     * Place information (if tweet is geo-tagged)
467
     */
468
    Place getPlace();
469
    
470
    /**
471
     * Whether tweet contains potentially sensitive content
472
     */
473
    boolean isPossiblySensitive();
474
    
475
    /**
476
     * Number of retweets
477
     */
478
    int getRetweetCount();
479
    
480
    /**
481
     * Number of favorites/likes
482
     */
483
    int getFavoriteCount();
484
    
485
    /**
486
     * Whether authenticated user has favorited this tweet
487
     */
488
    boolean isFavorited();
489
    
490
    /**
491
     * Whether authenticated user has retweeted this tweet
492
     */
493
    boolean isRetweeted();
494
    
495
    /**
496
     * Whether tweet contains a quoted tweet
497
     */
498
    boolean isQuoteStatus();
499
    
500
    /**
501
     * Quoted tweet status (if quote tweet)
502
     */
503
    Status getQuotedStatus();
504
    
505
    /**
506
     * Original tweet if this is a retweet
507
     */
508
    Status getRetweetedStatus();
509
    
510
    /**
511
     * URL entities found in tweet text
512
     */
513
    URLEntity[] getURLEntities();
514
    
515
    /**
516
     * User mention entities in tweet text
517
     */
518
    UserMentionEntity[] getUserMentionEntities();
519
    
520
    /**
521
     * Hashtag entities in tweet text
522
     */
523
    HashtagEntity[] getHashtagEntities();
524
    
525
    /**
526
     * Media entities (photos, videos) in tweet
527
     */
528
    MediaEntity[] getMediaEntities();
529
    
530
    /**
531
     * Symbol entities (cashtags) in tweet text
532
     */
533
    SymbolEntity[] getSymbolEntities();
534
}
535
```
536

537
### Uploaded Media Object
538

539
Media upload response with metadata.
540

541
```java { .api }
542
interface UploadedMedia {
543
    /**
544
     * Media ID for use in tweets
545
     */
546
    long getMediaId();
547
    
548
    /**
549
     * Media size in bytes
550
     */
551
    long getSize();
552
    
553
    /**
554
     * Expiration time for media (Unix timestamp)
555
     */
556
    long getExpiresAfterSecs();
557
    
558
    /**
559
     * Media processing state for videos
560
     */
561
    ProcessingInfo getProcessingInfo();
562
}
563
```
564

565
### oEmbed Response
566

567
Tweet embedding data for web pages.
568

569
```java { .api }
570
interface OEmbed {
571
    /**
572
     * HTML code for embedding tweet
573
     */
574
    String getHtml();
575
    
576
    /**
577
     * Width of embedded tweet
578
     */
579
    int getWidth();
580
    
581
    /**
582
     * Height of embedded tweet  
583
     */
584
    int getHeight();
585
    
586
    /**
587
     * oEmbed version
588
     */
589
    String getVersion();
590
    
591
    /**
592
     * oEmbed type (always "rich")
593
     */
594
    String getType();
595
    
596
    /**
597
     * Cache age in seconds
598
     */
599
    long getCacheAge();
600
    
601
    /**
602
     * Tweet URL
603
     */
604
    String getUrl();
605
    
606
    /**
607
     * Author name
608
     */
609
    String getAuthorName();
610
    
611
    /**
612
     * Author URL
613
     */
614
    String getAuthorUrl();
615
    
616
    /**
617
     * Provider name (Twitter)
618
     */
619
    String getProviderName();
620
    
621
    /**
622
     * Provider URL
623
     */
624
    String getProviderUrl();
625
}
626
```