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.
All paths referenced in this page uses the following base URL:
intent.messagebird.com
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}.
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
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
listMode | string from ListDatasetMode | List mode indicating to query template datasets, only user datasets or both. - ALL: List all datasets. - ONLY_TEMPLATE: List the template datasets. 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. - ONLY_USER: List the user datasets. | False | ALL |
limit | integer | The limit defining the maximal number of datasets to return. | False | 20 |
cursor | string | The cursor to view the next paginated collection of datasets as provided by the next_cursor value in the ListDatasetsResponse. | False | null |
curl -X GET "https://intent.messagebird.com/api/v1/datasets" \-H "Authorization: AccessKey your_access_key"
A response containing the Intent datasets that were queried.
Parameter | Type | Description |
---|---|---|
datasets | array of Dataset | The (paginated) collection of datasets. This can contain both your own datasets as well as template datasets. 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. |
limit | integer | The effective limit of the maximum number of datasets that could be returned by the list endpoint. If the limit defined in ListDatasetsRequest was not set, this value indicates the used limit. |
nextCursor | string | The cursor that can be used to obtain the next paginated collection of datasets. |
{"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=="}
Code | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authorized. |
404 | Returned when the resource does not exist. |
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}
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
datasetId | string | Unique ID for the dataset. You can obtain the IDs either from the dataset section in the dashboard or by listing the datasets with the Intent API. | True | - |
curl -X GET "https://intent.messagebird.com/api/v1/datasets/{datasetId}" \-H "Authorization: AccessKey your_access_key"
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.
Parameter | Type | Description |
---|---|---|
datasetId | string | The unique ID for the dataset. |
intents | array of string | The collection of intents that were added to this dataset. |
isTemplate | boolean | Describes if this dataset is a template dataset or not. 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. |
name | string | The name of the dataset. You can configure the name once creating a dataset in the dashboard. |
createdAt | string | The timestamp of dataset creation. Uses the ISO-8601 standard. |
updatedAt | string | The timestamp of last update. Uses the ISO-8601 standard. |
description | string | The optional description of the dataset. |
lastTrainedAt | string | The timestamp of last model that completed training. Uses the ISO-8601 standard. If there is not a model trained already, this field will not be populated. |
{"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"}
Code | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authorized. |
404 | Returned when the resource does not exist. |
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
Parameter | Type | Description | Required | Default |
---|---|---|---|---|
datasetId | string | The unique ID that identifies the dataset for which a prediction should be made. | True | - |
A request for predicting an intent from a phrase and a dataset ID.
Parameter | Type | Description |
---|---|---|
phrase | string | The phrase that might contain an intent. |
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"}'
A response for predicting an intent from a phrase and a dataset ID.
Parameter | Type | Description |
---|---|---|
intent | string | The intent that is predicted for the given phrase. |
intentPredicted | boolean | Boolean indicating an intent was predicted. If false the phrase could not be matched with an intent. |
{"intent": "order","intentPredicted": true}
Code | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authorized. |
404 | Returned when the resource does not exist. |
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"
List of recognized languages.
Parameter | Type | Description |
---|---|---|
languages | array of Language | The collection of 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"}]}
Code | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authorized. |
404 | Returned when the resource does not exist. |
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.
Parameter | Type | Description |
---|---|---|
datasetId | string | The unique ID for the dataset. |
intents | array of string | The collection of intents that were added to this dataset. |
isTemplate | boolean | Describes if this dataset is a template dataset or not. 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. |
name | string | The name of the dataset. You can configure the name once creating a dataset in the dashboard. |
createdAt | string | The timestamp of dataset creation. Uses the ISO-8601 standard. |
updatedAt | string | The timestamp of last update. Uses the ISO-8601 standard. |
description | string | The optional description of the dataset. |
lastTrainedAt | string | The timestamp of last model that completed training. Uses the ISO-8601 standard. If there is not a model trained already, this field will not be populated. |
Language that was detected from the given phrase.
Parameter | Type | Description |
---|---|---|
iso6393Code | string | The ISO-639-3 code of the language. |
name | string | The English name of the language. |
languageCode | string from LanguageCode | The enum value of the ISO639-3 language code. |
Language code in ISO639-3 format. More info can be found here: https://iso639-3.sil.org/code_tables/639/data.
Value | Description |
---|---|
LANGUAGE_INVALID | Language code is invalid. |
LANGUAGE_UNDETERMINED | Language could not be determined. |
ENG | English. |
RUS | Russian. |
DEU | German. |
FRA | French. |
ITA | Italian. |
JPN | Japanese. |
SPA | Spanish. |
CEB | Cebuano. |
TUR | Turkish. |
POR | Portuguese. |
UKR | Ukrainian. |
EPO | Esperanto. |
POL | Polish. |
SWE | Swedish. |
NLD | Dutch. |
HEB | Hebrew. |
ZHO | Chinese. |
HUN | Hungarian. |
ARA | Arabic. |
CAT | Catalan. |
FIN | Finnish. |
CES | Czech. |
FAS | Persian. |
SRP | Serbian. |
ELL | Greek. |
VIE | Vietnamese. |
BUL | Bulgarian. |
KOR | Korean. |
NOR | Norwegian. |
MKD | Macedonian. |
RON | Romanian. |
IND | Indonesian. |
THA | Thai. |
HYE | Armenian. |
DAN | Danish. |
TAM | Tamil. |
HIN | Hindi. |
HRV | Croatian. |
HBS | Serbo-Croatian. |
BEL | Belarusian. |
KAT | Georgian. |
TEL | Telugu. |
KAZ | Kazakh. |
WAR | Waray. |
LIT | Lithuanian. |
GLG | Galician. |
SLK | Slovak. |
BEN | Bengali. |
EUS | Basque. |
SLV | Slovenian. |
KAN | Kannada. |
MAL | Malayalam. |
MAR | Marathi. |
EST | Estonian. |
AZE | Azerbaijani. |
MSA | Malay. |
SQI | Albanian. |
LAT | Latin. |
BOS | Bosnian. |
NNO | Norwegian Nynorsk. |
URD | Urdu. |
LAV | Latvian. |
MYA | Burmese. |
TAT | Tatar. |
AFR | Afrikaans. |
OCI | Occitan. |
NDS | Low German. |
KIR | Kirghiz. |
AST | Asturian. |
TGL | Tagalog. |
ISL | Icelandic. |
INA | Interlingua. |
SIN | Sinhala. |
GUJ | Gujarati. |
KHM | Central Khmer. |
BRE | Breton. |
BAK | Bashkir. |
UZB | Uzbek. |
BOD | Tibetan. |
PAN | Panjabi. |
VOL | Volapük. |
ALS | Tosk Albanian. |
NEP | Nepali. |
CYM | Welsh. |
JBO | Lojban. |
FRY | Western Frisian. |
MON | Mongolian. |
LTZ | Luxembourgish. |
CHE | Chechen. |
UIG | Uighur. |
TGK | Tajik. |
SCO | Scots. |
SAN | Sanskrit. |
CHV | Chuvash. |
JAV | Javanese. |
MIN | Minangkabau. |
IDO | Ido. |
ORI | Oriya. |
ASM | Assamese. |
NEW | Newari. |
GLE | Irish. |
MLG | Malagasy. |
ARG | Aragonese. |
CKB | Central Kurdish. |
SWA | Swahili. |
BAR | Bavarian. |
LMO | Lombard. |
YID | Yiddish. |
ARZ | Egyptian Arabic. |
MHR | Eastern Mari. |
AZB | South Azerbaijani. |
SAH | Yakut. |
PNB | Western Panjabi. |
SUN | Sundanese. |
BPY | Bishnupriya. |
PMS | Piemontese. |
ILO | Iloko. |
WUU | Wu Chinese. |
KUR | Kurdish. |
PUS | Pushto. |
ILE | Interlingue. |
XMF | Mingrelian. |
YUE | Yue Chinese. |
GOM | Goan Konkani. |
LIM | Limburgan. |
MWL | Mirandese. |
COR | Cornish. |
SND | Sindhi. |
HSB | Upper Sorbian. |
SCN | Sicilian. |
GLA | Scottish Gaelic. |
PAM | Pampanga. |
BHO | Bhojpuri. |
MAI | Maithili. |
VEC | Venetian. |
MLT | Maltese. |
DIV | Dhivehi. |
WLN | Walloon. |
MZN | Mazanderani. |
AMH | Amharic. |
QUE | Quechua. |
CBK | Chavacano. |
TUK | Turkmen. |
ROH | Romansh. |
OSS | Ossetian. |
VLS | Vlaams. |
YOR | Yoruba. |
LAO | Lao. |
LEZ | Lezghian. |
SOM | Somali. |
MYV | Erzya. |
DIQ | Dimli. |
MRJ | Western Mari. |
DSB | Lower Sorbian. |
FRR | Northern Frisian. |
HAT | Haitian. |
GRN | Guarani. |
BXR | Russia Buriat. |
KOM | Komi. |
SRD | Sardinian. |
KRC | Karachay-Balkar. |
BCL | Central Bikol. |
NAP | Neapolitan. |
GLV | Manx. |
AVA | Avaric. |
RUE | Rusyn. |
XAL | Kalmyk. |
PFL | Pfaelzisch. |
DTY | Dotyali. |
HIF | Fiji Hindi. |
COS | Corsican. |
LRC | Northern Luri. |
VEP | Veps. |
TYV | Tuvinian. |
NOB | Norwegian Bokmål. |
SNA | Shona. |
KIN | Kinyarwanda. |
IBO | Igbo. |
SMO | Samoan. |
SOT | Southern Sotho. |
MRI | Maori. |
WOL | Wolof. |
XHO | Xhosa. |
HAU | Hausa. |
HAW | Hawaiian. |
NYA | Nyanja. |
ZUL | Zulu. |
HMN | Hmong. |
List of recognized languages.
Parameter | Type | Description |
---|---|---|
languages | array of Language | The collection of languages. |
Mode for listing datasets.
Value | Description |
---|---|
ALL | List all datasets. |
ONLY_TEMPLATE | List the template datasets. 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. |
ONLY_USER | List the user datasets. |
A response containing the Intent datasets that were queried.
Parameter | Type | Description |
---|---|---|
datasets | array of Dataset | The (paginated) collection of datasets. This can contain both your own datasets as well as template datasets. 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. |
limit | integer | The effective limit of the maximum number of datasets that could be returned by the list endpoint. If the limit defined in ListDatasetsRequest was not set, this value indicates the used limit. |
nextCursor | string | The cursor that can be used to obtain the next paginated collection of datasets. |
A response for predicting an intent from a phrase and a dataset ID.
Parameter | Type | Description |
---|---|---|
intent | string | The intent that is predicted for the given phrase. |
intentPredicted | boolean | Boolean indicating an intent was predicted. If false the phrase could not be matched with an intent. |