More updates to our Direct Message APIs to help you build better bots

Today we are releasing a few changes to our APIs to help developers build better bots and human-powered customer experiences in Direct Messages. As we announced today on our marketing blog, it's now possible to attach buttons to Direct Messages. We're also adding two new objects to the Direct Message payload to help developers understand how a conversation started and which app created a message. These updates are part of our ongoing work to improve our Direct Messages platform for developers.

Attaching buttons to messages

Buttons attached to messages make it easier for businesses to guide people to take an action that occurs outside of Direct Messages. This video shows how they can be used to launch the Tweet compose experience from within a Direct Message conversation.

Buttons can be used to open any web URL, including links to other Twitter features such as Tweet Intents and Follow Intents, or Direct Message deep links (e.g. to another account). Developers can attach up to three buttons to a message. The text labels on each button are fully customizable.

There are many cases where it makes sense to use links to let people access more information, complete an action on a website, take another action on Twitter, or present multiple of these options. Simplifying the experience using buttons makes it easier for people to take the desired action.

This pattern is particularly useful on Twitter to get people to tell others about your bot with a Tweet. Developers can now attach a simple button to messages at the right point in a conversation and make it easy to Tweet about the experience. People can share the March Madness bracket they just built, share a coupon they just discovered with their followers, share a news story they just received through a personalized subscription from a publisher, or a video clip from an upcoming movie they just learned about through a bot. Or, they can simply Tweet and tell the world about your bot.

Combined with the Direct Message Card we recently announced, the Tweet that gets shared can include rich content that drives their followers into the bot experience — starting a viral discovery loop. Creating this experience is simple, just use a Tweet Intent link with a Direct Message Card URL included at the end in your button.

When designing a bot, there’s an important design principle to keep in mind — buttons always open another view, they never send messages. Quick replies are used to send messages with a single tap or click.

To learn more about how buttons on messages can be used, see our documentation.

New metadata

There are now two additional objects that are returned in a Direct Message payload.

• initiated_via: This helps developers know how a person entered a conversation if they first engaged with some other object besides a DM -- like a Tweet or welcome message. When applicable, this element will include the Tweet ID that led to the Direct Message (for example, if a person clicked on a Direct Message deep link from a Tweet), and may also include the welcome message ID that led the user to send a Direct Message. By knowing which Tweet or welcome message someone responded to, a developer can accurately reconstruct the full conversation from the user’s perspective, which can be helpful for customer service agents as well as bots.
• source_app_id: This allows developers to know the app that was used to send a message, which can be useful to manage a conversation when a business uses multiple apps. For example, a bot app might know to not reply if they see a message from a human-powered customer service app.

These new features are part of our continued investment in our platform to make it easier to build compelling conversational experiences on Twitter. Developers can see where we’re focusing and what we’re building with our recently published API platform roadmap and those looking to build on our new APIs can learn how to get started here.