POST direct_messages/new

Updated on Sat, 2012-08-25 10:52

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/direct_messages/new.format

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

Extended description

The URL pattern /version/direct_messages/new.format?user=:screen_name_or_user_id is still accepted but not recommended. As a sequence of numbers is a valid screen name we recommend using the screen_name or user_id parameter instead.

Example Request

POST

https://api.twitter.com/1/direct_messages/new.format

POST Data

screen_name=themattharris&text=Hey%2C%20still%20ok%20for%20dinner%20tonight%3F

  1. {
  2.   "created_at": "Tue Jun 22 17:47:27 +0000 2010",
  3.   "sender_screen_name": "mattytest",
  4.   "sender": {
  5.     "name": "mattytest",
  6.     "profile_sidebar_border_color": "C0DEED",
  7.     "profile_background_tile": false,
  8.     "profile_sidebar_fill_color": "DDEEF6",
  9.     "location": "",
  10.     "profile_image_url": "http://a1.twimg.com/profile_images/644612310/matt_bright_normal.png",
  11.     "created_at": "Thu Jan 22 16:27:50 +0000 2009",
  12.     "profile_link_color": "0084B4",
  13.     "favourites_count": 0,
  14.     "url": null,
  15.     "contributors_enabled": false,
  16.     "utc_offset": -28800,
  17.     "id": 19345946,
  18.     "profile_use_background_image": false,
  19.     "profile_text_color": "333333",
  20.     "protected": true,
  21.     "followers_count": 3,
  22.     "lang": "en",
  23.     "verified": false,
  24.     "profile_background_color": "C0DEED",
  25.     "geo_enabled": true,
  26.     "notifications": false,
  27.     "description": "",
  28.     "time_zone": "Tijuana",
  29.     "friends_count": 2,
  30.     "statuses_count": 9,
  31.     "profile_background_image_url": "http://s.twimg.com/a/1277162817/images/themes/theme1/bg.png",
  32.     "screen_name": "mattytest",
  33.     "following": false
  34.   },
  35.   "text": "Hey, still ok for dinner tonight?",
  36.   "recipient_screen_name": "themattharris",
  37.   "id": 1270516771,
  38.   "recipient": {
  39.     "name": "Matt Harris",
  40.     "profile_sidebar_border_color": "C0DEED",
  41.     "profile_background_tile": false,
  42.     "profile_sidebar_fill_color": "DDEEF6",
  43.     "location": "San Francisco",
  44.     "profile_image_url": "http://a1.twimg.com/profile_images/554181350/matt_normal.jpg",
  45.     "created_at": "Sat Feb 17 20:49:54 +0000 2007",
  46.     "profile_link_color": "0084B4",
  47.     "favourites_count": 95,
  48.     "url": "http://themattharris.com",
  49.     "contributors_enabled": false,
  50.     "utc_offset": -28800,
  51.     "id": 777925,
  52.     "profile_use_background_image": true,
  53.     "profile_text_color": "333333",
  54.     "protected": false,
  55.     "followers_count": 1025,
  56.     "lang": "en",
  57.     "verified": false,
  58.     "profile_background_color": "C0DEED",
  59.     "geo_enabled": true,
  60.     "notifications": false,
  61.     "description": "Developer Advocate at Twitter. Also a hacker and British expat who is married to @cindyli and lives in San Francisco.",
  62.     "time_zone": "Tijuana",
  63.     "friends_count": 294,
  64.     "statuses_count": 2923,
  65.     "profile_background_image_url": "http://s.twimg.com/a/1276711174/images/themes/theme1/bg.png",
  66.     "screen_name": "themattharris",
  67.     "following": true
  68.   },
  69.   "recipient_id": 777925,
  70.   "sender_id": 19345946
  71. }