Buttons

Buttons enable developers to add up to three call-to-action (CTA) buttons to any Direct Message or Welcome Message. These buttons can be used to open any URL from the Direct Message compose view. The text labels displayed on the buttons can be fully customized.

This feature is intended to make it easier for users to complete actions outside of Direct Messages, whether in a webview or in another part of the Twitter app. For instance, buttons can be used to:

• Open a webview to interact with a mobile web page that is better suited for completing an action than completing that action in messaging. For example, completing a credit card purchase or interacting with a side-by-side comparison of different products.

• Compose a Tweet at the end of a Direct Message interaction. For example, to tell others about a bot or share a coupon publicly. This can be accomplished by using the Tweet web intents URL scheme.

• Follow a user account at the end of a Direct Message interaction. For example, as a final request from a business at the end of a customer service interaction. This can be accomplished using the Follow web intents URL scheme.

• Send a Direct Message to a different account. For example, to direct a user from a marketing-related bot to a separate dedicated customer service @username to get help from a person. This can be accomplished using the Direct Message URL deep link scheme. Example below.

  https://twitter.com/messages/compose?recipient_id=3805104374

CTAs Object¶

Buttons can be added to a Direct Message by defining a ctas array of 1-3 objects.

Example Request¶

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {
        "recipient_id": "844385345234"
      },
      "message_data": {
        "text": "Flight SF8020 from San Francisco to Montreal is ahead of schedule and will land in approximately 15 minutes. Can we help with anything else?",
        "ctas": [
          {
            "type": "web_url",
            "label": "See flight details",
            "url": "https://www.myairline.domain/see-flight-details"
          },
          {
            "type": "web_url",
            "label": "Map it",
            "url": "https://www.myairline.domain/map-it"
          },
          {
            "type": "web_url",
            "label": "Visit MyAirline.domain",
            "url": "https://www.myairline.domain/"
          }
        ]
      }
    }
  }
}

Example Read Response¶

The following JSON payload is an example of what will be received using an Account Activity webhook or GET request like GET direct_messages/events/list. Notice the addition of the t.co short URL representation of the full URLs.

{
  "event": {
    "type": "message_create",
    "message_create": {
      "target": {
        "recipient_id": "844385345234"
      },
      "message_data": {
        "text": "Flight SF8020 from San Francisco to Montreal is ahead of schedule and will land in approximately 15 minutes. Can we help with anything else?",
        "ctas": [
          {
            "type": "web_url",
            "label": "See flight details",
            "tco_url": "https://t.co/foo1",
            "url": "https://www.myairline.domain/see-flight-details"
          },
          {
            "type": "web_url",
            "label": "Map it",
            "tco_url": "https://t.co/foo2",
            "url": "https://www.myairline.domain/map-it"
          },
          {
            "type": "web_url",
            "label": "Visit MyAirline.domain",
            "tco_url": "https://t.co/foo3",
            "url": "https://www.myairline.domain/"
          }
        ]
      }
    }
  }
}