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

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, and keep the message under 140 characters.   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."
}