Welcome to the Twitter customer engagement playbook, where you will learn how to build a basic chatbot using webhooks and REST API endpoints. In this playbook, you will learn everything that you need to know to create a working customer engagement application with the ability to use welcome messages, quick replies, custom profiles, media attachments, buttons and more.

A webhook is a way for a web app to communicate real-time information. Webhooks are different from streaming because they do not require an active connection in order to receive activities, and different from REST APIs because you do not need to poll.

Since Twitter’s launch in 2006 it has been a world-changing messaging platform. Tweets are a way to deliver a public message to the entire world. Direct Messages are a way to have a conversation, privately. Over the last few years we’ve been making private messaging on Twitter better:

• We’ve made it easier to share public Tweets from the timeline with others in Direct Messages.
• We’ve expanded the character limit in Direct Messages to 10,000 characters.
• We made it possible to receive Direct Messages from anyone.
• We made it simple to start a Direct Message conversation from Tweets, Twitter profiles, and even websites.
• We made Direct Messages more rich and engaging, by allowing media and Cards to be displayed along with text in messages.

Now, we’re making Direct Messages a better channel for developers to build messaging interactions that deliver personalized customer experiences at scale. We provide the ability to get Direct Messages in real-time via Webhooks, and the REST API to implement features that make conversations faster and easier.

• Welcome messages: Welcome messages let businesses greet people and set expectations as they enter a Direct Message conversation—without requiring people to send the first message. Businesses can create multiple welcome messages and deep link directly to a specific greeting from Tweets, websites, or apps.
• Quick replies: Quick replies let businesses prompt people with the best ways to reply to a Direct Message, whether by choosing from a list of options.
• Custom profiles: Override the Twitter profile avatar and display name attached to a message in order to make the human element or chatbot experience more personal.
• Buttons: Attach buttons to messages to make it easy for people to take actions outside of the Direct Message conversation – like composing a Tweet, following an account, or opening a website within the Twitter app.

In order to get the messages required to build great customer experiences you will need to:

• Create a Twitter app with the correct permissions to allow you to receive activities, including Direct Messages, from Twitter accounts via the APIs.
• Use OAuth via Twitter Sign-in to get permission to consume your customers’ Direct Messages
• Configure a Webhook to subscribe to user activities and get the messages you need

In order to create experiences in Direct Messages by responding to the messages you receive and using new features you may want to:

• Create and manage welcome messages using the welcome message REST endpoints
• Attach quick replies and custom profiles to messages and welcome messages using REST endpoints
• Add media to conversations by using a REST endpoint
  

As a developer, there are several steps that you will need to take in order to begin using the Direct Messages services.

• Create an app on the "Apps" page of your approved developer account. If you are creating the app on behalf of your company, it is recommended you create the app with a corporate Twitter account.
• Enable “Read, Write and Access direct messages” on the permissions tab of your app page.
• On the "Keys and Tokens" tab, take note of your app's Consumer Key (API Key) and Consumer Token (API Secret).
• On the same tab, generate your app's Access Token and Access Token Secret. You will need these Access Tokens to register your webhook URL, which is where Twitter will send account events.
• If you are unfamiliar with Twitter Sign-in and how user contexts work with the Twitter API review Obtaining Access Tokens. As you add accounts for which to receive events, you will subscribe them using that account's access tokens.
• Take note of your app's numeric ID, as seen in the "Apps" page of the developer portal. When you apply for Account Activity API access, you'll need this app ID.
  

After creating a Twitter app, the next step is applying for Account Activity API access.

If you would like to use a script with a visual dashboard to get set up with your account activities, you should check out the Twitter Dev-supported Account Activity Dashboard.

