Today, we are announcing the first Twitter API v2 Direct Messages endpoints. Direct Messages are the fundamental tool for building private real-time notifications on the Twitter Platform. They provide a private communication channel for Twitter users and drive key use cases such as customer care and gaming notifications. 

This launch provides six foundational endpoints for creating Direct Message conversations and retrieving conversation events. For the first time, these endpoints support group Direct Message conversations. Group messages are a highly requested API feature, and we’re excited to be able to make this new functionality available on the Twitter API v2. 

This release includes three POST endpoints for creating new messages:

• Create a new one-to-one Direct Message. This endpoint will add a new Direct Message to a new or existing one-to-one conversation. 

• Create a new group conversation with an initial Direct Message. 

• Create a new Direct Message, adding it to either a one-to-one or group conversation.

These POST endpoints support adding a single media attachment. To learn more about these endpoints, see the Manage Direct Messages documentation. 

There are also three methods for retrieving Direct Message events: 

• Retrieve events associated with a one-to-one conversation by referencing the user ID the authenticating user is messaging with.

• Retrieve events associated with any conversation by referencing its conversation ID.

• Retrieve events associated with the authenticating user, across one-to-one and group conversations.

These three GET endpoints are used for reconstructing the timeline of Direct Message conversations. For this launch there are three event types available:

• A Direct Message is created.

• A participant joins a conversation.

• A participant leaves a conversation. 

To learn more about these endpoints, see the Direct Messages lookup documentation. 

Get started

To access these endpoints; you must have a developer account. All developers building with the Twitter API v2 can begin using these endpoints right away. Be sure to check out our documentation for more information on getting started.

We can’t wait to see what you build 

We’re continuing to add new features and functionality to Twitter API v2. This initial launch provides the foundation for v2 Direct Messages, so look for more functionality in the future. Be sure to keep an eye on our public roadmap for the latest. As always, we’d love to hear what you think. Please reach out with any questions or feedback on improving this endpoint. Be sure to Tweet us at @TwitterDev to let us know what you build!