Account Activity API: Enterprise

Overview

Enterprise

The Account Activity API provides you the ability to subscribe to realtime activities related to a user account via webhooks. This means that you can receive realtime Posts, Direct Messages, and other account events from one or more of your owned or subscribed accounts through a single connection.

You will receive all related activities below for each user subscription on your webhook registration:

Please note - We do not deliver home timeline data via the Account Activity API. Please use the GET statuses/home_timeline to pull this data.  

​

Video Series

Check out our four-part video series on the Account Activity API to get up to speed!

​

Feature summary

• Have questions? Running into errors?

  • Read our Frequently asked questions or Error Troubleshooting guide.

• Explore our sample code:

  • Enterprise Account Activity API dashboard, a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes Replay functionality.
  • The SnowBot chatbot, a Ruby web app built on the enterprise Account Activity and Direct Message APIs.

​

Manage webhooks and subscribed users

⏱ 10 min read

The enterprise Account Activity API provides you webhook-based JSON messages any time there are events associated with X accounts subscribed to your service. X delivers those activities to your registered webhook. In the following steps, you will learn how to manage webhooks and subscribed users.

You will learn how to register, view, and remove, both webhooks and subscribed users. We’ll be using simple cURL commands to make requests to the various API endpoints. cURL is a command-line tool for getting or sending requests using the URL syntax.

You will need:

• A registered X app - register here
• A bearer token - learn more
• A webhook that passes a Challenge-Response Check (CRC) - learn more
• An enterprise account - [apply here]https://developer.x.com/en/products/x-api/enterprise

Before you get started, we recommend you check out our Github repo here that provides a sample web app and helper scripts to get started with X’s Account Activity API

​

Managing a webhook:

Using a webhook provides you the ability to subscribe to realtime activities related to a user account through a single connection. 

• Adding a webhook
• Viewing a webhook
• Removing a webhook

​

Managing subscribed users:

Once you’ve registered a Webhook, you can add a subscribed user to the Account Activity API to begin receiving their account activities.

• Adding a subscription
• Viewing subscriptions
• Removing a subscription

Great job! You should now able to manage your webhooks and subscribed users.

​

Referenced articles

