Upcoming Change to X API DM Events Endpoints Behavior

[taycaldwell]

UPDATE:
The date of this change has been updated from May 30, 2025 to June 3, 2025.

---

Dear X API Developers,

We’re announcing an important update to the X API’s DM Events endpoints to address a bug introduced on July 8, 2024. This change will restore the original intended behavior for the following endpoints:

• GET /2/dm_conversations/{dm_conversation_id}/dm_events
• GET /2/dm_conversations/with/{participant_id}/dm_events
• GET /2/dm_events
• GET /2/dm_events/{event_id}

Current Behavior

Currently, all four endpoints include a participant_ids array in the payload for all DM event types (MessageCreate, ParticipantsJoin, and ParticipantsLeave). This array lists all participants in the DM conversation, regardless of when they joined or left.

Example Payload (Current):

{
    "data": [
        {
            "dm_conversation_id": "0000000000000000003",
            "event_type": "MessageCreate",
            "id": "55555555555555555555",
            "created_at": "2024-07-16T17:58:37.000Z",
            "sender_id": "743911390801342465",
            "participant_ids": [
                "1399766153053061121",
                "17874544",
                "783214",
                "2244994945"
            ],
            "text": "New message"
        },
        {
            "dm_conversation_id": "0000000000000000003",
            "event_type": "ParticipantsLeave",
            "id": "44444444444444444444",
            "created_at": "2024-07-16T17:55:56.000Z",
            "participant_ids": [
                "1399766153053061121",
                "17874544",
                "783214",
                "2244994945"
            ]
        },
        ...
    ],
    "meta": {
        "result_count": 5,
        "next_token": "18LAA69A0RPSUMJHDC11AAAA",
        "previous_token": "1BLC469A158166P0IS11AAAA"
    }
}

Intended Behavior (Post-Change)

To align with the original intended design, we’re reverting the July 8, 2024 change. After the update, the participant_ids array will only be included for ParticipantsJoin and ParticipantsLeave events, and it will list only the participants who joined or left at the time of the event. The MessageCreate event will no longer include the participant_ids array.

Example Payload (Post-Change):

{
    "data": [
        {
            "dm_conversation_id": "0000000000000000003",
            "event_type": "MessageCreate",
            "id": "55555555555555555555",
            "created_at": "2024-07-16T17:58:37.000Z",
            "sender_id": "2244994945",
            "text": "New message"
        },
        {
            "dm_conversation_id": "0000000000000000003",
            "event_type": "ParticipantsLeave",
            "id": "44444444444444444444",
            "created_at": "2024-07-16T17:55:56.000Z",
            "participant_ids": [
                "783214"
            ]
        },
        ...
    ],
    "meta": {
        "result_count": 5,
        "next_token": "18LAA69A0RPSUMJHDC11AAAA",
        "previous_token": "1BLC469A158166P0IS11AAAA"
    }
}

Why This Change?

The current behavior, introduced on July 8, 2024, inadvertently included the participant_ids array for all event types, listing all conversation participants. This deviates from the intended design, where participant_ids should only appear in ParticipantsJoin and ParticipantsLeave events to reflect the specific users involved in those actions. By reverting this change, we aim to restore clarity and consistency in the API’s behavior.

Timeline

We plan to implement this change on June 3, 2025. This provides approximately 5 weeks to prepare and update your applications if they rely on the current behavior.

Action Required

Please review your integration with the affected DM Events endpoints:

• GET /2/dm_conversations/{dm_conversation_id}/dm_events
• GET /2/dm_conversations/with/{participant_id}/dm_events
• GET /2/dm_events
• GET /2/dm_events/{event_id}

Ensure your application can handle the updated payload structure:

• The participant_ids array will no longer be included in MessageCreate events.
• For ParticipantsJoin and ParticipantsLeave events, the participant_ids array will only include the IDs of users who joined or left at the time of the event.

If your application depends on the current behavior (e.g., expecting participant_ids in MessageCreate events or the full participant list in ParticipantsJoin/ParticipantsLeave events), you may need to adjust your logic to align with the updated behavior.

Support

We’re committed to supporting you through this transition. For questions, concerns, or assistance, please reach out via the X Developer Forums.

Thank you for your attention and for building with the X API. We apologize for any inconvenience and appreciate your cooperation in making this transition smooth.

Best regards,

The X API Team