Skip to main content
Inbox and Thread represent the Instagram direct message layer in the JxInsta mobile library. Inbox is the top-level container returned by JxInsta.getDirectInbox() — it holds a list of Thread objects and the usernames of inbox participants. Each Thread represents a single conversation and provides methods to send text messages and images, paginate message history, delete the conversation, and mark it as read.

​
Thread fields

Thread objects are constructed from the threads array inside the inbox JSON response. Most fields are populated when constructing from a full thread JSON object.
​
id
String
The unique thread identifier, sourced from thread_id in the API response. Used as the key for all thread-level API operations.
​
recipient
String
The username of the other participant in the conversation, sourced from the first element of the users array.
​
recipientId
long
The numeric primary key (pk) of the recipient user. Used when constructing the recipient_users field for outbound messages.
​
displayPicture
String
The URL of the recipient’s high-resolution profile picture (profile_pic_url_hd). May be an empty string if unavailable.
​
messages
List<String>
A list of message text strings loaded from the items array at construction time. Each entry corresponds to the text field of one message item. The list is ordered as returned by the API (most recent first).
​
oldestCursor
String
The cursor pointing to the oldest loaded message, sourced from oldest_cursor. Passed to MessagePaginator to fetch earlier pages of message history.
​
lastItemId
String
The item_id of the most recent message in the thread, used by markSeen() to update the read receipt.

​
Thread methods

​
sendMessage(String message)

Sends a text message to the thread’s recipient. The method generates a unique client_context UUID for deduplication and sends the message via the direct send endpoint.
Thread.java
Inbox inbox = client.getDirectInbox(10, 5);
Thread thread = inbox.threads.get(0);
thread.sendMessage("Hey, how are you?");
​
message
string
required
The text content of the message to send. Must not be null (@NotNull). Sent as the text field in the signed request body.
Returns — void Throws — InstagramException

​
sendImage(InputStream inputStream, String caption)

Uploads an image and sends it as a direct message to the thread’s recipient. The image is uploaded first to obtain an upload ID (attachment_fbid), then dispatched via the photo send endpoint.
Thread.java
try (InputStream image = new FileInputStream("photo.jpg")) {
    thread.sendImage(image, "Check this out!");
}
​
inputStream
InputStream
required
The raw bytes of the image to send. Must not be null (@NotNull). The stream is consumed during the upload step.
​
caption
string
required
A text caption to accompany the image in the message. Must not be null (@NotNull). Sent as the text field alongside the image attachment.
Returns — void Throws — InstagramException (wraps any IOException from the upload step as Reasons.IO)

​
getMessages()

Returns a MessagePaginator for lazily fetching older pages of message history for this thread. The paginator is seeded with the thread’s oldestCursor to start from where the inbox fetch left off.
Thread.java
MessagePaginator paginator = thread.getMessages();
while (paginator.hasNext()) {
    System.out.println(paginator.next());
}
Returns — MessagePaginator

​
delete()

Deletes the thread for the authenticated user. The request is sent with should_move_future_requests_to_spam=false, meaning future messages from the same user will not be filtered.
Thread.java
thread.delete();
Returns — void Throws — InstagramException

​
markSeen()

Marks the thread as read up to the most recent message. This method is a no-op if lastItemId is null (i.e., the thread was constructed without message items).
Thread.java
thread.markSeen();
Returns — void Throws — InstagramException

​
toString()

Returns a string representation of all thread fields, useful for logging and debugging.
Thread.java
System.out.println(thread.toString());
// Thread{id='340282366...', recipient='someuser', recipientId=123456, ...}

​
Inbox fields

Inbox is returned by JxInsta.getDirectInbox(int maxThreads, int maxMessages). It parses the inbox and users arrays from the raw API response.
​
totalThreads
int
The number of threads retrieved in this response, equal to threads.size(). Derived from the length of the threads JSON array.
​
threads
List<Thread>
The list of Thread objects loaded from the inbox. Each thread includes pre-fetched messages up to the maxMessages limit specified in getDirectInbox.
​
users
List<String>
A flat list of usernames of all participants found in the inbox users array. Complements the per-thread recipient field.

​
Inbox methods

​
getRequests(int maxThreads, int maxMessages)

Fetches pending message requests (conversations from users you do not follow) from the separate DM requests inbox endpoint.
Inbox.java
Inbox inbox = client.getDirectInbox(20, 10);
List<Thread> requests = inbox.getRequests(10, 5);
for (Thread request : requests) {
    System.out.println("Request from: " + request.recipient);
}
​
maxThreads
number
required
The maximum number of request threads to return. Maps to the limit query parameter.
​
maxMessages
number
required
The maximum number of messages to load per request thread. Maps to the thread_message_limit query parameter.
Returns — List<Thread> Throws — InstagramException

​
getThread(String id, int maxMessage)

Fetches a single thread by its ID, loading up to maxMessage messages. Use this to refresh a thread or to load a thread you already have an ID for without fetching the full inbox.
Inbox.java
Thread thread = inbox.getThread("340282366841710300949128137443944820736", 20);
System.out.println(thread.recipient);
System.out.println(thread.messages);
​
id
string
required
The unique thread ID to fetch. Corresponds to Thread.id.
​
maxMessage
number
required
The maximum number of messages to load for this thread. Maps to the limit query parameter on the thread detail endpoint.
Returns — Thread Throws — InstagramException