Intent

The MessageBird Intent API enables predicting intents from a given phrase using a machine learning model that was trained on one of your datasets. Datasets can be created and managed using the dataset section of the MessageBird Dashboard.

Intent recognition is a way to group the phrases from incoming messages. For example, "hi" and "hello" are both ways to express a greeting. The corresponding intent would be greeting. You might also want to define a book-room intent that might be phrased as: "Can I book a room for tomorrow?" or `"do you have any vacancies?"``. The MessageBird Intent API applies machine learning to generalize from the phrases that you added to your intents so that unseen phrases are automatically mapped to the right intent. You can use this to route your messages based on their topic, or build an intelligent IVR menu that can deal with natural language, or integrate this into your chatbot system. The possibilities are endless!

You can configure the intents you want to recognize through the datasets section of the dashboard. You can easily improve your intent recognition accuracy by using the Train UI that can be accessed from the dataset overview.

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:

intent.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}.

ListDatasets

Lists datasets containing intents and corresponding phrases. You can choose to list only your own datasets, as well as template datasets, or both. Template datasets are used as examples and can be found under the Templates tab in the dataset overview of the dashboard. You can clone such datasets to kickstart the creation of a dataset that is tailored to your use-case.

Note that the results are paginated and so you might need to iteratively call this endpoint to obtain all your datasets.

GET /api/v1/datasets

Query Parameters

curl -X GET "https://intent.messagebird.com/api/v1/datasets" \
    -H "Authorization: AccessKey your_access_key"

Response (ListDatasetsResponse)

A response containing the Intent datasets that were queried.

{
  "datasets": [
    {
      "created_at": "2021-08-24T12:04:32Z",
      "dataset_id": "dde4eeae-7652-4bc8-8be1-1cd6ac898dc7",
      "description": "This dataset is clearly some awesome dataset.",
      "intents": [
        "order",
        "reservation"
      ],
      "is_template": false,
      "last_trained_at": "2021-08-24T12:04:32Z",
      "name": "My awesome dataset",
      "updated_at": "2021-08-24T12:04:32Z"
    }
  ],
  "limit": 20,
  "nextCursor": "VGhpcyBpcyBub3QgYSByZWFsIGN1cnNvciwgYnV0IHRoZXkgd291bGQgYmUgYmFzZTY0IGVuY29kZWQgdG9vCg=="
}

Response codes

GetDataset

Retrieves the dataset for the given dataset ID. It only displays the metadata corresponding to the dataset. If you want to view the individual intent phrases that you have added, you can use the dataset section of the dashboard.

GET /api/v1/datasets/{datasetId}

URL Parameters

curl -X GET "https://intent.messagebird.com/api/v1/datasets/{datasetId}" \
    -H "Authorization: AccessKey your_access_key"

Response (Dataset)

A collection of phrases with the corresponding intents. There can be multiple matching phrases per intent. To inspect the phrases that were added, go to the datasets section in the dashboard.

{
  "createdAt": "2021-08-24T12:04:32Z",
  "datasetId": "dde4eeae-7652-4bc8-8be1-1cd6ac898dc7",
  "description": "This dataset is clearly some awesome dataset.",
  "intents": [
    "order",
    "reservation"
  ],
  "isTemplate": false,
  "lastTrainedAt": "2021-08-24T12:04:32Z",
  "name": "My awesome dataset",
  "updatedAt": "2021-08-24T12:04:32Z"
}

Response codes

PredictIntent

Predicts an intent for a phrase given a dataset ID. The Intent API uses machine learning to generalize from the intents and phrases in the dataset that was created in the datasets overview to infer the intent of the given phrase. Requires the active model for the dataset to be trained.

Training a model usually takes around 1 after a dataset is created or updated. This endpoint yields an error if the model has not been trained yet.

POST /api/v1/datasets/{datasetId}/predict

URL Parameters

Request (PredictIntentRequest)

A request for predicting an intent from a phrase and a dataset ID.

curl -X POST "https://intent.messagebird.com/api/v1/datasets/{datasetId}/predict" \
    -H "Authorization: AccessKey your_access_key" \
    -H "Content-Type: application/json" \
    -d '{
  "phrase": "I'd like to order something"
}'

Response (PredictIntentResponse)

A response for predicting an intent from a phrase and a dataset ID.

{
  "intent": "order",
  "intentPredicted": true
}

Response codes

ListSupportedLanguages

Lists the languages supported by the Intent API.

GET /api/v1/supported-languages

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

Response (LanguageList)

List of recognized languages.

{
  "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

Dataset object

A collection of phrases with the corresponding intents. There can be multiple matching phrases per intent. To inspect the phrases that were added, go to the datasets section in the dashboard.

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.

LanguageList object

List of recognized languages.

ListDatasetMode enum

Mode for listing datasets.

ListDatasetsResponse object

A response containing the Intent datasets that were queried.

PredictIntentResponse object

A response for predicting an intent from a phrase and a dataset ID.