Jason | 5th December 2012
First off, there are a number of targets you should be aware of when filtering for @mentions of Twitter usernames:
twitter.user.id - The ID of the Twitter user that sent this Tweet
twitter.user.screen_name - The @username of the Twitter user that sent this Tweet
twitter.mentions - An array of Twitter @usernames that are mentioned in this Tweet
twitter.mention_ids - An array of Twitter user IDs that are mentioned in this Tweet
twitter.in_reply_to_screen_name - The @username of the Twitter user this Tweet is replying to. Note: This @username will also appear in the twitter.mentions and twitter.mention_ids arrays
twitter.retweet.user.id - The ID of the Twitter user that sent this retweet
twitter.retweet.user.screen_name - The @username of the Twitter user that sent this retweet
twitter.retweet.mentions - An array of Twitter @usernames that are mentioned in this retweet
Both Tweets and retweets
interaction.author.id - The author's ID on the service from which they generated a post. For example, their Twitter user ID
Secondly, there are two important syntax rules you should be familiar with when writing your CSDL. These rules are useful to know both when filtering for @mentions, and filtering for other keywords:
Use of [email protected] symbols when filtering for Twitter @usernames
You should not use the [email protected] symbol when filtering for usernames. Twitter usernames are passed on to us from Twitter as the bare username, without the appended [email protected] symbol. Further details of how our CSDL filtering engine works with regard to @Mentions, URLs and punctuation can be found on the documentation page - The CSDL Engine : How it Works.
Use of the IN and CONTAINS_ANY operators
contains_any - Matches if one of your comma separated keywords or phrases are contained as words or phrases in the target field. For example, twitter.user.location contains_any “New, Old” will match locations such as “New York”, but not “Oldfield”.
in - Matches if your comma separated keywords or phrases are an exact match of the full content of the target field. For example, twitter.user.location in “New York” would match the location “New York”, but not “New York, NY”.
How to filter for users sending Tweets
The best targets to use if you want to filter on a list of users who are sending Tweets are twitter.user.id or twitter.user.screen_name. If you are only interested in people sending retweets, you would want to use the twitter.retweet.user.id or twitter.retweet.user.screen_name targets. If you would like to receive both Tweets and retweets, you will be better off using interaction.author.id in conjunction with ‘interaction.type == “twitter”’.
How to filter for Twitter users @mentioned in Tweets
You should use the twitter.mentions or twitter.mention_ids targets. People often try to filter incorrectly for Tweets containing mentions of @usernames using the following CSDL:
twitter.text contains_any "@DataSift, @DataSiftDev, @DataSiftAPI"
The DataSift filtering engine filters keywords by first stripping out any @mentions or links from the main body of text, and filtering them separately using the twitter.mentions targets and links augmentation respectively, so you should never be able to find a @mention by filtering on twitter.text or interaction.content.
Below is an example of a correct way to filter for @mentions of Twitter usernames within Tweets:
twitter.mentions in "DataSift, DataSiftDev, DataSiftAPI"
You could also use twitter.mention_ids to filter on the Twitter user ID, rather than the @username:
twitter.mention_ids in [155505157, 165781228, 425158828]