The Account Activity API sends you events related to a Twitter user’s account activities in realtime. For example, the Account Activity API delivers a JSON event payload every time a subscribed user creates or deletes a Tweet, Retweets, receives or sends a Direct Message, follows a new user, or likes a post. You can find a full list of the types of activities served by the Account Activity API in our developer documentation (premium and enterprise).

The Account Activity API is different to Twitter’s REST and streaming APIs, because it uses a combination of REST endpoints for setup and management, and webhooks for data delivery. Webhooks deliver data by “pushing” (aka POSTing) events to the webhook URL of a registered web application. This is done via an HTTP call in real-time when a specific event (aka an account activity) happens on Twitter.

Twitter’s more common APIs are based on a client-server approach, where the developer creates a client application that makes a connection to Twitter’s servers to receive some information. This can be based on a streaming model, where the client connection to Twitter’s servers stays always open to receive data in realtime, or, it can be a client-triggered request, for example if a developer wants to retrieve a specific Tweet object.

With the Account Activity API, this pattern is inverted. Instead of the client application making a connection request to Twitter’s servers, it’s Twitter’s servers that make a connection to the developer’s web application webhook listening for data. In this case, Twitter acts as the client and opens a connection to the developer’s server to post activities to that webhook every time an event occurs.

There are many advantages to using webhook-based APIs:

• From a computing-resourcing perspective, webhooks require less resources than if you have an ongoing open connection to a streaming API.
• There is confirmation on both sides of an activity being delivered per POST with an HTTP 200 response code.
• If an activity is not successfully delivered, there is a built in retry process to re-POST, which reduces the chance of missed data.
• With webhooks, an application no longer has to make periodic polling requests to an API to check for new data to be available.
• New data will automatically be sent to your server as soon as it’s available. Therefore, the data received is almost always the most up-to-date.
  

In order to get started with the Account Activity API, the following elements are required:

• A developer account is required to use any Twitter's APIs. If you don’t have one already, you can apply for one.
• A Twitter developer app with the right permissions. You can create a new app by selecting the “Create an app” button under the Apps section of your developer portal.
  • Make sure to enable “Read, Write, and Direct Messages, on the permissions tab of your app page. Note that permission settings are not retroactive for authorized users with previous lower permission settings.
  • On the “Keys and Access token” tab, take a note of your app’s Consumer API Key and API Secret. This information will enable you to generate a bearer token.
  • You will also have to generate your app’s access token and access token secret. You will need these when you register your webhook URL. 
• A developer environment, which can be set up in the Dev environments section of your developer portal. Select your app and choose an environment name. The name you choose will replace the :env_name token when you start using the different Account Activity API endpoints.
• A specific, secured web application with URL for receiving data through webhooks. A tool like ngrok can be useful for creating a local web address to test your webhooks in development.

In order to receive activities from Twitter via webhooks, you will need to create and secure a web application that can receive HTTP (POST and GET) requests on a URL of your choice. This web application must be secured with the same Twitter app credentials that you set up in your developer environment for the Account Activity API, and coded to create the crc_token using these credentials. Twitter will frequently send your webhook challenge response check (known as CRC) GET requests, for which your web application must return the crc_token generated using the Twitter application credentials that match those of your approved developer environment app.

You can register a webhook URL for the Account Activity API using the POST account_activity/all/:env_name/webhooks endpoint.

All set up for the Account Activity API is done with API requests. There is no user interface built into the developer portal. For testing, however, there is an example dashboard tool available on the TwitterDev GitHub page: https://github.com/twitterdev/account-activity-dashboard.

Your chosen registered webhook URL is where the Account Activity API will send account activities, in the form of HTTP POST requests containing the event data.

Authentication can be tricky with the Account Activity API, because there are different authentication methods for different functions of the API. Most of the webook setup is done through application-only authentication with a bearer token. Review our documentation for more information on how to generate the necessary bearer token.

Subscription setup is done through application-user authentication for each user subscription. If you want to receive events for your own Twitter account, you can use the access token generated with the API key and API secret key from your developer portal, and this is a great way to get started and test the API. However, in order to receive events relating to another Twitter account, the owner of that account will have to grant you permission via the 3-legged OAuth process. This process is also something that you will need to implement in your server-side code, as this will enable you to receive a user’s access tokens.

You will start receiving events for a user as soon as they are subscribed to your webhook URL. So, what exactly is an event? In this case, an event corresponds with an activity related to the Twitter account of a subscribed user. Each event is delivered in the form of a JSON payload that your app can consume. As you can see in the example below, a "message create" event is delivered when the user receives a Direct Message. There is a "text" field that contains the content of the message and other information.