POST direct_messages/new

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 in the requested format 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 public 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

OAuth Signature Generator

Sign in to see a list of your registered applications.

Example Request

Example Result

{
    "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."
}