Sending and receiving events
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 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 / 24-hour window | 1000 per user; 15000 per app* |
Please note - The 15000 per app rate limit goes into effect on October 22nd, 2018. You can learn more about this change by reading our recent forum post.
Direct Message Rate Limiting¶
When a message is received from a user you may send up to 5 messages in response within a 24 hour window. Each message received resets the 24 hour window and the 5 allotted messages. Sending a 6th message within a 24 hour window or sending a message outside of a 24 hour window will count towards rate-limiting. This behavior only applies when using the POST direct_messages/events/new endpoint.
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¶
curl --request POST
--url https://api.twitter.com/1.1/direct_messages/events/new.json
--header 'authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY", oauth_nonce="AUTO_GENERATED_NONCE", oauth_signature="AUTO_GENERATED_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="AUTO_GENERATED_TIMESTAMP", oauth_token="USERS_ACCESS_TOKEN", oauth_version="1.0"'
--header 'content-type: application/json'
--data '{"event": {"type": "message_create", "message_create": {"target": {"recipient_id": "RECIPIENT_USER_ID"}, "message_data": {"text": "Hello World!"}}}}'
twurl <https://github.com/twitter/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": "RECIPIENT_USER_ID"}, "message_data": {"text": "Hello World!"}}}}'
Example Response¶
{
"event": {
"type": "message_create",
"message_create": {
"target": {
"recipient_id": "RECIPIENT_USER_ID"
},
"message_data": {
"text": "Hello World!",
}
}
}
}
Note
See media entity documentation for details on returned media object properties.