Sending and receiving events
POST direct_messages/new (deprecated, sunset August 16th, 2018)¶
Important: This endpoint will be deprecated and non-functional on August 16, 2018. See the DM Migration Guide for further information.
Sends a new Direct Message to the specified user from the authenticating user. Requires both the user and text parameters and must be a POST. Returns the sent message if successful.
Direct Message Behavior¶
The standard behavior of Direct Messages on Twitter requires that the recipient be following the sender. In most cases, any Direct Message sent to a recipient that is not following the sender will not be delivered and an error message will be returned.
Alternatively, a recipient may have their allow_dms_from account setting set to “all”. In this case, any Direct Message sent to the recipient will be delivered, regardless of whether the recipient follows the sender.
Once a Direct Message thread is established between two users, that thread can be used to send messages bi-directionally, regardless of the follow relationship. To discontinue the thread (effectively, leave the conversation), it is necessary to either explicitly leave the conversation in the Twitter client/website or perform a block of the user via the APIs or Twitter client/website.
Note
Besides determining the follow status between two users via friendships/lookup, you are unable to determine if you can Direct Message a user via the API. If your app requires such behavior, you may apply for whitelisted access using this form. Your use case will be reviewed and not all requests will be granted. Your app may always attempt to send the Direct Message and handle any errors gracefully.
Resource URL¶
https://api.twitter.com/1.1/direct_messages/new.json
Resource Information¶
| Response formats | JSON |
| Requires authentication? | Yes (user context only) |
| Rate limited? | Yes |
Parameters¶
| Name | Required | Description | Default Value | Example |
| user_id | optional | The ID of the user who should receive the Direct Message. Helpful for disambiguating when a valid user ID is also a valid screen name. | 12345 | |
| screen_name | optional | The screen name of the user who should receive the Direct Message. Helpful for disambiguating when a valid screen name is also a user ID. | noradio | |
| text | required | The text of your Direct Message. Be sure to URL encode as necessary. | Meet me behind the cafeteria after school |
Example Request¶
POST https://api.twitter.com/1.1/direct_messages/new.json?text=hello%2C%20tworld.%20welcome%20to%201.1.&screen_name=theseancook
Example Response¶
{
"created_at": "Tue Aug 28 00:59:49 +0000 2012",
"entities": {
"hashtags": [],
"urls": [],
"user_mentions": []
},
"id": 240252311455277056,
"id_str": "240252311455277056",
"recipient": {
"contributors_enabled": true,
"created_at": "Sat May 09 17:58:22 +0000 2009",
"default_profile": false,
"default_profile_image": false,
"description": "I taught your phone that thing you like. The Mobile Partner Engineer @Twitter. ",
"favourites_count": 584,
"follow_request_sent": false,
"followers_count": 10622,
"following": true,
"friends_count": 1181,
"geo_enabled": true,
"id": 38895958,
"id_str": "38895958",
"is_translator": false,
"lang": "en",
"listed_count": 190,
"location": "San Francisco",
"name": "Sean Cook",
"notifications": false,
"profile_background_color": "1A1B1F",
"profile_background_image_url": "http://a0.twimg.com/profile_background_images/495742332/purty_wood.png",
"profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/495742332/purty_wood.png",
"profile_background_tile": true,
"profile_image_url": "http://a0.twimg.com/profile_images/1751506047/dead_sexy_normal.JPG",
"profile_image_url_https": "https://si0.twimg.com/profile_images/1751506047/dead_sexy_normal.JPG",
"profile_link_color": "2FC2EF",
"profile_sidebar_border_color": "181A1E",
"profile_sidebar_fill_color": "252429",
"profile_text_color": "666666",
"profile_use_background_image": true,
"protected": false,
"screen_name": "theSeanCook",
"show_all_inline_media": true,
"statuses_count": 2608,
"time_zone": "Pacific Time (US & Canada)",
"url": null,
"utc_offset": -28800,
"verified": false
},
"recipient_id": 38895958,
"recipient_screen_name": "theSeanCook",
"sender": {
"contributors_enabled": false,
"created_at": "Thu Aug 23 19:45:07 +0000 2012",
"default_profile": false,
"default_profile_image": false,
"description": "Keep calm and test",
"favourites_count": 0,
"follow_request_sent": false,
"followers_count": 0,
"following": false,
"friends_count": 11,
"geo_enabled": true,
"id": 776627022,
"id_str": "776627022",
"is_translator": false,
"lang": "en",
"listed_count": 0,
"location": "San Francisco, CA",
"name": "Mick Jagger",
"notifications": false,
"profile_background_color": "000000",
"profile_background_image_url": "http://a0.twimg.com/profile_background_images/644522235/cdjlccey99gy36j3em67.jpeg",
"profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/644522235/cdjlccey99gy36j3em67.jpeg",
"profile_background_tile": true,
"profile_image_url": "http://a0.twimg.com/profile_images/2550256790/hv5rtkvistn50nvcuydl_normal.jpeg",
"profile_image_url_https": "https://si0.twimg.com/profile_images/2550256790/hv5rtkvistn50nvcuydl_normal.jpeg",
"profile_link_color": "000000",
"profile_sidebar_border_color": "000000",
"profile_sidebar_fill_color": "000000",
"profile_text_color": "000000",
"profile_use_background_image": false,
"protected": false,
"screen_name": "s0c1alm3dia",
"show_all_inline_media": false,
"statuses_count": 0,
"time_zone": "Pacific Time (US & Canada)",
"url": "http://cnn.com",
"utc_offset": -28800,
"verified": false
},
"sender_id": 776627022,
"sender_screen_name": "s0c1alm3dia",
"text": "hello, tworld. welcome to 1.1."
}