• Overview of Challenge-Response Check (CRC)
• [Account Activity Data Types](/x-api/x-api-v2/enterprise-gnip-2.0/fundamentals/account-activity#account-activity-data-object-structure
• Managing Webhooks and Subscriptions

​

A video walkthrough of the Account Activity API

In this video walkthrough, you will learn about the capabilities of the premium and enterprise tiers of the Account Activity API.

By the end of this video, you will learn about the following capabilities.

• Registering a webhook
• Adding a user subscription
• Removing a user subscription
• Receiving account activities
• Replay account activities

• Have questions? Running into errors?

  • Read our Frequently asked questions or Error Troubleshooting guide.

• Explore our sample code:

  • Enterprise Account Activity API dashboard, a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes Replay functionality.
  • The SnowBot chatbot, a Ruby web app built on the enterprise Account Activity and Direct Message APIs.

Enterprise

​

Getting started with webhooks

The Account Activity API is a webhook-based API that sends account events to a web app you develop, deploy and host. 

There are several ‘plumbing’ details that need attention before you can start receiving webhook events in your event consumer application. As described below, you will need to create a X app, obtain Account Activity API access, and develop a web app that consumes webhook events. 

​

1. Create a X app.

• Create a X app with an approved developer account from the developer portal. If you are creating the app on behalf of your company, it is recommended you create the app with a corporate X account. To apply for a developer account, click here.
• Enable “Read, Write and Access direct messages” on the permissions tab of your app page.
• On the “Keys and Access 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 X will send account events.
• If you are unfamiliar with X Sign-in and how user contexts work with the X 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.  

​

2. Get Account Activity API access

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

Account Activity API is only availble on Enterprise, so you will need to submit an application using the link below.

​

3. Develop webhook consumer app

Once you have received Account Activity API access, you need to develop, deploy and host a web app that will receive X 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 X 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 X 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 X 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. 

• X 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.

​

4. Validate setup

• To validate your app and webhook are configured correctly, favorite a Post posted by one of the X accounts your app is subscribed to. You should receive a favorite_events via a POST request to your webhook URL for each Favorite your subscribers receive.
• Note that it may take up to 10 seconds for events to start being delivered after a subscription has been added.

Important Notes

• When registering your webhook URL, your web app must authenticate with its consumer token and secret and the app owner’s user access token and secret. 

• All incoming Direct Messages will be delivered via webhooks. All Direct Messages sent via POST direct_messages/events/new (message_create) will also be delivered via webhooks. This is so your web app can be aware of Direct Messages sent via a different client.

• Note that every webhook event includes a for_user_id user ID that indicates which subscription the event was delivered for.

• If you have two users using your web app for Direct Messages in the same conversation, your webhook will receive two duplicate events (one for each user). Your web app should account for this. 

• If you have more than one web app sharing the same webhook URL and the same user mapped to each app, the same event will be sent to your webhook multiple times (once per web app).

• In some cases, your webhook may receive duplicate events. Your webhook app should be tolerant of this and dedupe by event ID.

• Do not expect Quick Reply response to directly follow a request. A user has the ability to ignore a Quick Reply request and may respond via traditional Direct Message. The user may also provide a Quick Reply response to a request they have not replied to earlier in the message thread.

• See example code:

  • Enterprise Account Activity API dashboard, a node web app that displays webhook events using the enterprise tier of the Account Activity API and includes Replay functionality.

  • The SnowBot chatbot, a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a script to help set up Account Activity API webhooks.

​

Securing webhooks

X’s webhook-based APIs provide two methods for confirming the security of your webhook server:

1. The challenge-response checks enable X to confirm the ownership of the web app receiving webhook events. 
2. The signature header in each POST request enables you to confirm that X is the source of the incoming webhooks.  

​

Challenge-Response Checks 

In order to verify that you are both the owner of the app and the webhook URL, X will perform a Challenge-Response Check (CRC), which is not to be confused with a cyclic redundancy check. When a CRC is sent, X will make a GET request of your web app with a ;crc_token parameter. When that request is received, your web app needs to build an encrypted response_token based on the crc_token parameter and your app’s Consumer Secret (details below). The response_token must be encoded in JSON (see example below) and returned within three seconds. When successful, a webhook id will be returned. 

A CRC will be sent when you register your webhook URL, so implementing your CRC response code is a fundamental first step. Once your webhook is established, X will trigger a CRC roughly every 24 hours from the last time we received a successful response. Your app can also trigger a CRC when needed by making a PUT request with your webhook id. Triggering a CRC is useful as you develop your webhook application, after deploying new code and restarting your service. 

The crc_token should be expected to change for each incoming CRC request and should be used as the message in the calculation, where your Consumer Secret is the key.

In the event that the response is not posted within 3 seconds or becomes invalid, events will cease to be sent to the registered webhook.

​

The CRC request will occur:

• When a webhook URL is registered.
• Approximately hourly to validate your webhook URL.
• You can manually trigger a CRC by making a PUT request. As you develop your webhook client, you should plan on manually triggering the CRC as you develop your CRC response.   

​

Response requirements:

• A base64 encoded HMAC SHA-256 hash created from the crc_token and your app Consumer Secret
• Valid response_token and JSON format.
• Latency less than 3 seconds.
• 200 HTTP response code.  

​

Language-specific HMAC libraries:

• Java/Scala
• Ruby
• Node.js
• Python

​

Example response token generation in Python:

The following defines a route in a Python 2.7 Flask webapp that will respond to the challenge response check correctly.

import base64
import hashlib
import hmac
import json


\# Defines a route for the GET request
@app.route('/webhooks/twitter', methods=\['GET'\])
def webhook_challenge():

  # creates HMAC SHA-256 hash from incomming token and your consumer secret
  sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest()

  # construct response data with base64 encoded hash
  response = {
    'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest)
  }

  # returns properly formatted json response
  return json.dumps(response)

​

Example JSON response:

With the route defined as above your webapp should return a response similar to below when navigating to https://your-app-domain/webhooks/twitter?crc_token=foo in your web browser.

{
  "response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="
}

​

Other examples:

• HERE is an example CRC response method written in Node/JS.
• HERE is an example CRC response method written in Ruby (see the generate_crc_response and the /GET route that receives CRC events).

​

Optional signature header validation

When receiving a POST request from X, sending a GET request to create a webhook, or sending a GET request to perform a manual CRC, a hash signature will be passed in the headers as x-twitter-webhooks-signature. This signature can be used to validate the source of the data is X. The POST hash signature starts with sha256= indicating the use of HMAC SHA-256 to encrypt your X App Consumer Secret and payload. The GET hash is calculated from the query parameter string crc_token=token&nonce=nonce. 

Steps to validate a request

1. Create a hash using your consumer secret and incoming payload body.
2. Compare created hash with the base64 encoded x-twitter-webhooks-signature value. Use a method like compare_digest to reduce the vulnerability to timing attacks.

​

Additional security guidelines

The following are additional security guidelines to consider for your web application. Not having these guidelines implemented will not prevent your webhook from functioning, but are highly reccomended by the X Information Security team. If you are unfamilair with the below recommendations consult with your server administrator.

​

X aggregate network blocks

For added security you may wish to add the following aggregate network blocks to an allowlist:

• 199.59.148.0/22

• 199.16.156.0/22

• 192.133.77.0/26

• 64.63.15.0/24

• 64.63.31.0/24

• 64.63.47.0/24

• 202.160.128.0/24

• 202.160.129.0/24

• 202.160.130.0/24

​

Recommended server configurations

• ”A” rating on ssllabs.com test
• Enable TLS 1.2
• Enable Forward Secrecy
• Turn off SSLv2
• Turn off SSLv3 (because of POODLE)
• Turn off TLS 1.0
• Turn off TLS 1.1
• Turn off TLS Compression
• Turn off Session Tickets unless you rotate session ticket keys.
• Set the “ssl_prefer_server_ciphers” or “SSLHonorCipherOrder” option in the SSL Configuration “on”.
• Ensure the list of ciphers is a modern list such as: ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA

​

Managing webhooks and subscriptions

​

Creating & changing webhooks

In order to change webhook URLs, you must delete your existing webhook and then create a new one. Note that when you do this, you will be required to re-add user subscriptions to the new webhook.

​

Webhook configuration management endpoints:

​

Why can’t I just update the webhook URL?

Why are webhook configurations immutable? X takes security very seriously. If your webhook URL is changed, there is a possibility that your application consumer key and consumer secret have been compromised. By requiring you to create a new webhook configuration, you are also required to re-subscribe to your user’s events. This requires the use of access tokens that a malicious party is less likely to possess. As a result, the likelihood that another party will receive your user’s private information is reduced.  

​

Adding & removing User subscriptions

Support for thousands of subscriptions is available with the enterprise tier. If you already have an account manager, please reach out to them with questions.  To apply for access to the enterprise APIs, click here. 

​

Subscription management endpoints

Account Activity API: Enterprise

The Account Activity API consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection. 

There are two authentication methods available with the Account Activity API (OAuth 1.0a and OAuth 2.0 Bearer Token). The authentication method that you should use will depend on which endpoint you are using.

*_ Authentication requires the access tokens of the subscribing user. _

For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request: 

• Consumer Keys (API Key and Secret)
• Access Tokens (Access Token and Secret)

In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the developer portal, under the “Keys and tokens” tab for your App.  

• POST account_activity/webhooks: Register a new webhook URL for the given application context
• PUT account_activity/webhooks/:webhook_id: Trigger a challenge response check (CRC) for a given webhook’s URL
• DELETE account_activity/webhooks/:webhook_id: Delete a webhook

On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see OAuth 1.0a: how to obtain a user’s Access Tokens). These endpoints have been marked with an asterisk in the above table (*).

• POST account_activity/webhooks/:webhook_id/subscriptions/all: Subscribe the application to a user’s account events
• GET account_activity/webhooks/:webhook_id/subscriptions/all: Check if a webhook configuration is subscribed to a user’s events
• DELETE account_activity/webhooks/:webhook_id/subscriptions/all: Deactivate a subscription for the provided user context and application [DEPRECATED]

A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found inthe API reference documentation.

For additional information, check out XDev’s sample web app and helper scripts to get started with the Enterprise Account Activity API.

The Account Activity API consists of a set of endpoints that allow you to create and manage user subscriptions to receive real-time account activities for all of your subscribed accounts through a single connection. 

There are two authentication methods available with the Account Activity API (OAuth 1.0a and OAuth 2.0 Bearer Token). The authentication method that you should use will depend on which endpoint you are using.

*_ Authentication requires the access tokens of the subscribing user. _

For those endpoints that require OAuth 1.0a user context authentication, you will need to provide the following credentials to authenticate the request: 

• Consumer Keys (API Key and Secret)
• Access Tokens (Access Token and Secret)

In the case of the following three endpoints, you perform write actions within the context of your application (no X users are involved). Therefore, the Access Tokens you need to provide are the ones belonging to your developer App. These can be generated directly from within the developer portal, under the “Keys and tokens” tab for your App.  

• POST account_activity/webhooks: Register a new webhook URL for the given application context
• PUT account_activity/webhooks/:webhook_id: Trigger a challenge response check (CRC) for a given webhook’s URL
• DELETE account_activity/webhooks/:webhook_id: Delete a webhook

On the other hand, in the case of the following three endpoints, you are making a request that allows your application to access protected data on behalf of a X user (for example, Direct Messages). You must therefore provide the Access Tokens that belong to the subscribing user in question. The required Access tokens can be obtained using the 3-legged OAuth flow (see OAuth 1.0a: how to obtain a user’s Access Tokens). These endpoints have been marked with an asterisk in the above table (*).

