Direct Message events

Direct Message events

Direct Message (DM) conversations are made up of events. The Twitter API v2 currently supports three event types: MessageCreate, ParticipantsJoin, and ParticipantsLeave.

DM event objects are returned by the Direct Message lookup endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the Manage Direct Messages endpoints.

When requesting DM events, there are three default event object attributes, or fields, included: id, event_type, and text. To receive additional event fields, use the fields parameter dm_event.fields to select others. Other available event fields include the following: dm_conversation_id, created_at, sender_id, attachments, participant_ids, and referenced_tweets.

Several of these fields provide the IDs of other Twitter objects related to the Direct Message event:

  • sender_id - The ID of the account that sent the message, or who invited a participant to a group conversation
  • partricipants_ids - An array of account IDs. For ParticipantsJoin and ParticipantsLeave events this array will contain a single ID of the account that created the event
  • attachments - Provides media IDs for content that has been uploaded to Twitter by the sender
  • referenced_tweets - If a Tweet URL is found in the text field, the ID of that Tweet is included in the response

The sender_id, participant_ids, referenced_tweets.id, and attachments.media_keys expansions are available to expand on these Twitter object IDs.

Field value Type Description How it can be used
id (default) string

The unique identifier of the event.

"id": "1050118621198921728"

Use this to programmatically retrieve a specific conversation event (available with v1.1 endpoints).
event_type (default) string

Describes the type of event. Three types are currently supported: 

  • MessageCreate

  • ParticipantsJoin

  • ParticipantsLeave

"event_type": "MessageCreate"

When retrieving a conversation's history, understanding when messages were created, and for group conversations, understanding when participants joined and left. All GET methods support filtering on specific event types with the event_type= query parameter. .
text (default)  string

The actual UTF-8 text of the Direct Message. 

"text": "Hello, just you!"

With chatbots, this can be used to analyze message contents and determining automated responses. Could be used to build conversation search features. 
sender_id string

ID of the User creating the event. To expand this object in the response, include sender_id as an expansion  and use the user.fields query parameter to specify User object attributes of interest.

"sender_id": "906948460078698496"

Retrieve the User object of who created the MessageCreate or ParticipantsJoin event.
participant_id array (of strings)

IDs of the participants joining and leaving a group conversation. Also used when creating new group conversations. To expand this object in the response, include participant_ids as an expansion and use the user.fields query parameter to specify User object attributes of interest.

"participant_ids": [

     "906948460078698496"

]

Used to retrieve User objects for participants joining and leaving group conversations.
dm_conversation_id string

The unique identifier of the conversation the event is apart of.

"dm_conversation_id": "1584988213961031680"

Use this to programmatically retrieve events from a conversation, and add Direct Messages to it.
created_at date (ISO 8601)

Creation time (UTC) of the Tweet.

"created_at": "2019-06-04T23:12:08.000Z"

This field can be used to understand when a Direct Message was created or when conversation participants joined or left.
referenced_tweets array

ID for any Tweet mentioned in the Direct Message text. To expand this object in the response, include referenced_tweets.id as an expansion and use the tweet.fields query parameter to specify Tweet object attributes of interest.

"referenced_tweets": [

    {

        "id": "1578868150510456833"

    }

]

When Direct Messages reference a Tweet, these IDs can be used to lookup the Tweet's details.
attachments object

For Direct Messages with attached Media, provides the media key of the uploaded content (photo, video, or GIF. To expand this object in the response, include attachments.media_keys as an expansion and use the media.fields query parameter to specify media object attributes of interest. Currently, one attachment is supported. 

"attachments": {

    "media_keys": [

        "3_1136048009270239232"

    ]

}

Understanding the media objects attached to Direct Messages.

Retrieving a Direct Message event object

Sample Request

For this example, we will build a request that retrieves events associated with a one-to-one conversation. This request will return fundamental Direct Message event fields, along with additional fields for referenced Tweets and their authors. Let's build a query that asks for:

  • Fundamental event attributes such as when it was created and what conversation it is part of (dm_conversation).
  • The account ID and description of who sent the Direct Message.
  • The text of any referenced Tweet, and when it was posted.
  • The account ID and description of any referenced Tweet author.

To return those attributes, your request query would include the following:

      ?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description
    
      curl --request GET 'https://api.twitter.com/2/dm_conversations/with/:participant_id/dm_events?tweet.fields=created_at,text,author_id&user.fields=description&expansions=sender_id,participant_ids,referenced_tweets.id&dm_event.fields=id,sender_id,text,participant_ids,created_at,' 
    --header 'Authorization: Bearer $BEARER_TOKEN'
    

Be sure to replace $BEARER_TOKEN with your own generated Bearer Token.

Sample Response

      {
	"data": [{
			"id": "1585047616894574596",
			"sender_id": "944480690",
			"text": "Hello, just you!",
			"created_at": "2022-10-25T23:16:15.000Z",
			"event_type": "MessageCreate",
			"dm_conversation_id": "944480690-906948460078698496"
		},
		{
			"id": "1581048670673260549",
			"sender_id": "944480690",
			"text": "Simple Tweet link: https://t.co/IYFbRIdXHg",
			"referenced_tweets": [{
				"id": "1578900353814519810"
			}],
			"created_at": "2022-10-14T22:25:52.000Z",
			"event_type": "MessageCreate",
			"dm_conversation_id": "944480690-906948460078698496"
		},
		{
			"id": "1580705121553420292",
			"sender_id": "944480690",
			"text": "Adding a new 1-to-1 Direct Message.",
			"created_at": "2022-10-13T23:40:43.000Z",
			"event_type": "MessageCreate",
			"dm_conversation_id": "944480690-906948460078698496"
		}
	],
	"includes": {
		"users": [{
				"name": "API Demos",
				"description": "Hosting TwitterDev integrations... @TwitterDev #DevRel",
				"id": "944480690",
				"username": "FloodSocial"
			},
			{
				"name": "the SnowBot",
				"description": "Home of the @TwitterDev SnowBot... Serving snow reports, snow photos, and snow research links... Chatbot is currently being remodeled for Twitter APIv2.",
				"id": "906948460078698496",
				"username": "SnowBotDev"
			}
		],
		"tweets": [{
				"text": "Feeling kind of bad that I didn’t wish everybody a happy new Colorado Water Year…\n\nHappy Water Year to all my Colorado friends and colleagues, new and old… \n\nMay this be a generous water year, although not too generous…",
				"id": "1578900353814519810",
				"created_at": "2022-10-09T00:09:13.000Z",
				"author_id": "944480690",
				"edit_history_tweet_ids": [
					"1578900353814519810"
				]
			}
		]
	},
	"meta": {
		"result_count": 3,
		"next_token": "18LAA581J5II7LA00C00ZZZZ",
		"previous_token": "1BLC45G1H8CAL5DG0G00ZZZZ"
	}
}