Inbox Initial State

GET/tw-v2/interaction/inbox-initial-state

Description

Get the initial state of your Twitter DM inbox. Returns conversations, messages, user data, and inbox timeline cursors for pagination. Use the returned cursor for polling updates via dm-user-updates endpoint.

Parameters

Parameter	Type	Required	Description
authToken	string	required	Twitter authentication token (auth_token cookie value)
proxy	string	optional	Optional proxy in format 'host:port@user:pass'

Code Examples

const params = new URLSearchParams({
  authToken: 'YOUR_AUTH_TOKEN'
});

const response = await fetch(`https://api.tweetapi.com/tw-v2/interaction/inbox-initial-state?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

200

{
  "conversations": [
    {
      "id": "1234567890-9876543210",
      "type": "ONE_TO_ONE",
      "participants": [
        "1234567890",
        "9876543210"
      ],
      "lastMessageId": "1111111111111111111",
      "lastMessageTime": "2024-08-04T07:00:14.115Z",
      "lastReadMessageId": "1111111111111111111",
      "trusted": true,
      "muted": false,
      "readOnly": false,
      "lowQuality": false,
      "nsfw": false,
      "notificationsDisabled": false
    },
    {
      "id": "9876543210-5555555555",
      "type": "ONE_TO_ONE",
      "participants": [
        "9876543210",
        "5555555555"
      ],
      "lastMessageId": "2222222222222222222",
      "lastMessageTime": "2024-10-10T17:11:43.250Z",
      "lastReadMessageId": "0",
      "trusted": false,
      "muted": false,
      "readOnly": false,
      "lowQuality": true,
      "nsfw": false,
      "notificationsDisabled": false
    }
  ],
  "messages": [
    {
      "id": "1111111111111111111",
      "conversationId": "1234567890-9876543210",
      "senderId": "1234567890",
      "recipientId": "9876543210",
      "text": "Hey, how are you doing?",
      "createdAt": "2024-08-04T07:00:14.000Z",
      "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "editCount": 0
    },
    {
      "id": "3333333333333333333",
      "conversationId": "1234567890-9876543210",
      "senderId": "9876543210",
      "recipientId": "1234567890",
      "text": "I'm doing great, thanks for asking!",
      "createdAt": "2024-08-04T07:01:30.000Z",
      "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "editCount": 0,
      "replyTo": {
        "messageId": "1111111111111111111",
        "text": "Hey, how are you doing?"
      }
    },
    {
      "id": "4444444444444444444",
      "conversationId": "1234567890-9876543210",
      "senderId": "1234567890",
      "recipientId": "9876543210",
      "text": "Check out this photo! https://t.co/example123",
      "createdAt": "2024-08-04T07:05:00.000Z",
      "requestId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "editCount": 0,
      "entities": {
        "urls": [
          {
            "url": "https://t.co/example123",
            "expandedUrl": "https://x.com/messages/media/4444444444444444444",
            "displayUrl": "pic.x.com/example123"
          }
        ],
        "mentions": [],
        "hashtags": []
      },
      "attachment": {
        "type": "photo",
        "photo": {
          "id": "4444444444444444440",
          "url": "https://example.com/media/photo123.jpg",
          "width": 1200,
          "height": 800
        }
      }
    },
    {
      "id": "2222222222222222222",
      "conversationId": "9876543210-5555555555",
      "senderId": "5555555555",
      "recipientId": "9876543210",
      "text": "Hello! This is a test message with a link https://t.co/example456",
      "createdAt": "2024-10-10T17:11:43.000Z",
      "requestId": "d4e5f6a7-b8c9-0123-def1-234567890123",
      "editCount": 0,
      "entities": {
        "urls": [
          {
            "url": "https://t.co/example456",
            "expandedUrl": "https://example.com",
            "displayUrl": "example.com"
          }
        ],
        "mentions": [],
        "hashtags": []
      }
    }
  ],
  "users": [
    {
      "id": "1234567890",
      "username": "john_doe",
      "name": "John Doe",
      "bio": "Software developer and tech enthusiast",
      "location": "San Francisco, CA",
      "website": "https://example.com",
      "pinnedTweetIds": [],
      "avatar": "https://example.com/avatars/user1.jpg",
      "banner": "https://example.com/banners/user1.jpg",
      "profileImageShape": "Circle",
      "verified": false,
      "isBlueVerified": true,
      "verifiedType": null,
      "verifiedSince": null,
      "isIdentityVerified": false,
      "isProtected": false,
      "possiblySensitive": false,
      "profileInterstitialType": null,
      "withheldInCountries": [],
      "professional": null,
      "businessAccount": null,
      "creatorSubscriptionsCount": 0,
      "hasHiddenSubscriptions": false,
      "highlightsInfo": null,
      "hasGraduatedAccess": false,
      "isProfileTranslatable": false,
      "hasCustomTimelines": false,
      "isTranslator": false,
      "affiliatesHighlightedLabel": null,
      "defaultProfile": false,
      "defaultProfileImage": false,
      "followerCount": 1523,
      "followingCount": 892,
      "tweetCount": 456,
      "listedCount": 12,
      "mediaCount": 89,
      "favoritesCount": 3456,
      "createdAt": "2020-01-15T10:30:00.000Z"
    },
    {
      "id": "9876543210",
      "username": "jane_smith",
      "name": "Jane Smith",
      "bio": "Designer | Creator | Coffee lover ☕",
      "location": "New York, NY",
      "website": "https://janesmith.example",
      "pinnedTweetIds": [],
      "avatar": "https://example.com/avatars/user2.jpg",
      "banner": null,
      "profileImageShape": null,
      "verified": false,
      "isBlueVerified": false,
      "verifiedType": null,
      "verifiedSince": null,
      "isIdentityVerified": false,
      "isProtected": false,
      "possiblySensitive": false,
      "profileInterstitialType": null,
      "withheldInCountries": [],
      "professional": null,
      "businessAccount": null,
      "creatorSubscriptionsCount": 0,
      "hasHiddenSubscriptions": false,
      "highlightsInfo": null,
      "hasGraduatedAccess": false,
      "isProfileTranslatable": false,
      "hasCustomTimelines": false,
      "isTranslator": false,
      "affiliatesHighlightedLabel": null,
      "defaultProfile": false,
      "defaultProfileImage": false,
      "followerCount": 2341,
      "followingCount": 567,
      "tweetCount": 789,
      "listedCount": 23,
      "mediaCount": 145,
      "favoritesCount": 5678,
      "createdAt": "2019-03-20T14:22:00.000Z"
    }
  ],
  "inboxTimelines": {
    "trusted": {
      "status": "AT_END",
      "min_entry_id": "1817804537354494065"
    },
    "untrusted": {
      "status": "HAS_MORE",
      "min_entry_id": "1973369953274466402"
    },
    "untrustedLowQuality": {
      "status": "HAS_MORE",
      "min_entry_id": "1973369953274466402"
    }
  },
  "cursor": "GRwm5ILd5ZzonfM2FtiF3umk5p_zNiUCAAA",
  "lastSeenEventId": "4444444444444444444"
}