• POST account_activity/webhooks/:webhook_id/subscriptions/all: Subscribe the application to a user’s account events
• GET account_activity/webhooks/:webhook_id/subscriptions/all: Check if a webhook configuration is subscribed to a user’s events
• DELETE account_activity/webhooks/:webhook_id/subscriptions/all: Deactivate a subscription for the provided user context and application [DEPRECATED]

A list of all endpoints available with the Account Activity API, including associated description and example cURL requests with authentication implementation examples, can be found inthe API reference documentation.

For additional information, check out XDev’s sample web app and helper scripts to get started with the Enterprise Account Activity API.

​

Retries

Enterprise

One of the benefits of the enterprise tier of the Account Activity API is a retry mechanism for webhook events. If a ‘success’ 200 HTTP response code is not received, the X server will initiate a retry mechanism, resending the webhook event up to three times over a five-minute period. This webhook event retry service helps provide reliability and event recovery when network problems occur and during client-side service interruptions and deploys.  

​

What are retries?

The Account Activity API provides a retry feature when the client’s web app does not return a ‘success’ 200 response for an account activity webhook event. When the client-side does not confirm the successful receipt of an event, X assumes the event was not received. If a non-200 response is received, a response isn’t received within three seconds, or we don’t receive a response at all, we retry the request and leave that open for three seconds. This means that you have roughly five seconds over two attempts to respond to receive the activity that we are trying to send to your webhook URL. In the event that your server doesn’t response or returns a transient error, we will retry for five minutes. There will be a total of three retry attempts to confirm validation. This allows redundancy and insurance that you receive all webhook events. Note that subscriptions with retries will get retried events for any/all activities for all subscribed users on their webhook.

If you do not confirm validation within these eight attempts, the activity will no longer be available via the Account Activity API. 

​

Retry timeline

The Account Activity API will retry up to three times over a five-minute period until a 200 response is received.  Refer to the table below for more details. After around five minutes, the activity cannot be resent through the Account Activity API. You will need to use other X endpoints to collect missed data. For example, the search APIs can be used to retrieve relevant Posts, Retweets, Quote Tweets, Mentions, and Replies. Missed Direct Messages can be retrieved with this endpoint.

​

Retries timeline

​

Account Activity data object structure

Available Activities

Payload examples

See the payload examples below for each Account Activity event described in the table above.

​

tweet_create_events (Posts, Retweets, Replies, QuoteTweets) 

{
	"for_user_id": "2244994945",
	"tweet_create_events": [
	  {
		<Tweet Object>
	  }
	]
}

​

tweet_create_events (@mentions) 

{
	"for_user_id": "2244994945",
	"user_has_blocked": "false",
	"tweet_create_events": [
	  {
		<Tweet Object>
	  }
	]
}

​

favorite_events

{
	"for_user_id": "2244994945",
	"favorite_events": [{
		"id": "a7ba59eab0bfcba386f7acedac279542",
		"created_at": "Mon Mar 26 16:33:26 +0000 2018",
		"timestamp_ms": 1522082006140,
		"favorited_status": {
			<Tweet Object>
		},
		"user": {
			<User Object>
		}
	}]
}

​

follow_events

{
	"for_user_id": "2244994945",
	"follow_events": [{
			"type": "follow",
			"created_timestamp": "1517588749178",
			"target": {
				<User Object >
			},
			"source": {
				< User Object >
			}
		]
	}
}

​

unfollow_events

{
	"for_user_id": "2244994945",
	"follow_events": [{
			"type": "unfollow",
			"created_timestamp": "1517588749178",
			"target": {
				<User Object >
			},
			"source": {
				< User Object >
			}
		]
	}
}

​

block_events

{
	"for_user_id": "2244994945",
	"block_events": [{
		"type": "block",
		"created_timestamp": "1518127020304",
		"source": {
			<User Object>
		},
		"target": {
			<User Object>
		}
	}]
}

​

unblock_events

{
	"for_user_id": "2244994945",
	"block_events": [{
		"type": "unblock",
		"created_timestamp": "1518127020304",
		"source": {
			<User Object>
		},
		"target": {
			<User Object>
		}
	}]
}

​

mute_events

{
	"for_user_id": "2244994945",
	"mute_events": [
		{
			"type": "mute",
		  	"created_timestamp": "1518127020304",
			"source": {
				<User Object>
			},
			"target": {
				<User Object>
			}
		}
	]
}

​

unmute_events

{
	"for_user_id": "2244994945",
	"mute_events": [
		{
			"type": "unmute",
		  	"created_timestamp": "1518127020304",
			"source": {
				<User Object>
			},
			"target": {
				<User Object>
			}
		}
	]
}

​

user_event

{
	"user_event": {
		"revoke": {
			"date_time": "2018-05-24T09:48:12+00:00",
			"target": {
				"app_id": "13090192"
			},
			"source": {
				"user_id": "63046977"
			}
		}
	}
}

​

direct_message_events

{
  	"for_user_id": "4337869213",
	"direct_message_events": [{
		"type": "message_create",
		"id": "954491830116155396",
		"created_timestamp": "1516403560557",
		"message_create": {
			"target": {
				"recipient_id": "4337869213"
			},
			"sender_id": "3001969357",
			"source_app_id": "13090192",
			"message_data": {
				"text": "Hello World!",
				"entities": {
					"hashtags": [],
					"symbols": [],
					"user_mentions": [],
					"urls": []
				}
			}
		}
	}],
	"apps": {
		"13090192": {
			"id": "13090192",
			"name": "FuriousCamperTestApp1",
			"url": "https://twitter.com/furiouscamper"
		},
		"users": {},
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "Alter Ego - Twitter PE opinions-are-my-own",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 22,
			"friends_count": 45,
			"statuses_count": 494,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		},
		"4337869213": {
			"id": "4337869213",
			"created_timestamp": "1448312972328",
			"name": "Harrison Test",
			"screen_name": "Harris_0ff",
			"location": "Burlington, MA",
			"protected": false,
			"verified": false,
			"followers_count": 8,
			"friends_count": 8,
			"profile_image_url": "null",
			"statuses_count": 240,
			"profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png"
		}
	}
}

Code copied to clipboard

​

direct_message_indicate_typing_events

{
	"for_user_id": "4337869213",
	"direct_message_indicate_typing_events": [{
		"created_timestamp": "1518127183443",
		"sender_id": "3284025577",
		"target": {
			"recipient_id": "3001969357"
		}
	}],
	"users": {
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "Alter Ego - Twitter PE opinions-are-my-own",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 47,
			"statuses_count": 509,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		},
		"3284025577": {
			"id": "3284025577",
			"created_timestamp": "1437281176085",
			"name": "Bogus Bogart",
			"screen_name": "bogusbogart",
			"protected": true,
			"verified": false,
			"followers_count": 1,
			"friends_count": 4,
			"statuses_count": 35,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg"
		}
	}
}

