Create an alert

POST /accounts/{account_id}/alerts

Creates a new alert for the given account.

Parameters

  • account_id (string) - ID of the account

Page content


Minimal curl example

curl -ig 'https://api.mention.net/api/accounts/{account_id}/alerts' \
    -X POST \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Accept-Version: 1.19' \
    -d '{
        "name":"ALERT_NAME",
        "query": {
            "type": "basic",
            "included_keywords":["ALERT_NAME"]
        },
        "languages":["en"],
        "sources":["web"]
    }'

Available properties

Properties _ Definition Example
name required Alert name "NASA and competitors"
query required Query definition {"type": "basic", "included_keywords": ["NASA"]}
languages required Array of languages ["en", "fr", "ru"]
countries optional Array of countries ["US", "RU", "XX"]
sources optional Array of sources ["web", "twitter"]
blocked_sites optional Array of blocked site ["http://www.spaceoflovemagazine.com/"]
noise_detection optional Enables noise detection true
reviews_pages optional Array of reviews pages ["http://www.yelp.com/biz/space-center-houston-houston-4"]

Name

name

Human readable identifier of your alert, this is the way you name it in order to remember what it is tracking.

Query

query

Query is a json object that can be of two different types: basic, or advanced. The type of a query is defined by its type attributes.

Basic query

Properties _ Definition Example
type *required Query type "basic"
included_keywords *required Array of included keywords ["NASA", "Arianespace", "SpaceX", "Pockocmoc"]
required_keywords optional Array of required keywords ["mars"]
excluded_keywords optional Array of excluded keywords ["nose", "fil d'ariane"]
monitored_website optional Monitored website as an object ["domain":"www.nasa.gov", "block_self":true]
Keywords
  • included_keywords
  • required_keywords
  • excluded_keywords

Keywords can contains alphanumeric characters, white spaces, and the following characters: ._@#'&. Additionally, the - character is allowed when preceded by an alphanumeric character.

One of included_keywords or required_keywords MUST have at least 1 keyword in it.

Each keyword is matched exactly.

Keywords form a boolean constraint such that:

  • At least one of included_keywords must be present in the mention
  • And all of required_keywords must be present in the mention
  • And none of excluded_keywords must be present in the mention

Monitored website

The domain acts like an included_keyword.
If block_self is set to true, it acts like a blocked_url.

Properties _ Definition Example
domain required Http domain or full url "www.nasa.gov"
block_self required Should this source be ignored true

Note that if a full url is provided to domain like "http://domain.com/page", input will be stripped and only domain.com will be kept.

Advanced query

Properties _ Definition Example
type *required Query type "advanced"
query_string *required Query string "(NASA AND Discovery) OR (Arianespace AND Ariane)"
Query String

query_string

