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.

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

One of user_id or screen_name are required.

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.

Example Values: 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.

Example Values: noradio

text required

The text of your direct message. Be sure to URL encode as necessary, and keep the message under 140 characters.

Example Values: Meet me behind the cafeteria after school

OAuth Signature Generator

Sign in to see a list of your registered applications.

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