Frequently Asked Questions
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:
- Speed: we deliver data at the speed of Twitter.
- Simplicity: we deliver all of an account's events, through one single webhook connection. The activities delivered in the API include Tweets, @mentions, replies, Retweets, Quote Tweets, Retweets of Quote Tweets, favorites, Direct Messages sent, Direct Messages received, follows, blocks, mutes.
- 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.
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 Twitter Dev supported scripts:
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 (only available to enterprise customers) 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 Twitter 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 Twitter. Twitter 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 Tweet, 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?
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 Tweets 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 Tweet
- Replies to a Tweet
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 Twitter 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 Tweet mentions.
I already have access to the developer portal, how do I sign up for the Premium Account Activity API?
Once you've logged into your developer portal and navigated to the "Dev environments" page, you can 'Create a dev environment' and add your environment name and Twitter app to start using the Premium Account Activity API.
How long will it take to have my Twitter developer account approved?
We continue to work through the applications as quickly as we can. Hang tight - we are just as excited to see what you are going build!
How much does the Premium Account Activity API cost?
You can learn more about the different pricing and access levels on our Premium Account Activity API pricing page.
How many apps can I use with the Premium Account Activity API?
You can use one Twitter app per dev environment (aka webhook) when using the Premium Account Activity API. That means that you can only have one app with the Sandbox tier, and two apps if you are using the Paid Premium tier.
Can I transfer my Premium Account Activity API access to a different app?
While you can change the Twitter app that is utilizing your Premium Account Activity API webhook(s), you have to delete the environment and create a new one to make a transfer.
:env_name come from?
You can find your
:env_name, or environment name, within the "Dev environments" page.
I need more than 250 user subscriptions! What do I do?
Please apply for our Enterprise access by applying here.
How do I downgrade from Paid Premium?
Adjusting your premium tier can be done in the developer dashboard under ‘Manage Subscriptions’. Note that you must downgrade your subscription before the monthly renewal date. See our Billing FAQ for more.
I have a question that hasn’t been answered in the documentation.
Please check our forums to see if your question was answered there. If you still can’t find your answer, please submit a post to the forum.
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 Twitter isn’t getting the proper Oauth setup or url.
- Make sure you have an approved developer account, have established a dev environment for the Account Activity API. You must use the proper environment name and app tokens in your request.
- If you are trying to register a webhook, the POST :env_name/webhooks endpoint requires for you to replace
:env_namewith your environment name in the request. Also, this endpoint requires that you authenticate with user context, aka Oauth1.0a, meaning that you need to use the consumer keys and access tokens generated by the Twitter app that you selected as your designated dev environment.
- If authenticating with user context, make sure you have properly authorized your request with the proper
- 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_nameis case sensitive.
- Please keep in mind that
Code 200 - Forbidden
- 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.
- 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 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 Twitter 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 and Premium Account Activity API.
How to handle error Code 348 - Client application is not permitted to access this user's webhook subscriptions.
- This means that you don't have the right permission level for receiving all the activity types from Account Activity API. You likely need to update your App permissions and re-generate access token & access token secret for that specific user. It's very likely that at the time that the user authenticated your Twitter App your permissions were set to 'Read' only or 'Read, write' rather than the permission level of ‘Read, write, and Direct Messages’ which is required for Account Activity API subscriptions because it sends direct messages.