A query string is composed of one or more clauses separated by AND or OR keywords. A clause can be a term (a string without white spaces in it), a quoted term (a string of characters enclosed with "), or a nested query string enclosed in parentheses.

A single clause can not contain both AND and OR at the same time: add parentheses accordingly.

this is not a querystring of the url! This is a query 'string', so an attribute of the query object, which is itself an attribute of the method.

{
    ...
    "name": "Space innovation",
    "query": {
        "type": "advanced",
        "query_string": "(space AND innovation)"
    },
    ...
}
Term

A term must contain only letters and numbers (including accented letters, and letters from any script). As an exception, a term can start with @ or # character.

Examples:

NASA
Voilà
@NASA
Wildcards

If a term contains the * or ? characters, it's a wildcard term. In a wildcard term, * matches one or more term character, and ? matches exactly one term character.

Query Match Not Match
astro* astronomy, astrophysics astral, astro
201? 2010, 2011 201, 2020, 20201

Note: not all accounts have access to wildcard terms.

Quoted term

A quoted term can contain any character. The only exception is that " or \ must be preceded by \.

Examples:

"Space Station"
"Jason-3"

Quoted terms match if all the keyword are present, in order, and next to each other.

Proximity

You can allow some distance between words by using the proximity operator ~ followed by the maximum distance allowed between each them.

The distance is the difference of the second word's position, relative to the first word, in the query and in the mention. For example, in the query "Create Alert"~1, the second word is at position 1 relative to the first one; in the mention This will create an alert, the word alert is at position 2 relatively to create. So the distance is 2-1: 1. Note that this allows words to be in opposite order if the proximity constraint is 2 or more.

The proximity can not be lower than 1, or upper than 6.

Examples:

Query Match Not Match
"Mars Rover"~1 "Mars Rover", "Mars Exploration Rover Missiong" "Rover on Mars"
"Mars Rover"~3 "Rover on Mars"

Punctuation in quoted terms

If you expect your quoted terms to appear with and without punctuation, specify both forms in your query for best results.

Example: "Mars" AND "Rover" AND ("sand-dune selfie" OR "sand dune selfie").

Near

It is possible to specify the maximum distance between two terms or quoted terms by using the NEAR operator:

Query Match Not Match
"the ISS" NEAR/3 "its orbit" "The ISS raised its orbit today"
("the ISS" OR "international space station") NEAR/3 "its orbit" "The international space station raised its orbit today"

The proximity can not be lower than 1, or upper than 6.

Negation

A clause can be negated by prefixing it with the - character, or the NOT operator:

"Space Station" AND -"MIR"
"Planet" AND NOT ("Pluton" OR "Moon")

Note that there must be not whitespace after a -. Other than that, - and NOT are strictly equivalent.

Selectors

It is possible to specify that a part of the query must match only in some parts of the mention, by prefixing it with a selector. A selector is a name followed by the : character.

Examples: url:NASA, source_country:"US", source_country:(us OR ca).

Possible selectors:

Fields Effect Example
url Match for mentions that have the given string in the mention's own URL url:nasa.gov
source_country Match for mentions whose source has been located in the specified country. The country should be specified as a two-letters country code. Valid country codes can be found in the countries attribute in the app endpoint. Country codes are case-insensitive. source_country:US source_country:(us OR ca)
lang Match for mentions by language lang:(en OR fr)
influence Match for mentions by author influence score (from 40 to 100) influence:50
title Match for mentions that have the given string in the mention's own title attribute title:nasa
body Match for mentions that have the given string in the mention's content body:nasa
source_name Match for mentions by the real name of author source_name:National Aeronautics and Space Administration
source_username Match for mentions by the nickname of the author source_username:NASA
has Match when the specified field is defined and not empty. Currently only possible with source_country source_country:US OR -has:source_country
source Match mentions of the given source source:(twitter OR facebook)
twitter_followers Match mentions whose Twitter author has at least the given number of followers (twitter_followers:1000 OR -source:twitter)
Punctuation

Punctuation in quoted terms is taken into account when matching mentions.

Examples:

Query Match Not Match
"Yahoo!" Yahoo!, yahoo ! Yahoo.
"M&M's" M&M's M&Ms, MMs, M&M’s
"M&M's" OR "M&M’s" OR "M&Ms" M&M's, M&M’s, M&Ms, M & M's MMs
"youtube.tv" youtube.tv youtube tv
"Coca-Cola" coca-cola coca cola
"Coca Cola" coca cola coca-cola
"Coca Cola"~1 coca cola, coca-cola, coca/cola
Restrictions
  • A query string can not exceed 1700 characters (measured in unicode code points)
  • An OR clause can not contain a negative clause. Example: "Space Station" OR -"MIR" is not valid.
  • An OR clause can not contain a clause who consits only of one stop word. You can still match a stop word by associating it with other words in a AND clause, or in a quoted term. Examples: The OR Space Station is invalid. "The Space Station" or "The" AND "Space Station" are valid. Current list of stop words: a, an, and, at, but, by, com, from, http, https, if, in, is, it, its, me, my, or, rt, the, this, to, too, via, we, www, you.
  • A query string can not consist only of negative clauses
  • A term can not be longer than 128 characters (measured in unicode code points)

Languages

languages

An array of language codes. All languages that you can select as origin of the alert can be listed via the app/data request, where there is an alert language section. Currently, you are limited to 5 languages.

On alerts with query.type="advanced", the languages attribute applies only to monitored pages and reviews pages.

Countries

countries

An array of countries from which mentions should be tracked. By default, no country is "filtered out". All countries that you can select as origin of the alert can be listed via the app/data request, where there is an alert countries section. Currently, you are limited to 5 countries if you want to filter some countries out.

Note: This attribute is ignored when using advanced queries.

Sources

sources

An array of sources from which mentions should be tracked. All sources that you can select can be listed via the app/data request output, where there is an alert sources section.

In case you are using monitored_facebook_page and/or monitored_twitter_account, you have to add facebook and/or twitter to sources.

Blocked sites

blocked_sites

An array of blocked sites from which you don't want mentions to be tracked.

A mention is blocked if its URL is matched by any of the blocked URLs.

A blocked URL matches a mention’s URL if the blocked URL equals the mention’s URL, or if the mention’s URL starts with the blocked URL and is followed by one of [/.?&#].

http:// in blocked URLs also match https:// and vice-versa.

The following characters are ignored, when they appear at the end of blocked URLs: /.?&#.

Noise detection

noise_detection

We have a noise detector that strive to detect mentions that might meet your criteria, but not what you are looking for. It will watch your behaviour when you put mentions in spam and trash, and will try to skip similar mentions. It is a helper to avoid you to reach quota because of spam; but it may skip mentions you would have liked to seem from time to time.

Reviews Pages

reviews_pages

For 3 reviews website, tripadvisor, yelp, and booking, we allow you to list urls of reviews page that we will monitor.

Color

color

This defines a color to be set to the alert in dashboards, reports, etc... Available colors can be found in the colors attribute in the app endpoint.

Connection Type

connection_type

connection_type is the way this alert is related (or not) to one other. Possible values are:

  • main: This is the first alert of the user created at onboarding
  • related: This is a competitor alert created at the same time than the main alert
  • independent: This is an alert created after and not related to main nor related

Connection Id

connection_id

connection_id is defined only for related alerts and represent the id of the main alert it is related to.


Request example

  • Headers
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept-Version: 1.19
  • Body
{
    "name": "NASA and competitors",
    "query": {
        "type": "basic",
        "included_keywords": ["NASA", "Arianespace", "SpaceX", "Pockocmoc"],
        "required_keywords": ["mars"],
        "excluded_keywords": ["nose", "fil d'ariane"]
    },
    "languages": ["en", "fr", "ru"],
    "countries": [],
    "sources": ["web", "twitter"],
    "blocked_sites": ["www.spaceoflovemagazine.com/"],
    "noise_detection": true,
    "sentiment_analysis": true,
    "reviews_pages": ["http://www.yelp.com/biz/space-center-houston-houston-4"],
    "shares": []
}

Response example

If the request was successful, the response will return the full alert data, like if you did a GET request on that Alert.

  • Body
{
    "alert": {
        "id": "112233",
        "name": "NASA and competitors",
        "query": {
            "type": "basic",
            "included_keywords": ["NASA", "Arianespace", "SpaceX", "Pockocmoc"],
            "required_keywords": ["mars"],
            "excluded_keywords": ["nose", "fil d'ariane"],
            "monitored_website": [
                "domain": "www.nasa.gov",
                "block_self": true
            ]
        },
        "languages": ["en", "fr", "ru"],
        "countries": [],
        "sources": ["twitter", "news", "web", "blogs", "videos", "forums", "images"],
        "blocked_sites": ["www.spaceoflovemagazine.com/"],
        "role": "admin",
        "stats": {
            "mention_sources": {
                "total": "0"
            },
            "mention_folders": {
                "inbox": {
                    "total": "0"
                },
                "archive": {
                    "total": "0"
                },
                "spam": {
                    "total": "0"
                },
                "trash": {
                    "total": "0"
                }
            },
            "unread_mentions": {
                "total": "0"
            },
            "unseen_mentions": {
                "total": "0"
            },
            "favorite_mentions": {
                "total": "0"
            },
            "important_mentions": {
                "total": "0"
            },
            "tasks": {
                "total": "0"
            },
            "todo_tasks": {
                "total": "0"
            },
            "done_tasks": {
                "total": "0"
            },
            "logs": {
                "total": "0"
            }
        },
        "shares": [{
            "id": "THE_ACCOUNT_ID",
            "account": {
                "id": "THE_ACCOUNT_ID",
                "name": "Doe",
                "email": "john.doe@nasa.com",
                "language_code": "en",
                "created_at": "2014-09-30T10:03:54.0+00:00",
                "updated_at": "2016-01-14T14:55:57.0+00:00",
                "avatar_url": "https:\/\/d39qsljf883l.cloudfront.net\/f6415b89ef2ljkca5c0c7d464f1b82-088f3dsqlj12lj4.jpg",
                "timezone": "Europe\/Berlin",
                "grouped_email_notification": true,
                "default_email_notification_frequency": "daily",
                "default_desktop_notification_frequency": "hourly",
                "default_push_notification_frequency": "hourly"
            },
            "role": "admin",
            "permissions": {
                "edit": true,
                "delete": true
            },
            "created_at": "2016-01-14T15:31:42.0+00:00",
            "weight": 88674800
        }],
        "noise_detection": true,
        "created_at": "2016-01-14T15:31:42.0+00:00",
        "updated_at": "2016-01-14T15:31:44.0+00:00",
        "quota_used": 0,
        "index_version": 2,
        "permissions": {
            "edit": true,
            "share": true,
            "list_tasks": true,
            "list_logs": true
        },
        "description": "Monitor NASA press release.",
        "color": "#05e363",
        "connection_type": "related",
        "connection_id": "12121212"
    }
}

Stats

Contains statistics about the alert:

  • mention number by source
  • mention number by folder
  • tasks
  • ...

Shares

Array listing who has access to the alert. When you create an alert, your account is the only item in shares; however, once the alert gets shared, all accounts it is shared with are listed in this array.

Index version

Indicates the 'search' version of the Alert. 'Search' version is a version of the search feature. For a given alert, a specific 'search' version will indicate if a specific attribute is available in the search for that Alert. In order to know which attributes are available for search for the version of your alert, check this.

Connection

connection_type is the way this alert is related (or not) to one other. Possible values are:

  • main: This is the first alert of the user created at onboarding
  • related: This is a competitor alert created at the same time than the main alert
  • independent: This is an alert created after and not related to main nor related

connection_id is defined only for related alerts and represent the id of the main alert it is related to.