POST direct_messages/welcome_messages/new

Creates a new Welcome Message that will be stored and sent in the future from the authenticating user in defined circumstances. Returns the message template in the requested format if successful. Supports publishing with the same elements as Direct Messages (e.g. Quick Replies, media attachments).

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.

Triggering Welcome Messages

Once a Welcome Message is created, it can be triggered by Rules or Buttons.

  • Rules

    Rules determine how and when a Welcome Message is presented to the user. See POST direct_messages/welcome_messages/rules/new for more information about Rules.

  • Buttons

    The Send a Private Message Button and Message Button can specify a specific Welcome Message ID to override a Rule by appending a welcome_message_id parameter to the deeplink URL.

    Button URL Example:

    https://twitter.com/messages/compose?recipient_id=2244994945&welcome_message_id=12345
    

Resource URL

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

Resource Information

Response formats JSON
Content-Type application/json
Requires authentication? Yes (user context only)
Rate limited? Yes

Welcome Message Object

message_data (required) The Message Data Object defining the content of the message template. See POST direct_messages/events/new (message_create) for Message Data object details.

Note

See Attaching Media to Direct Messages for details on including an image, GIF or video in Welcome Messages. Media assets attached to Welcome Messages must have shared field set to true during upload.

Example Request

{
  "welcome_message" : {
    "message_data": {
      "text": "Welcome!",
      "attachment": {
        "type": "media",
        "media": {
          "id": "48909183894931"
        }
      }
    }
  }
}

Example request using Twurl

twurl -A 'Content-type: application/json' /1.1/direct_messages/welcome_messages/new.json -d '{"welcome_message": {"message_data": {"text": "Welcome!", "attachment": {"type": "media", "media": {"id": "48909183894931"}}}}}'

Example Response

{
  "welcome_message" : {
    "id": "844385345234",
    "created_timestamp": "1470182274821",
    "message_data": {
      "text": "Welcome!",
      "attachment": {
        "type": "media",
        "media": {
          ...
        }
      }
    }
  }
}