GET direct_messages

API version 1.1
Updated on Tue, 2013-01-29 08:08

Returns the 20 most recent direct messages sent to the authenticating user. Includes detailed information about the sender and recipient user. You can request up to 200 direct messages per call, up to a maximum of 800 incoming DMs.

Important: This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.

Resource URL

https://api.twitter.com/1.1/direct_messages.json

Parameters

since_id optional

Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.

Example Values: 12345

max_id optional

Returns results with an ID less than (that is, older than) or equal to the specified ID.

Example Values: 54321

count optional

Specifies the number of direct messages to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of Tweets to return because suspended or deleted content is removed after the count has been applied.

Example Values: 5

include_entities optional

The entities node will not be included when set to false.

Example Values: false

skip_status optional

When set to either true, t or 1 statuses will not be included in the returned user objects.

Example Request

GET

https://api.twitter.com/1.1/direct_messages.json?since_id=240136858829479935&count=1 

  1. [
  2. {
  3.     "created_at": "Mon Aug 27 17:21:03 +0000 2012", 
  4.     "entities": {
  5.         "hashtags": [], 
  6.         "urls": [], 
  7.         "user_mentions": []
  8.     }, 
  9.     "id": 240136858829479936, 
  10.     "id_str": "240136858829479936", 
  11.     "recipient": {
  12.         "contributors_enabled": false, 
  13.         "created_at": "Thu Aug 23 19:45:07 +0000 2012", 
  14.         "default_profile": false, 
  15.         "default_profile_image": false, 
  16.         "description": "Keep calm and test", 
  17.         "favourites_count": 0, 
  18.         "follow_request_sent": false, 
  19.         "followers_count": 0, 
  20.         "following": false, 
  21.         "friends_count": 10, 
  22.         "geo_enabled": true, 
  23.         "id": 776627022, 
  24.         "id_str": "776627022", 
  25.         "is_translator": false, 
  26.         "lang": "en", 
  27.         "listed_count": 0, 
  28.         "location": "San Francisco, CA", 
  29.         "name": "Mick Jagger", 
  30.         "notifications": false, 
  31.         "profile_background_color": "000000", 
  32.         "profile_background_image_url": "http://a0.twimg.com/profile_background_images/644522235/cdjlccey99gy36j3em67.jpeg", 
  33.         "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/644522235/cdjlccey99gy36j3em67.jpeg", 
  34.         "profile_background_tile": true, 
  35.         "profile_image_url": "http://a0.twimg.com/profile_images/2550226257/y0ef5abcx5yrba8du0sk_normal.jpeg", 
  36.         "profile_image_url_https": "https://si0.twimg.com/profile_images/2550226257/y0ef5abcx5yrba8du0sk_normal.jpeg", 
  37.         "profile_link_color": "000000", 
  38.         "profile_sidebar_border_color": "000000", 
  39.         "profile_sidebar_fill_color": "000000", 
  40.         "profile_text_color": "000000", 
  41.         "profile_use_background_image": false, 
  42.         "protected": false, 
  43.         "screen_name": "s0c1alm3dia", 
  44.         "show_all_inline_media": false, 
  45.         "statuses_count": 0, 
  46.         "time_zone": "Pacific Time (US & Canada)", 
  47.         "url": "http://cnn.com", 
  48.         "utc_offset": -28800, 
  49.         "verified": false
  50.     }, 
  51.     "recipient_id": 776627022, 
  52.     "recipient_screen_name": "s0c1alm3dia", 
  53.     "sender": {
  54.         "contributors_enabled": true, 
  55.         "created_at": "Sat May 09 17:58:22 +0000 2009", 
  56.         "default_profile": false, 
  57.         "default_profile_image": false, 
  58.         "description": "I taught your phone that thing you like.  The Mobile Partner Engineer @Twitter. ", 
  59.         "favourites_count": 584, 
  60.         "follow_request_sent": false, 
  61.         "followers_count": 10621, 
  62.         "following": false, 
  63.         "friends_count": 1181, 
  64.         "geo_enabled": true, 
  65.         "id": 38895958, 
  66.         "id_str": "38895958", 
  67.         "is_translator": false, 
  68.         "lang": "en", 
  69.         "listed_count": 190, 
  70.         "location": "San Francisco", 
  71.         "name": "Sean Cook", 
  72.         "notifications": false, 
  73.         "profile_background_color": "1A1B1F", 
  74.         "profile_background_image_url": "http://a0.twimg.com/profile_background_images/495742332/purty_wood.png", 
  75.         "profile_background_image_url_https": "https://si0.twimg.com/profile_background_images/495742332/purty_wood.png", 
  76.         "profile_background_tile": true, 
  77.         "profile_image_url": "http://a0.twimg.com/profile_images/1751506047/dead_sexy_normal.JPG", 
  78.         "profile_image_url_https": "https://si0.twimg.com/profile_images/1751506047/dead_sexy_normal.JPG", 
  79.         "profile_link_color": "2FC2EF", 
  80.         "profile_sidebar_border_color": "181A1E", 
  81.         "profile_sidebar_fill_color": "252429", 
  82.         "profile_text_color": "666666", 
  83.         "profile_use_background_image": true, 
  84.         "protected": false, 
  85.         "screen_name": "theSeanCook", 
  86.         "show_all_inline_media": true, 
  87.         "statuses_count": 2608, 
  88.         "time_zone": "Pacific Time (US & Canada)", 
  89.         "url": null, 
  90.         "utc_offset": -28800, 
  91.         "verified": false
  92.     }, 
  93.     "sender_id": 38895958, 
  94.     "sender_screen_name": "theSeanCook", 
  95.     "text": "booyakasha"
  96. }
  97. ]