POST direct_messages/events/new (message_create)

Publishes a new message_create event resulting in a Direct Message sent to a specified user from the authenticating user. Returns an event in the requested format if successful. Supports publishing Direct Messages with optional Quick Reply and media attachment. Replaces behavior currently provided by POST direct_messages/new.

Requires a JSON POST body and Content-Type header to be set to application/json. Setting Content-Length may also be required if it is not automatically.

Resource URL

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

Resource Information

Response formats JSON
Content-Type application/json
Requires authentication? Yes (user context only)
Rate limited? Yes
Requests / 15-min window (user auth) Refer to your existing rate limit agreements.

Event Object

type (required) The type of event you are posting. For Direct Messages, use message_create
message_create.target.recipient_id (required) The ID of the user who should receive the direct message.
message_create.message_data (required) The Message Data Object defining the content to deliver to the reciepient.

Message Data Object

Note

See Attaching Media to Direct Messages for details on including an image, GIF or video in Direct Messages.

Example Request

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {
        "recipient_id": "844385345234"
      },
      "message_data": {
        "text": "Hello World!",
      }
    }
  }
}

Example request using Twurl

twurl -A 'Content-type: application/json' -X POST /1.1/direct_messages/events/new.json -d '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}'

Example Response

{
  "event": {
    "type": "message_create",
    "id": "1234858585",
    "created_timestamp": "1392078023507",
    "message_create": {
      "target": {
        "recipient_id": "844385345234"
      },
      "sender_id": "1241124",
      "message_data": {
        "text": "Hello World!",
        "entities": {
          "hashtags": [],
          "symbols": [],
          "urls": [],
          "user_mentions": []
        },
        "quick_reply": {
          ...
        },
        "attachment": {
          "type": "media",
          "media": {
            ...
          }
        }
      }
    }
  }
}

Note

See media entity documentation for details on returned media object properties.