Account Activity Migration guide & set up

Transcription

1 Account Activity Migration guide & set up

2 Agenda What is the Account Activity (AAAPI)? User Streams & Site Streams overview What s different & what s changing? How to migrate to AAAPI? Questions? 2

3 Account Activity Overview

4 Migration timeline April 6, 2017 May 16, 2018 August 16, 2018 Site Streams & User Streams Replacement Announced Premium AAAPI Released to the Community Site Streams & User Streams Deprecated 4

5 Account Activity API (AAAPI) The Account Activity API delivers all activities (Tweets, direct messages, favorites, retweets, etc.) related to an authenticated Twitter account (subscription) via webhooks in real-time. 5

6 What data do you get? For each of your subscribed users, the AAAPI sends all of the following activities to a single specified webhook URL via a POST request: Tweets (by (of user) Replies (to or from user) Retweets (by user, of user) Quote Tweets (by user, of user) Retweets of Quoted Tweets (by user, of user) Likes (by user, of user) Follows (of user, by user) Blocks (by user) Mutes (by user) Direct Messages Sent (by user) Direct Messages Received (to user) Typing Indicators (to user) Read Receipts (to user) Subscription Revoke (by user) 6

7 How do you get it? 1. Establish & secure a webhook URL 2. Pass the CRC 3. Add a subscription per authenticated user 4. Accept POST requests per activity 7

8 Retry logic The retry logic for the the Account Activity API functions as follows: The first retry occurs at 3 seconds, the second at 30 seconds, and the third (and final) at the 5 minutes After the third and final retry... The activity can t be re-sent to you so you ll need to leverage other Twitter APIs to collect the missing data Our 30-Day Search API could be leveraged to retrieve Tweets, Retweets, Quote Tweets, Mentions, and Replies The direct_messages/events/list endpoint can be used to retrieve all of the DMs sent and received over the last 30 days (if you re only looking for sent or received DMs, you ll need to post process the Tweets based on the sender_id property) 8

9 User & Site Streams vs Account Activity

10 How does AAAPI differ from Site Streams & User Streams? The Account Activity API. is the replacement for Site Streams in a new easy-to-manage API was designed to help you manage and monitor a user s account activity will be supported and managed by Twitter going forward is widely available as opposed to only being available in closed beta has reliability features built into it to ensure you don t miss data includes a new set of features that allow you to better manage your DM experiences (there are net new activities including read receipts and typing indicators) delivers real-time access to all activities (Tweets, direct messages, events, etc) related to an authenticated Twitter account (subscription) via webhooks. leverages webhooks to send you events as they re created in lieu of a streaming API 10

11 What s the difference? User Streams Site Streams Account Activity Data Streaming User Data for a Specific User Streaming User Data for a Specific Set of Users User and Activity Data for Subscribed Accounts Delivery HTTP Streaming API HTTP Streaming API Webhooks API Availability Available Publically (Deprecation on 8/16/18) Available in Limited Beta (Deprecation on 8/16/18) Available in Premium & Enterprise Tiers 11

12 What data do I get now? User and Site Streams Data Tweets Home Timeline of the followed user Tweets Created by the followed of the followed user Replies From the followed user To the followed user Likes For the followed user s Tweets From the followed user (on another s Tweet) Follows New followers of the followed user New accounts followed by followed user User unfollows an account List Activity List created by user List deleted by user List updated by user User Profile Profile updated by user Account Activity API Tweets Tweets Created by the subscribed to of the subscribed user Quote Tweet of the subscribed to user Quote Tweets by the subscribed to user Retweets of the subscribed to user Retweets by the subscribed to user Replies From the followed user To the followed user Likes For the subscribed to user s Tweets From the subscribed to user (on another s Tweet) Follows New followers of the subscribed to user New accounts followed by subscribed to user Blocks & Mutes Subscribed to user blocks an account Subscribed to user unblocks an account Subscribed to user mutes an account Subscribed to user unmutes an account Direct Messages Direct messages sent by the subscribed to user Direct messages received by the subscribed to user Typing indicator for DMs DM read receipts for DMs sent by the subscribed to user 12

13 AAAPI available activity types Message Type tweet_create_events favorite_events follow_events block_events mute_events user_event direct_message_events direct_message_indicate_typing_events Details Tweet status payload when any of the following actions are taken by or to the subscription user: Tweets, Retweets, Quote Tweets Favorite (like) event status with the user and target. Follow event with the user and target. Block event with the user and target. Mute event with the user and target. User removes application authorization and subscription is automatically deleted. Direct message status with the user and target. Direct message typing event with the user and target. direct_message_mark_read_events Direct message read event with the user and target. 13

14 Choosing a Package

15 Which tier is best for me? What you should consider when making your decision: How many users or sets of users are you following? How many separate applications do you have? How many webhooks, or environments, would you like to use? 15

16 Account Activity API (AAAPI) Enterprise Package Offerings: 3+ webhooks (ex: 1x dev webhook, 1x prod webhook, webhooks for different features in your app, etc.) Multiple Client Apps (ex: 1x app for production, 1x for testing) 500+ Subscriptions Tiered Subscription Pricing Retries Included Managed support 16

17 Migrating to Account Activity

18 Migrating to AAAPI Step 1: Decide on a AAAPI Package Step 2: Create an App on Apps.Twitter.com Step 3: Setup AAAPI & Configure Your Webhooks Step 4: Create Subscriptions For Site Streams Users Step 5: Validate Your Webhook Setup 18

19 Step 1: Decide on a AAAPI package When deciding on the package that best suits your needs, some items worth considering are: Number of webhooks needed Current/projected subscriptions/authorized users managed on your application Current number of Twitter client applications The level of support you'd prefer from Twitter (forum support or managed enterprise level 1:1 support) Price of each package 19

20 Step 2: Creating a Twitter app Create an app at apps.twitter.com. If you are creating the app on behalf of your company, it is recommended you create the app with a corporate Twitter account. Enable Read, Write and Access direct messages on the permissions tab of your app page (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) Generate access tokens for the app owner at the bottom of the Keys and Access Tokens tab. On this same tab take note of your Consumer Key, Consumer Secret, Access Token and Access Token secret. You will need these to use the API. If you are unfamiliar with Twitter Sign-in and how user contexts work with the Twitter API review Obtaining Access Tokens. 20

21 Step 3: Configuring your webhooks Review Securing Webhooks documentation taking special note of the Challenge Response Check (CRC) requirements. Create a web app with an endpoint to use as your webhook to receive events (e.g. or Make sure your webhook supports POST requests for incoming events and GET requests for the CRC. Register your webhook URL with your app using POST account_activity/webhooks and receive a webhook_id. Use the returned webhook_id to add user subscriptions with POST account_activity/webhooks/:webhook_id/subscriptions. 21

22 Securing a webhook Webhook APIs will secure your webhooks in two ways: Require challenge response checks to validate that the webhook owner is the Twitter app owner. A signature header in each POST request for your app to validate source. In order to verify that you are both the owner of the app and the webhook URL, Twitter 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. 22

23 Challenge Response Check (CRC) The CRC request will occur: When a webhook URL is registered. Hourly (once per hour) to validate your webhook URL. When you manually trigger the CRC check Response requirements: Valid response_token and JSON format. Latency less than 3 seconds. 200 HTTP response code. 23

24 Step 4: Create subscriptions for Site Streams & Users Streams 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 (and not migrating from Site Streams or User Streams) Register your webhook URL with your app using POST account_activity/webhooks and receive a webhook_id. Use the returned webhook_id to add user subscriptions with POST account_activity/webhooks/:webhook_id/subscriptions. 24

25 Step 5: Validate setup To validate your app and webhook are configured correctly, favorite a Tweet that s from one of your app is subscribed to. You should receive a Favorite Event via a POST request to your webhook for each DM received. 25

26 Troubleshooting Code 32 Enterprise - Make sure the app tokens that you are using belong to an app that has been whitelisted for use of Enterprise products. Make sure you are using the proper authentication method. If user context, include the consumer key and secret of the whitelisted app and the access tokens of the user you are trying to make a request on behalf of. If app only, make sure you are either using the bearer token or a consumer key and secret of the app that is whitelisted for use of the product. Code Webhook URL does not meet the requirements. Please make sure that you are using https and your URL is formatted correctly Code 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 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 Too many resources already created. You have already used all of your webhooks. 26

27 Troubleshooting How can I whitelist my app or check if my app is already whitelisted? To manage the apps that you have whitelisted 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 app in question in apps.twitter.com and making note of the numerical value within the app s URL. If I have access to three webhooks, can I use three webhooks for each of the apps that I have whitelisted 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 whitelisted for enterprise use, you can use two webhooks on one app and the third on the other app, but not three on each app. 27

28 Thank you