• Once you have received Account Activity API access, you need to develop, deploy and host a web app that will receive Twitter webhook events. 
• Create a web app with a URL to use as your webhook to receive events. This is the endpoint deployed on your server to listen for incoming Twitter webhook events. 
  • The URI path is completely up to you. This example would be valid: https://mydomain.com/service/listen
  • If you are listening for webhooks from a variety of sources, a common pattern is: https://mydomain.com/webhook/twitter
  • Note that the specified URL can not include a port specification (https://mydomain.com:5000/NoWorkie).
• As described in our Securing Webhooks guide, a first step is writing code that receives a Twitter Challenge Response Check (CRC) GET request and responds with a properly formatted JSON response. 
• Register your webhook URL. You will make a POST request to a /webhooks.json?url= endpoint. When you make this request Twitter will issue a CRC request to your web app. When a webhook is successfully registered, the response will include a webhook id. This webhook id is needed later when making some requests to the Account Activity API. 
• Twitter will send account webhook events to the URL you registered. Make sure your web app supports POST requests for incoming events. These events will be encoded in JSON. See HERE for example webhook JSON payloads.
• Once your web app is ready, the next step is adding accounts to receive activities for. When adding (or deleting) accounts you will make POST requests referencing the account id. See our guide on adding subscriptions for more information.
• To validate your app and webhook are configured correctly, favorite a Tweet posted by one of the Twitter accounts your app is subscribed to. You should receive a Favorite event via a POST request to your webhook URL for each Favorite your subscribers receive.

In order to perform write actions (create Tweets or messages) on behalf of another account or to read private information from that account, you will need to obtain access tokens. Access tokens provide the user context when using the Twitter API.

• User - A Twitter @user. All write actions on the Twitter API require the context of a user. Chatbots exist on Twitter accounts and are not their own entity. The account the chatbot exists on is a user. Customers interacting with the chatbot are also users. All messages sent on Twitter are between two user entities.
• App - A Twitter app is created in your approved developer account. An app is always owned by a single user. The app provides the base context for using the Twitter API.
  

1. User owns the app / Single User - If the user is the owner of the app, they can generate access tokens on the “Keys and Tokens” tab in an app's "Details" section within the from the "Apps" page in the developer portal. Click the “Create” button on the bottom of the page.
2. User does not own the app / Multiple Users - If your app is going to consume Account Activity events on behalf of multiple users, each user must authenticate with your app to grant permission. To achieve this you must have a web app that implements Twitter Sign-in.

At this point in the process, you should have all of the necessary information to set up an application in the developer portal, perform the initial Challenge Response Check to secure your endpoint, and obtain access tokens in order to publish content on both your own application and on behalf of others who have given explicit permission. Now let's take a look at the different endpoints we will be using in our app.

To make experiences conversational we provide Direct Message data in real time via webhooks which includes metadata about the features in that experience. Additionally, we have REST endpoints to create messages, get welcome messages and custom profile data, and manage these features. Understanding the basic flow below will help you set up your own app based on the sample app you cloned in step 3.

• Data about Direct Messages (sent and received) is provided to developers in real-time via their Account Activity API webhook setup
  • Register a webhook URL for the APP:
    • API call to POST account_activity/all/:env_name/webhooks
    • Developers can only register 1 URL per environment
  • Developer will ask the user to authorize the app via Twitter Sign-in to generate valid access tokens.
  • Add a new subscription (enable the app to receive Direct Messages on behalf of the user via the registered webhook)
    • API call to POST account_activity/all/:env_name/subscriptions
    • User needs to have a valid access token with the app (step 4)
  • Validate your webhooks URL using the PUT account_activity/all/:env_name/webhooks endpoint
  • Retrieve your webhook configuration using the GET account_activity/all/:env_name/webhooks endpoint
• Get all Direct Messages sent and received in the last 30 days using the GET direct_messages/events/list endpoint
• Get a single Direct Message based on the ID using the GET direct_messages/events/show endpoint, there’s no time restriction on this endpoint
• Send a message using POST direct_messages/events/new (message_create)
  
  • This endpoint is referenced in the send-direct-message script here
    

• Create a new welcome message using POST direct_messages/welcome_messages/new
  • This endpoint is referenced in the create-welcome-message script here
• Create a new rule for welcome messages using POST direct_messages/welcome_messages/rules/new
  • This endpoint is referenced in this script here

• Delete a subscriptions using DELETE account_activity/webhooks/:webhook_id/subscriptions
  • This endpoint is referenced in this script
• Get your current webhook configuration using GET account_activity/webhooks
  • This endpoint is referenced in this script

Below is a list of debugging tools you may find useful when building your application:

• Postman - Build mock requests
• Ngrok - Test the code on your local machine
• Runscope - Enables a developer to see how the flow of the API works

Now you’ve created a solution that allows you to access Direct Messages in real-time and create personalized experiences at scale on behalf of customers. You can start conversations with a welcome message for context. You can make messages that have quick reply options, buttons to open links, or engaging media attached to them. Those messages can have a custom profile to make it clear when a human or a chatbot is interacting. Ideally, it looks something like this example.

This feature lets developers add up to three calls-to-action or buttons to any Direct Message or Welcome Message POST request. Buttons can be used to open any https URL and the call-to-action shown to users in the Twitter app can be fully customized.

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

• Compose a Tweet at the end of a Direct Message interaction, e.g. to tell others about a chatot or share a coupon or offer publicly. This can be accomplished by using the Tweet web intents URL scheme.
• Follow a user account at the end of Direct Message interaction, e.g. as a final request from a business at the end of an interaction. This can be accomplished using the Follow button web intents URL scheme.
• Send a Direct Message to a different account, e.g. to direct a user from a marketing-related chatbot to a dedicated customer service @username to get help from a person. This can be accomplished using the Direct Message deep link scheme (twitter.com/messages/compose…).
• Open a webview to interact with a mobile web page that is better suited for completing an action than completing that action in messaging, e.g. completing a credit card purchase or interact with a side-by-side comparison of different products.

Technical information on Buttons can be found here.