​

direct_message_mark_read_events

{
	"for_user_id": "4337869213",
	"direct_message_mark_read_events": [{
		"created_timestamp": "1518452444662",
		"sender_id": "199566737",
		"target": {
			"recipient_id": "3001969357"
		},
		"last_read_event_id": "963085315333238788"
	}],
	"users": {
		"199566737": {
			"id": "199566737",
			"created_timestamp": "1286429788000",
			"name": "Le Braat",
			"screen_name": "LeBraat",
			"location": "Denver, CO",
			"description": "data by day @twitter, design by dusk",
			"protected": false,
			"verified": false,
			"followers_count": 299,
			"friends_count": 336,
			"statuses_count": 752,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg"
		},
		"3001969357": {
			"id": "3001969357",
			"created_timestamp": "1422556069340",
			"name": "Jordan Brinks",
			"screen_name": "furiouscamper",
			"location": "Boulder, CO",
			"description": "Alter Ego - Twitter PE opinions-are-my-own",
			"url": "https://t.co/SnxaA15ZuY",
			"protected": false,
			"verified": false,
			"followers_count": 23,
			"friends_count": 48,
			"statuses_count": 510,
			"profile_image_url": "null",
			"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
		}
	}
}

​

tweet_delete_events

{
    "for_user_id": "930524282358325248",
    "tweet_delete_events": [
{
        "status": {
            "id": "1045405559317569537",
            "user_id": "930524282358325248"
        },
        "timestamp_ms": "1432228155593"
    }
   ]
}

​

Account Activity Replay API

Enterprise

The Account Activity Replay API is a data recovery tool that allows you to retrieve events from as far back as five days. It should be utilized to recover data in scenarios where your webhook server misses events, — whether due to disconnections lasting longer than the retry window, or for those disaster recovery scenarios where you need a few days to restore your system back to normal.

The Account Activity Replay API was developed for any scenario where you fail to ingest activities for a period of time. It delivers activities to the same webhook used for the original real-time delivery of activities. This product is a recovery tool and not a backfill tool, which means events will only be replayed if a previous delivery of them was attempted. The Account Activity Replay API cannot deliver events for a time period prior to a subscription’s creation time.

​

Using Account Activity Replay API

If your account is configured with Replay functionality, you can make requests in a similar manner as requests to the Account Activity API. It is important to note that your request must specify a webhook id parameter to indicate which webhook’s activities you would like to replay. In other words, a Replay request asks Account Activity Replay API to retrieve events from a start date and time to an end date and time based on the webhook id and application id.

Please note that UTC time is expected. These activities are delivered through the registered webhook associated with the id at a rate of up to 2,500 events per second. Also keep in mind that only one Replay job per webhook may be running at a time, although all subscriptions that were active during the date/time specified on that webhook will be replayed.

Events are delivered beginning with the first (oldest) minute of the specified time period, continuing chronologically (as best as possible) until the final minute is delivered. At that point, Replay will deliver a job completion event to the webhook. Because we work chronologically in delivering activities, if there are little or no matching results near the start time, there will likely be a period of time before the first results are delivered.

​

Limitations

Replay is intended as a tool for easily recovering activities as far back as five days ago, but it will not deliver events prior to a subscription’s creation time. For example, if three days ago, you added a new subscription and ran a Replay job with a window for five days prior to today, you would only receive data for the three days that this new subscription was active.

​

Data availability and types

Activities from the Account Activity Replay API are available five days from the initiation of the request, with new data becoming available roughly 10 minutes after a given activity is created. You will be able to make requests specifying a timeframe within this five day window using the from_date and to_date parameters within the request. Events that were originally delivered prior to having access to Replay cannot be replayed. For example, if your account was enabled for access to the Account Activity Replay API on June 1, 2019 at 3:30PM UTC, you would not be able to use Replay to retrieve any events prior to that date and time.

Continue to the Account Activity Replay API reference

​

Migration introduction

We retired the Site Streams, User Streams, and standard beta version of the Account Activity API - DM Only products in 2018. If you had been using those products, please make sure to migrate over to the premium or enterprise version of the Account Activity API.

**We have also retired the legacy Direct Message endpoints. If you had been using those endpoints, please make sure to migrate over to either the new DM endpoints, or to the premium or enterprise version of the Account Activity API. **

Please review this announcment to learn more.

Here are the endpoints that will be affected by these changes:

• User Streams
• Site Streams
• GET direct_messages
• GET direct_messages/sent
• GET direct_messages/show
• POST direct_messages/new
• POST direct_messages/destroy  

We have new endpoints and services available that provide similar access and, for Direct Messages, some additional functionality:

• Account Activity API enterprise and premium
• GET direct_messages/events/list
• GET direct_messages/events/show
• POST direct_messages/events/new
• POST direct_messages/events/destroy

To help you make a smooth migration to these new endpoints and services we have two migration guides:

• Account Activity API migration guide for those going from User Streams and Site Streams to our new webhooks based service
• Direct Message migration guide for those migrating between Direct Message REST endpoints  

Additionally, we have a series of videos about the Account Activity API and how to get started.

And, finally, we have code samples to further your understanding and help you get started quickly:

• The Account Activity Dashboard is a sample Node.js web app with helper scripts to get started with the Account Activity API.
• SnowBot is a sample chatbot using the Account Activity API and REST Direct Message endpoints. It’s written in Ruby, uses the Sinatra web app framework, and is deployed on Heroku.  

If you are building solutions that ingest data and respond in Direct Messages we also have a Building a Customer Engagement Application on X playbook.

​

Migration Guide: Moving from User Streams/Site Streams to Account Activity API

As of August 23rd, 2018, we retired both Site Streams and User Streams. Please make sure to migrate over to the Account Activity API.

Please review this announcement to learn more.

This guide is designed to help you migrate from legacy User Streams and Site Streams APIs to their replacement, the Account Activity API. Below you will find a summary of the changes, new features list, as well as key differences and considerations to help with the transition. For guidance in migrating from basic DM endpoints, please refer to the Direct Message migration guide.

​

Summary of changes

The Account Activity API will deliver you events for authenticated and subscribed accounts via webhooks as opposed to a streaming connection like with User Streams and Site Streams.

​

Deprecated APIs

GET user

GET site  (including control streams: GET site/c/:stream_id,  GET site/c/:stream_id/info.json,  GET site/c/:stream_id/friends/ids.json,  POST site/c/:stream_id/add_user.json,  POST /site/c/:stream_id/remove_user.json)

​

Replacement APIs

Enterprise Account Activity API - All Activities

​

Differences & migration considerations

API format: The new Account Activity API operates differently than User Streams and Site Streams. You will need to alter your web app to receive data with webhooks. You can find more information on webhooks here.

