Playbook - Building a Simple Customer Engagement Application Using Webhooks — Twitter Developers


Building a Customer Engagement Application on Twitter

**This playbook is currently only usable for Standard DM only Account Activity API.  We will be updating it shortly for use with the All Activities endpoint shortly.**


Welcome to the Twitter Direct Message playbook - building 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.

What are webhooks?

A webhook is a way for a web app to communicate information when it happens. 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. This increases the efficiency between a user and an app as it delivers data when it happens.

History and current state of Direct Messages

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, if you want to allow that.
  • 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 clear.
  • 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

Initial Setup

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

Step 1 - Create a Twitter app

In order to use Twitter's APIs, you will need to register a new application that will be associated with the handle.  This application will be tied to the handle that you register it with, so you should  

  • Create an app at 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.
  • Generate access tokens for the app owner at the bottom of the “Keys and Access Tokens” tab. On this same tab take note of your Consumer Key, Consumer Secret, Access Token and Access Token secret. You will need these to use the API.
  • If you are unfamiliar with Twitter Sign-in and how user contexts work with the Twitter API review Obtaining Access Tokens.

Step 2 - Create a webhook app

To receive message activities, such as Direct Message, for a Twitter user you will need to create a web app that receives HTTPS requests on a webhook URL you determine. At this point, you may wish to clone this Node.js code sample on GitHub onto your machine for reference. Incoming message activities will be sent to your URL as POST requests. For security, your webhook URL must also support incoming GET requests as outlined below.

In order to verify that you are the owner of both the app and the Webhook URL, you will need to perform a challenge response check (CRC) within your application. This will occur when you first register your webhook URL as well as once every 24 hours to ensure that your URL is still valid.

  • A GET request with a parameter named crc_token will be sent to your webhook URL. Your endpoint must return a HMAC SHA-256 hash created from the crc_token and your app Consumer Secret. The crc_token should be expected to change for each incoming CRC request. The crc_token should be used as the message in the calculation, where your Consumer Secret is the key.
  • The CRC check happens randomly in a set time interval to ensure the app/key has not been compromised.  In the event that the response is invalid, activities will cease to be sent to the registered webhook.
  • Response Requirements
    • Valid CRC token in JSON format.
    • Latency less than 1 second.
    • 200 HTTP response code.
    • Example response: {"response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="}
  • Validating the signature header - With each incoming POST request from Twitter a hash signature will be passed in the headers as X-Twitter-Webhooks-Signature. This signature can be used to validate source of the data. The hash signature starts with sha256=indicating the use of HMAC with SHA-256 to generate a message digest of your Twitter app Consumer Secret and payload.
  • Further details and security information can be found here

Step 3 - Obtain User Permission

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.

Basic Definitions

  • 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 on An app is always owned by a single user. The app provides the base context for using the Twitter API.

How are tokens generated? Two scenarios:

  1. User owns the app / Single User - If the user is the owner of the app, you can generate tokens on under the “Keys and Access Tokens” tab. Click the “Create my access tokens” button on the bottom of the page.
  2. User does not own the app / Multiple Users - If your app is going to consume Direct Messages 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 at, 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.

Step 4 - Understanding the endpoints used in the sample application and how they fit together

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 setup your own app based on the sample app you cloned in step 2.

Direct Messages

Welcome Messages

Subscription Endpoints

Debugging Tools

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

Put it all together

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 use the sample app make messages that have quick reply options, buttons to open links, or engaging media attached to them. Those messages can have a custom profiles to make it clear when a human or a chatbot is interacting. Ideally, it looks something like this example.

Other Data Types and Endpoint Reference

Buttons on messages

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 separate dedicated customer service @username to get help from a person. This can be accomplished using the Direct Message deep link scheme (…).
  • 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.

Custom profiles

Custom profiles allow a Direct Message author to present a different identity than that of the Twitter account being used. For example, brands may want customer service agents posting under a single Twitter account to use their own name and photo. A custom profile may also be used to attach a unique identity to a message authored by an automated application or chatbot so that users clearly understand they are talking to a chatbot.

  • Data about which custom profile is used on a specific message is part of the message content that is provided to developers in real-time via their webhooks setup
  • Get a list of all custom profiles currently in Twitter’s system using the GET custom_profiles/list endpoint
  • Get the content of a custom profile based on the ID using the GET custom_profiles/:id endpoint

Technical information on Custom Profiles can be found here.

Ready to build your solution?

Apply for developer access to get started

  • Read Previous
  • Read Next