Skip to main content
GET
/
2
/
chat
/
conversations
Get Chat Conversations
curl --request GET \
  --url https://api.x.com/2/chat/conversations \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "<string>",
      "admin_ids": [
        "<string>"
      ],
      "created_at": "<string>",
      "group_avatar_url": "<string>",
      "group_name": "<string>",
      "is_muted": true,
      "member_ids": [
        "<string>"
      ],
      "message_ttl_msec": "<string>",
      "participant_ids": [
        "<string>"
      ],
      "screen_capture_blocking_enabled": true,
      "screen_capture_detection_enabled": true,
      "type": "direct",
      "updated_at": "<string>"
    }
  ],
  "errors": [
    {
      "title": "<string>",
      "type": "<string>",
      "detail": "<string>",
      "status": 123
    }
  ],
  "includes": {
    "users": [
      {}
    ]
  },
  "meta": {
    "has_message_requests": true,
    "next_token": "<string>",
    "result_count": 123
  }
}

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
max_results
integer<int32>
default:10

Maximum number of conversations to return.

Required range: 1 <= x <= 100
​
pagination_token
string

Token for pagination to retrieve the next page of results.

​
chat_conversation.fields
enum<string>[]

A comma separated list of ChatConversation fields to display. The fields available for a ChatConversation object.

Minimum array length: 1
Available options:
admin_ids,
created_at,
group_avatar_url,
group_name,
id,
is_muted,
member_ids,
message_ttl_msec,
participant_ids,
screen_capture_blocking_enabled,
screen_capture_detection_enabled,
type,
updated_at
Example:
[
  "admin_ids",
  "created_at",
  "group_avatar_url",
  "group_name",
  "id",
  "is_muted",
  "member_ids",
  "message_ttl_msec",
  "participant_ids",
  "screen_capture_blocking_enabled",
  "screen_capture_detection_enabled",
  "type",
  "updated_at"
]
​
expansions
enum<string>[]

A comma separated list of fields to expand. The list of fields you can expand for a ChatConversation object. If the field has an ID, it can be expanded into a full object.

Minimum array length: 1
Available options:
admin_ids,
member_ids,
participant_ids
Example:
[
  "admin_ids",
  "member_ids",
  "participant_ids"
]
​
user.fields
enum<string>[]

A comma separated list of User fields to display. The fields available for a User object.

Minimum array length: 1
Available options:
affiliation,
confirmed_email,
connection_status,
created_at,
description,
entities,
id,
is_identity_verified,
location,
most_recent_tweet_id,
name,
parody,
pinned_tweet_id,
profile_banner_url,
profile_image_url,
protected,
public_metrics,
receives_your_dm,
subscription,
subscription_type,
url,
username,
verified,
verified_followers_count,
verified_type,
withheld
Example:
[
  "affiliation",
  "confirmed_email",
  "connection_status",
  "created_at",
  "description",
  "entities",
  "id",
  "is_identity_verified",
  "location",
  "most_recent_tweet_id",
  "name",
  "parody",
  "pinned_tweet_id",
  "profile_banner_url",
  "profile_image_url",
  "protected",
  "public_metrics",
  "receives_your_dm",
  "subscription",
  "subscription_type",
  "url",
  "username",
  "verified",
  "verified_followers_count",
  "verified_type",
  "withheld"
]

Response

The request has succeeded.

​
data
object[]

List of conversations in the user's inbox.

​
errors
object[]
Minimum array length: 1
​
includes
object

Expanded objects requested via expansions parameter.

​
meta
object