Data Available: Another key difference you will notice is in regards to the data being delivered. X will no longer send events from people that you follow on X (aka your home timeline). This was an intentional change and is not something we plan to alter going forward.

Reliability: Unlike streaming, webhooks enable confirmation of delivery and options to retry POSTed activities that do not make it to the webhook URL.  This gives more assurance that the app is receiving all applicable activities, even if there are brief disconnections or periods of downtime.

​

New features

The Account Activity API offers many new features, most notably that data is now delivered via webhooks as opposed to streaming. Webhooks offer many benefits compared to streaming, but the most prominent are speed and reliability. The API will send you data in the form of JSON events as they become available and you will no longer need to maintain an active connection or poll the endpoint. This limits the need for redundancy features and increases efficiency overall. More information on webhooks can be found in the technical documentation.

​

Managing user subscriptions

The Account Activity API allows multiple subscriptions for a single registered webhook.  This allows multiple user subscriptions activities to be delivered to the same location, similar to the Site Streams architecture, with webhooks.  This means you can track subscriptions, as they pertain to your subscription limits, independently from the webhook connection.  This also allows scalability from only one or a few subscriptions to thousands of subscriptions for a single webhook.

​

How to Migrate

​

Follow the steps below to easily migrate from the Site Streams API to the Account Activity API

Step 1: Decide on a Package

Depending on how you are currently operating with User Streams or Site Streams, you should consider moving to either the enterprise or premium version of the Account Activity API.  Consider the number of applications or authorized users you are currently supporting and scale appropriately to the volume and reliability needed.  When deciding on the package that best suits your needs, some things worth considering are:

• Number of webhooks needed
• Current/projected subscriptions/authorized users managed on your application
• Current number of X client applications
• The level of support you’d prefer from X (forum support or managed enterprise level 1:1 support)
• Price of each package

Step 2: Check the Setup of your X app in the developer portal

The X app currently used for User Streams or Site Streams will be listed for the owning user within the developer portal. This X app can also be used for Account Activity API to retain authorized users for that application.  A new app can also be created, and users can be re-authorized for this new app if desired.  If you are creating a new app on behalf of a business, it is recommended that you create the app with a corporate X @handle account.

• Enable “Read, Write and Access direct messages” on the permissions tab of your X app page.  *Note that changing these settings is not retroactive, any authorized users will keep the authorization settings from the time at which they were authorized. If a user has not already given you read, write and direct message access, you will need to have that user re-authorize your application.
• If you are unfamiliar with X Sign-in and how user contexts work with the X API review Obtaining Access Tokens.
• Generate access tokens for the X app owner at the bottom of the “Keys and 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.
• Generate a bearer token using your Consumer Key and Consumer Secret for application-only API methods.

Step 3: Setup & Configure Your Webhooks

