Named Entity Recognition

The MessageBird Named Entity Recognition API extracts and parses a fixed set of entities from incoming phrases. A phrase is usually the text from an incoming message of your customer. This can happen in the context of receiving a Conversations API message or when receiving an SMS message, just to name a few.

An entity contains structured information, such as person names, time, durations, locations etc. The process of finding and parsing entities from phrases is known as named entity recognition.

Going from an unstructured phrase to structured data can be helpful for building intelligent conversational systems, such as chatbots. Chatbots often need to repeat information that was already said, for example to confirm whether they have extracted the right information. In other cases you might want your chat bot to call an internal or external API with a structured object. These things become straightforward using the MessageBird Named Entity Recognition API.

API access to AI services is currently available in Customer Preview with limited access. Please contact your account manager to request access. If you have any questions about how to use the API and get more guidance on your implementation, send an email to our AI team.

Base URL

All paths referenced in this page uses the following base URL:

ner.messagebird.com

Authorization

You need to set an access key to authenticate your HTTP requests. You can create, manage, and retrieve your access keys using the MessageBird Dashboard.

To provide the access key, set the Authorization HTTP header in the form of AccessKey {accessKey}.

PredictEntities

Extracts named entities from a phrase. If no entities can be found, it returns an empty collection of entities. Each entity contains one or more (ambiguous) interpretations. Each recognized entity will most likely contain only one possible interpretation.

You can limit the named entities to search for by explicitly providing the entity types. If no types are specified upfront, all entity types will be extracted and returned if possible.

If no language is specified upfront, the Named Entity Recognition API will try to infer it automatically before proceeding with named entity recognition. An inferred or pre-specified language that is not supported will yield an error.

POST /api/v1/predict-entities

Request (PredictEntitiesRequest)

A request for predicting the entities from a given phrase. This process is also referred to as named entity recognition. It is possible to pre-specify the language when calling this endpoint. Otherwise, the Named Entity Recognition API will attempt to infer the language and proceed with extraction of the entities.

If no entities could be found, it will return an empty collection.

curl -X POST "https://ner.messagebird.com/api/v1/predict-entities" \
    -H "Authorization: AccessKey your_access_key" \
    -H "Content-Type: application/json" \
    -d '{
  "language": "ENG",
  "phrase": "Today we're in Amsterdam, building two chatbots using https://messagebird.com/en/solutions/faq-bots",
  "timezone": "Europe/Amsterdam"
}'

Response (PredictEntitiesResponse)

Response payload that is returned when predicting entities. Contains an empty list when no entities could be found.

{
  "entities": [
    {
      "ambiguous": false,
      "end_char_index": 5,
      "entity_values": [
        {
          "time": {
            "value": "2021-09-21T19:00:00.000+00:00"
          }
        }
      ],
      "start_char_index": 0,
      "text": "Today",
      "type": "TIME"
    },
    {
      "ambiguous": false,
      "end_char_index": 24,
      "entity_values": [
        {}
      ],
      "start_char_index": 15,
      "text": "Amsterdam",
      "type": "GEOPOLITICAL"
    },
    {
      "ambiguous": false,
      "end_char_index": 38,
      "entity_values": [
        {
          "numeral": {
            "value": "5"
          }
        }
      ],
      "start_char_index": 35,
      "text": "two",
      "type": "NUMERAL"
    },
    {
      "ambiguous": false,
      "end_char_index": 99,
      "entity_values": [
        {
          "url": {
            "domain": "messagebird.com",
            "value": "https://messagebird.com/en/solutions/faq-bots"
          }
        }
      ],
      "start_char_index": 54,
      "text": "https://messagebird.com/en/solutions/faq-bots",
      "type": "URL"
    }
  ]
}

Response codes

ListSupportedLanguages

Lists the supported entity types per language.

GET /api/v1/supported-languages

curl -X GET "https://ner.messagebird.com/api/v1/supported-languages" \
    -H "Authorization: AccessKey your_access_key"

Response (ListSupportedLanguagesResponses)

A response with a collection of languages and the entity types supported by those languages.

{
  "entitiesPerLanguage": [
    {
      "entity_types": [
        "GEOPOLITICAL",
        "URL",
        "TIME",
        "NUMERAL"
      ],
      "language": {
        "iso_639_3_code": "nld",
        "language_code": "NLD",
        "name": "Dutch"
      }
    },
    {
      "entity_types": [
        "GEOPOLITICAL",
        "URL",
        "TIME",
        "NUMERAL"
      ],
      "language": {
        "iso_639_3_code": "eng",
        "language_code": "ENG",
        "name": "English"
      }
    },
    {
      "entity_types": [
        "GEOPOLITICAL",
        "URL",
        "TIME",
        "NUMERAL"
      ],
      "language": {
        "iso_639_3_code": "spa",
        "language_code": "SPA",
        "name": "Spanish"
      }
    },
    {
      "entity_types": [
        "GEOPOLITICAL",
        "URL",
        "TIME",
        "NUMERAL"
      ],
      "language": {
        "iso_639_3_code": "zho",
        "language_code": "ZHO",
        "name": "Chinese"
      }
    }
  ],
  "languages": [
    {
      "iso_639_3_code": "nld",
      "language_code": "NLD",
      "name": "Dutch"
    },
    {
      "iso_639_3_code": "eng",
      "language_code": "ENG",
      "name": "English"
    },
    {
      "iso_639_3_code": "spa",
      "language_code": "SPA",
      "name": "Spanish"
    },
    {
      "iso_639_3_code": "zho",
      "language_code": "ZHO",
      "name": "Chinese"
    }
  ]
}

Response codes

Objects Reference

AmountOfMoneyValue object

An amount of money expressed in whole units, cents and a currency.

CurrencyCodeIso4217 enum

The ISO 4217 currency code.

CurrencyCodeIso4217Value object

A wrapper for the currency code enum.

DefaultValues object

A normalized value of an entity, e.g. for time the ISO8601 date format.

DurationValues object

A duration and the unit of the duration. Durations are normalized to whole seconds.

Entity object

A (named) entity. Entities are sub-phrases with structured information, such as person name, locations, time, quantities etc. The process of extracting these entities from natural language is called Named Entity Recognition (NER).

EntityType enum

Type of entity.

EntityValuesWrapper object

A wrapper for entity values with varying type and structure.

IntervalValues object

A start time and an end time of an interval.

Language object

Language that was detected from the given phrase.

LanguageCode enum

Language code in ISO639-3 format. More info can be found here: https://iso639-3.sil.org/code_tables/639/data.

ListSupportedLanguagesResponses object

A response with a collection of languages and the entity types supported by those languages.

PredictEntitiesRequest object

A request for predicting the entities from a given phrase. This process is also referred to as named entity recognition. It is possible to pre-specify the language when calling this endpoint. Otherwise, the Named Entity Recognition API will attempt to infer the language and proceed with extraction of the entities.

If no entities could be found, it will return an empty collection.

PredictEntitiesResponse object

Response payload that is returned when predicting entities. Contains an empty list when no entities could be found.

ProductQuantityValue object

A quantity of a product using a certain unit. Example use-cases are parsing of cooking recipes and shopping.

SupportedEntitiesForLanguage object

A language and the entity types supported by that language.

UnitValues object

An amount and a unit of the amount.

UrlValues object

A URL and its domain.