• Create a web app with an endpoint to use as your webhook to receive events (e.g. https://your\_domain.com/webhook/twitter or https://webhooks.your\_domain.com).

• Use your Consumer Key, Consumer Secret, Access Token and Access Token Secret when creating your webhook, Note that your endpoint must return a JSON response with a response_token that is a base64 encoded HMAC SHA-256 hash created from the crc_token and your app Consumer Secret.

• Review Securing Webhooks documentation taking special note of the Challenge Response Check (CRC) requirements.

• Make sure your webhook supports POST requests for incoming events and GET requests for the CRC.

• Make sure your webhook has low latency (<3 seconds to respond to POST requests)

Step 4: Validate Your Webhook Setup

• Webhook APIs will secure your webhooks in two ways:

               - Require challenge response checks to validate that the webhook owner is the web app owner.

               - A signature header in each POST request for your web app to validate the source.

• In order to verify that you are both the owner of the web app and the webhook URL, X will perform a Challenge Response Check (CRC), which is not to be confused with a cyclic redundancy check.
• A GET request with a parameter named crc_token will be sent to your webhook URL. Your endpoint must return a JSON response with a response_token that is a base64 encoded 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.
• In the event that the response is invalid, events will cease to be sent to the registered webhook.

Step 5: Create Subscriptions for Each User Stream or Site Streams Authorized User

Converting to the Account Activity API from User Streams:

• Generate a list of your current user subscriptions on User Streams
• Set up your new Account Activity API subscriptions using the request:  POST account_activity/all/:env_name/subscriptions
• Confirm your Account Activity API subscriptions using the request:  _GET account_activity/all/:env_name/subscriptions/list  _

Converting to the Account Activity API from Site Streams: (using control streams):

• Generate a list of your current subscriptions on Site Streams using the request:  GET /1.1/site/c/:stream_id/info.json
• Set up your new Account Activity API subscriptions using the request:  POST account_activity/all/:env_name/subscriptions
• Confirm your Account Activity API subscriptions using the request:  _GET account_activity/all/:env_name/subscriptions/list  _

Registering a Webhook and Creating Subscriptions (not migrating from Site Streams or User Streams)

• Register your webhook URL with your app using POST webhooks and receive a webhook_id.
• Use the returned webhook_id to add user subscriptions with POST webhooks/:webhook_id/subscriptions/all.

​

The Account Activity dashboard (sample Account Activity API application)

We’ve created a sample app to make testing the Account Activity API a little quicker:   

• Download the Account Activity Dashboard sample application here (it uses Node.js)
• Follow the instructions on the README to install and launch the app
• Once the application has been launched, you can use the UI to easily set up your webhook and create a new subscription

​

Available Activities

​

Deprecated streaming message types 

​

Deprecated event types

​

Direct Message migration guide

On September 17th, 2018 we retired the legacy Direct Message endpoints. If you had been using those endpoints, please make sure to migrate over to the new Direct Message endpoints or the Account Activity API.

Please review this announcment to learn more.

This guide is designed to help you migrate from legacy Direct Message REST APIs to their enhanced replacements which have graduated from beta. Below you will find a summary of the changes, a new features list, and key differences and considerations to help with the transition. The new Direct Message endpoints are available now to all developers. For guidance in migrating from User Streams or Site Streams, see the migration guide to Account Activity API.

• Summary of changes
• New features
• Sending Direct Messages
• Receiving Direct Messages
• Deleting Direct Messages

​

Summary of changes

If you are still using the following DM endpoints, you will have to migrate to the newer endpoints. 

​

New features

The new Direct Message API endpoints support a number of new capabilities and provide improved access to previous Direct Messages. New features include:

• Support for media attachments (image, GIF, and video).
• Ability to prompt users for structured replies with a predefined options list.
• Up to 30 days of access to past Direct Messages.

For a full list of new Direct Message features and additional new API endpoints refer to the technical documentation.  

​

Differences & migration considerations

The new API endpoints behave very differently from their previous counterparts. Simply updating the endpoint URLs will result in errors in your application. Consider the following when updating your application for the migration.

​

New Direct Message object

The first thing you are likely to notice is the new object structure of Direct Messages. This new Message Create object structure has been introduced to support new capabilities like Quick Replies and Attachments. The new object also contains a smaller condensed user object. Your application will need to be updated to account for this new object structure when parsing and potentially in data models or storage. For descriptions of each property see the full documentation on the Message Create Object.

Example message create object

{
      "type": "message_create",
      "id": "1234858592",
      "created_timestamp": "1392078023603",
      "initiated_via": {
        "tweet_id": "123456",
        "welcome_message_id": "456789"
      },
      "message_create": {
        "target": {
          "recipient_id": "1234858592"
        },
        "sender_id": "3805104374",
        "source_app_id": "268278",
        "message_data": {
          "text": "Blue Bird",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "urls": [],
            "user_mentions": [],
          },
          "quick_reply_response": {
            "type": "options",
            "metadata": "external_id_2"
          },
          "attachment": {
            "type": "media",
            "media": {
             ...
            }
          }
        }
      }

​

Summary

• Entirely new Direct Message object structure.
• Condensed user object.
• New information provided (quick reply responses, attachments, etc).

​

Sending Direct Messages

POST direct_messages/events/new is a direct replacement for sending Direct Messages. The most significant difference with this endpoint is that all information is now sent as JSON in the POST request body as opposed to individual POST params.

Example Twurl request

twurl -A 'Content-type: application/json' -X POST /1.1/direct\_messages/events/new.json -d '{"event": {"type": "message\_create", "message\_create": {"target": {"recipient\_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}'

Note in the above request that the content-type is set to application/json as opposed to application/x-www-form-urlencoded. Additionally, if you are constructing the OAuth 1.0a signature, note that the JSON body is not included in the generation of the signature. Most OAuth libraries already account for this. If you are using twurl, ensure you are using at least version 0.9.3.

​

Summary

• Message is defined in JSON POST body
• Content-type header must be set to application/json
• JSON body is not included in the generation of the OAuth signature.  

​

Retrieving Direct Messages

Retrieving past Direct Message is now accomplished with a single API endpoint: GET direct_messages/events/list. The significant difference with this new endpoint is that it now returns both sent and received messages in reverse chronological order. This may make it easier to rebuild a conversation. However, if you are only looking for sent or received messages you will need to post-process the response by referring to the sender_id property.

Pagination is now based on a cursor value rather an ID of a Direct Message. A cursor property is returned with each response. GET direct_messages/events/list will return up to 30 days of past messages, regardless of how many messages exist within the past 30 days. When a cursor is not returned, there are no more messages to be returned. The method for accessing individual Direct Messages with GET direct_messages/events/show remains the same, although the Direct Message object returned has a different structure as described previously.

Finally, real-time access to Direct Messages will now be accomplished via webhook with the Account Activity API. For guidance in migrating from User Streams or Site Streams, see the migration guide to Account Activity API for more information.

​

Summary

• Sent and Received messages are now returned on the same endpoint.
• Up to 30 days of messages returned.
• Cursor based pagination.
• Real-time access to Direct Message via webhook.

​

Deleting Direct Messages

Direct Messages can now be deleted with DELETE direct_messages/events/destroy. The interface is largely the same requiring the ID of the message to delete. The key differences is the endpoint now requires a DELETE request instead of a POST request.

How deleted Direct Messages are reflected in official X clients remains the same. Direct Messages are only removed from the interface of the user context provided. Other members of the conversation can still access the Direct Message.

​

Summary

• Deleting a Direct Message requires the ID.
• New endpoint requires a DELETE request.
• How deleted Direct Messages are reflected in official X clients remains unchanged.

**Questions about migrating to the new Direct Message endpoints? **Post your question to the developer community forum on twittercommunity.com.

​

Frequently Asked Questions

​

General

What are the advantages of using the Account Activity API?

The Account Activity API uses webhooks, meaning that unlike for the streaming APIs we don’t require you to have an open connection for us to send you information. Webhooks are also different from Rest APIs because you don’t have to pull us hundreds of times every 15 minutes to get the data you care about. This increases the efficiency between a user and your app, as it delivers data when it happens.

The Account Activity API has a number of benefits:

1. Speed: we deliver data at the speed of X.
2. Simplicity: we deliver all of an account’s events, through one single webhook connection. The activities delivered in the API include Posts, @mentions, replies, Retweets, Quote Tweets, Retweets of Quote Tweets, favorites, Direct Messages sent, Direct Messages received, follows, blocks, mutes. 
3. Scale: you receive all of the activities for an account that you manage without being restricted by any rate limits of event caps.

The Account Activity API is available as a premium sandbox, premium paid, and enterprise offering, so you can scale as you require more accounts for liability features or additional functionality.

To get started, visit the playbook or download sample code snippets from GitHub.  

How do I identify which product tier is best for me?

Please read through our Account Activity API Overview page to learn more about the differences between the Premium options and the Enterprise option.   

What is the difference between a Premium environment and an Enterprise webhook?

There is no difference. Each Premium environment will have its own webhook_id.  

I need a development, staging and production environment for Account Activity API, is this possible?

Yes! With the paid tiers of Account Activity API (Paid Premium and Enterprise), it’s possible to register multiple webhook URLs and manage subscriptions separately for each through the API methods. Additionally, multiple client apps may be added to an allowlist to maintain authorization for your current authorized users.  

Do you have any step-by-step guides on how to get set up with the Account Activity API?

As a matter of fact, we do!

• If you are just getting started, we recommend that you visit our Getting started with webhooks guide

• Follow along with our X Dev supported scripts: 

  • Account Activity API dashboard, a node web app that displays webhook events.
  • The SnowBot chatbot, a Ruby web app built on the Account Activity and Direct Message APIs. This code base includes a script to help set up Account Activity API webhooks.  

Is there a way to recover data if our system goes down for a period of time?

With the paid tiers of Account Activity API (Paid Premium and Enterprise), our system will retry to send the activities to you several times over a four hour period. If your system does not respond within that four hour period, then the activity will be lost and you will have to use other REST endpoints to recover data within 7 days.

We suggest that you use your different webhooks, or environments, as a redundancy tool like the Account Activity Replay API to ensure that you don’t miss any activities if one of your systems goes down.  

What authentication do I have to use with the Account Activity API?

The authorization methods required for Account Activity API is described per method in the API reference pages. If you are just starting out with X authentication, we recommend that you read through this section.

What is a challenge-response check (CRC)?

The Account Activity API challenge response check is a security feature put in place to ensure that the Account Activity API’s activities are being sent to the proper developer. It also can be used by developers to ensure that the data that they are receiving is coming from X. X will automatically send a CRC to your webhook URL once every 24 hours, starting the last time the webhook URL was validated. Your system must respond with a valid response within 3 seconds to remain validated. 

Please visit our page Securing webhooks for more details.  

Is there anything that would immediately invalidate my webhook URL?

If one of the following occurs, we will immediately mark your webhook as invalid:

• The server responds to a CRC with an incorrect token. In this case, our system will not retry to send you the activity.
• The webhook URL has an incorrect certificate configured. In this case, our system will not retry to send you the activity.
• Your server returning a non-2XX, non-4XXX, non-5XXX response code.
• You specify the use of gzip without actually sending it.
• You do not specify the use of gzip, but actually send it in the response.  

Will I get duplicate activities if subscribed to users that are interacting with each other?

Yes.  If your web app has active subscriptions for User A and User B, and User A mentions User B in a Post, there will be two POST activities sent to the registered webhook.  Each activity will have an indicator of “for_user_id” to show which subscription the activity belongs to.  

**When I make a subscription to my webhook, can I replace the /all/ portion of the following endpoint with other account activity data objects to limit the activities the API delivers? **POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json

No, this is not possible. As it currently stands, we only have the /all/ product available.  

**Is there any way of using the Account Activity API without requesting Direct Messages permissions from users? **

At this point, Direct Messages permissions are required because there is no way to ‘filter out’ the Direct Messages activities for this API.   

Is there a free version of the Account Activity API?

Yes, we offer the sandbox version as a free tier. Our sandbox option is limited to a single webhook with a limit of a maximum of 15 subscriptions. You can read more about the sandbox option in our documentation. 

**Is it possible to use the Account Activity API to get Retweets of Posts that mention subscribed users? **

Unfortunately, this is not part of the activities delivered with this API. For this, we suggest using the Streaming API instead.   

What are the possible activity types that are represented by a tweet_create_event?

A tweet_create_event payload will be sent:

If the subscription user does any of the following actions:

• Creates a Post
• Retweets
• Replies to a Post

If another user:

• @mentions* the subscription user
• Quotes a Tweet created by the subscription user 

*Note: The Account Activity API only delivers events when the subscription user would receive a notification from X and could see the event publicly.  This means, If the mentioned account (@userA) follows the protected account (@userB) then UserA will get a notification UserB mentioned them. If UserA is not following UserB (and approved by UserB) UserA will not get a notification, and therefore a tweet_create_event would not be sent via AAA if @userA had a subscription.

If a blocked user mentions my subscribed user, how can I identify this?

You will see a boolean field `user_has_blocked` on the top level of the json response, set to either “true” or “false”. This field will only be exposed on Post mentions. 

Enterprise

How can I add my app to an allowlist or check if my app is already on the allowlist?

To manage the X apps that you have added to an allowlist for access via the Enterprise APIs, please reach out to your account manager with your app ID. You can find your app ID by navigating to the “Apps” page in the developer portal.  

If I have access to three webhooks, can I use three webhooks for each of the apps that I have registered for enterprise use?

The webhook limit is set on the account level, not the app level. If you have access to three webhooks and two apps registered for enterprise use, you can use two webhooks on one app and the third on the other app, but not three on each app. 

Can I specify which types of events will be redelivered using the Account Activity Replay API?

The types of events to replay cannot be specified. All events delivered during the date and time window specified will be replayed. 

Will there be any retries if my application fails to ingest an Account Activity Replay API event?

No, there will not be any retries. If an application fails to ingest an event sent by the Account Activity Replay API, another Replay job can be submitted for the same time period to attempt redelivery of any missed Replay events. 

What should I do when I receive a partial success completion event?

We suggest making note of the timestamps for the events that were received and requesting another Replay job for the events that were missed. 

How many Account Activity Replay API jobs can I have running at a time?

Only one Account Activity Replay API job per webhook may be running at a time. 

How can I differentiate Account Activity Replay API events from real-time production events as they are delivered to my webhook?

Since the Account Activity Replay API will always deliver events from the past, events can be differentiated from real-time production events based on the event’s timestamp. 

How soon can I start using the Account Activity Replay API to redeliver an activity my application dropped or missed?

An activity becomes available for redelivery about 10 minutes after it was created. 

​

Error troubleshooting guide

​

Code 32

This error generally means that something is either malformed in the request, headers, authorization, or url that you are specifying. This is not an Account Activity API error, it’s an authorization error and X isn’t getting the proper Oauth setup or url.

• Enterprise - Make sure the consumer keys and access tokens you are using belong to a X app that has been registered for use of Enterprise products. If you don’t have your consumer keys and access tokens, or need to add your X app to the allowlist, please reach out to your account manager. 

• If authenticating with user context, make sure you have properly authorized your request with the proper oauth nonce, oauth_signature, and oauth_timestamp.

• Make sure that your access tokens have the proper permission level.

  • When on the ‘Keys and tokens’ tab in the app dashboard, please make sure that your access tokens have the ‘Read, write, and direct messages’ permission level. 
  • If the tokens’ permission level is set to anything less than this, please navigate to the ‘Permissions’ tab, adjust the access permission to ‘Read, write, and direct messages’, then regenerate your access tokens and secret from the ‘Keys and tokens’ tab.

• Make sure that your URL is formed properly.

  • Please keep in mind that :env_name is case sensitive.  

​

Code 200 - Forbidden

• Premium - Make sure that you have an approved developer account before you try to make a request to the API. You also must use the proper :env_name in the request, which you can setup on the dev environments page.

• Enterprise - Make sure that your account manager has set you up with access to the Account Activity API.

• Make sure you have set up your URI properly. This error can trigger if you have entered the incorrect URI in your request.  

​

Code 214 - Webhook URL does not meet the requirements.

• Please make sure that you are using https.
• Your webhook URL could be malformed.
• Learn more about how to set up your webhook URL under the Develop webhook consumer app section on Getting started with webhooks page.  

​

Code 214 - High latency on CRC GET request. Your webhook should respond in less than 3 seconds.

• This means that your server is slow. Make sure that you are responding to the CRC within 3 seconds.  

​

Code 214 - Non-200 response code during CRC GET request (i.e. 404, 500, etc).

• Your server is down. Make sure that your server is running properly.  

​

Code 214 - Too many resources already created.

• Enterprise - You have already used all of your webhooks. Use the GET webhooks endpoint with each of your registered apps to identify where your webhooks are distributed. 

​

Code 261 - Application cannot perform write actions.

• The app that you are using with the API does not have the proper permission level set for its access token and access token secret. Please navigate to the ‘Keys and tokens’ tab on the X apps dashboard and check the permission levels assigned to your access token and access token secret. If it is set to anything other than ‘Read, write and Direct Messages,’ then you are going to have to adjust the settings under the ‘Permission’ tab and regenerate your access token and access token secret to apply the new settings.
• Alternatively, you are trying to register a webhook using app-only authentication, which is not supported. Please authenticate with user context instead as noted in the API reference sections for registering a webhook for Enterprise Account Activity API.

​

Account Activity API Reference Index

​

Enterprise Account Activity API

​

POST account_activity/webhooks

Registers a new webhook URL for the given application context. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester.

The number of allowed webhooks is determined by billing package.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks.json

​

Resource Information

​

Parameters

​

Example Request

$ curl —request POST —url ‘https://api.x.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhooks%2Ftwitter%2F0’ —header ‘authorization: OAuth oauth_consumer_key=“CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“ACCESS_TOKEN”, oauth_version=“1.0“‘

​

HTTP Responses

​

Example Response - Success

_HTTP 200_

    {
      "id": "1234567890",
      "url": "https://your_domain.com/webhook/twitter/0",
      "valid": true,
      "created_at": "2016-06-02T23:54:02Z"
    }

​

Error Messages

HTTP 403

    {
      "errors": [
        {
          "code": 214,
          "message": "Too many resources already created."
        }
      ]
    }

​

GET account_activity/webhooks

Returns all URLs and their statuses for the given application.

We mark a URL as invalid if it fails the daily validation check. In order to re-enable the URL, call the update endpoint.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks.json

​

Resource Information

​

Example Request

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/webhooks.json
     --header 'authorization: Bearer TOKEN'

​

Example Response

HTTP 200 OK

    [
      {
        "id": "1234567890",
        "url": "https://your_domain.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-02T23:54:02Z"
      }
      {
        "id": "2468013579",
        "url": "https://your_domain2.com/webhook/twitter/0",
        "valid": true,
        "created_at": "2016-06-04T22:31:29Z"
      }
    ]

​

Error Messages

​

PUT account_activity/webhooks/:webhook_id

Triggers the challenge response check (CRC) for the given webhook’s URL. If the check is successful, returns 204 and reenables the webhook by setting its status to valid.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

​

Resource Information

​

Parameters

​

Example Request

    $ curl --request PUT
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​

Response

HTTP 204 OK

    { }

​

Error Messages

​

POST account_activity/webhooks/:webhook_id/subscriptions/all

Subscribes the provided application to all events for the provided user context for all message types. After activation, all events for the requesting user will be sent to the application’s webhook via POST request.

Subscriptions are currently limited based on your account configuration. If you have a need to add more subscriptions, please contact your account manager.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​

Resource Information

​

Parameters

​

Example Request

    $ curl --request POST
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'

​

Example Response - Success

HTTP 204 NO CONTENT

    {}

​

Error Messages

​

GET account_activity/subscriptions/count

Returns the count of subscriptions that are currently active on your account. Note that the /count endpoint requires application-only OAuth, so that you should make requests using a bearer token instead of user context.

​

Resource URL

https://api.x.com/1.1/account_activity/subscriptions/count.json

​

Resource Information

​

HTTP Response Codes

​

Example Request

    $ curl --request GET
     --url https://api.x.com/1.1/account_activity/subscriptions/count.json
     --header 'authorization: Bearer TOKEN'

​

Example Response - Success

HTTP 200

    {
      "account_name":"my-account",
      "subscriptions_count_all":"1",
      "subscriptions_count_direct_messages":"0",
      "provisioned_count":"50"
    }

​

Error Messages

HTTP 401

    {
      "errors": [
        {
           "code": 32,
          "message": "Could not authenticate you."
        }
      ]
    }

​

GET account_activity/webhooks/:webhook_id/subscriptions/all

Provides a way to determine if a webhook configuration is subscribed to the provided user’s events. If the provided user context has an active subscription with provided application, returns 204 OK. If the response code is not 204, then the user does not have an active subscription. See HTTP Response code and error messages below for details.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​

Resource Information

​

Parameters

​

Example Request

$ curl —request GET —url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json —header ‘authorization: OAuth oauth_consumer_key=“WHITELISTED_CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“SUBSCRIBING_USER’S_ACCESS_TOKEN”, oauth_version=“1.0“‘

​

Example Response - Success

HTTP 204 NO CONTENT

    { }

​

GET account_activity/webhooks/:webhook_id/subscriptions/all/list

Returns a list of the current All Activity type subscriptions for the specified webhook. Note that the /list endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json

​

Resource Information

​

Parameters

​

HTTP Response Codes

​

Example Request

$ curl —request GET —url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list.json —header ‘authorization: Bearer TOKEN’

​

Example Response - Success

HTTP 200

    {
      "webhook_id": "1234567890",
      "webhook_url": "https://your_domain.com/webhook/twitter/0",
      "application_id": "11231812",
      "subscriptions": [{
        "user_id": "20212306"
      }]
    }

​

Error Messages

HTTP 401

    {
      "errors": [
        {
           "code": 32,
          "message": "Could not authenticate you."
        }
      ]
    }

​

DELETE account_activity/webhooks/:webhook_id

Removes the webhook from the provided application’s configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/webhooks.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json

​

Resource Information

​

Parameters

​

Example Request

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
     --header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​

Response

HTTP 204 OK

    { }

​

DELETE account_activity/webhooks/:webhook_id/subscriptions/all (DEPRECATED)

Deactivates subscription(s) for the provided user context and application. After deactivation, all events for the requesting user will no longer be sent to the webhook URL.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json

​

Resource Information

​

Parameters

​

Example Request

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
     --header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"'

Example Request

    { }

​

DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

Deactivates subscription for the specified webhook and user id. After deactivation, all events for the requesting user will no longer be sent to the webhook URL. Note, that this endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context.

​

Resource URL

https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json

​

Resource Information

​

Example Request

    $ curl --request DELETE
     --url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
     --header 'authorization: Bearer TOKEN'

​

Response

HTTP 204 NO CONTENT

​

Error Messages

​

Replay API

POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json ¶

Submits a request to retrieve activities from up to the past five days from all subscriptions present during the date and time windows specified in the request. If your webhook has active user subscriptions, you will concurrently receive those events as well. Note: We do perform a CRC before delivering replay events.

​

Responses

The following responses may be returned by the API. Most error codes are returned with a string including additional details in the body. For non-200 responses, you should resolve the error and try again.

​

”Job completed successfully” message

Once your job successfully completes, Account Activity Replay API will deliver the following job completion event. Once you receive this event, the job has finished running and another can be submitted.

{
  "replay\_job\_status": {
    "webhook_id": "1234577122340233217",
    "job_state": "Complete",
    "job\_state\_description": "Job completed successfully"
    "job_id": "1095098195724558337"
  }
}

​

”Job failed to complete” message

In the event your job does not complete successfully, we will return the following message encouraging you to retry your Replay job. Once you receive this event, the job has finished running and another can be submitted.

{
  "replay\_job\_status": {
    "webhook_id": "123451374207332352",
    "job_state": "Incomplete",
    "job\_state\_description": "Job failed to deliver all events, please retry your replay job",
    "job_id": "1093226942650736640"
  }
}

​

Example curl request

    curl --request POST  --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm'
    --header 'authorization: Bearer TOKEN'

​

Example response

HTTP 202

{
  "job_id": "1234567890",
  "created_at": "2016-06-02T23:54:02Z"
}