API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIContacts API (v2)Integrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

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.

Notification icon

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

ParameterTypeDescriptionRequiredDefault
listModestring from ListDatasetModeList 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.FalseALL
limitintegerThe limit defining the maximal number of datasets to return.False20
cursorstringThe cursor to view the next paginated collection of datasets as provided by the next_cursor value in the ListDatasetsResponse.Falsenull
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.

ParameterTypeDescription
datasetsarray of DatasetThe (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.
limitintegerThe 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.
nextCursorstringThe 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=="
}
Response codes
CodeDescription
200A successful response.
401Returned when the user is not authorized.
404Returned when the resource does not exist.

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

ParameterTypeDescriptionRequiredDefault
datasetIdstringUnique 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"

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.

ParameterTypeDescription
datasetIdstringThe unique ID for the dataset.
intentsarray of stringThe collection of intents that were added to this dataset.
isTemplatebooleanDescribes 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.
namestringThe name of the dataset. You can configure the name once creating a dataset in the dashboard.
createdAtstringThe timestamp of dataset creation. Uses the ISO-8601 standard.
updatedAtstringThe timestamp of last update. Uses the ISO-8601 standard.
descriptionstringThe optional description of the dataset.
lastTrainedAtstringThe 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"
}
Response codes
CodeDescription
200A successful response.
401Returned when the user is not authorized.
404Returned when the resource does not exist.

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

ParameterTypeDescriptionRequiredDefault
datasetIdstringThe unique ID that identifies the dataset for which a prediction should be made.True-

Request (PredictIntentRequest)

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

ParameterTypeDescription
phrasestringThe 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"
}'

Response (PredictIntentResponse)

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

ParameterTypeDescription
intentstringThe intent that is predicted for the given phrase.
intentPredictedbooleanBoolean indicating an intent was predicted. If false the phrase could not be matched with an intent.
{
"intent": "order",
"intentPredicted": true
}
Response codes
CodeDescription
200A successful response.
401Returned when the user is not authorized.
404Returned when the resource does not exist.

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.

ParameterTypeDescription
languagesarray of LanguageThe 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"
}
]
}
Response codes
CodeDescription
200A successful response.
401Returned when the user is not authorized.
404Returned when the resource does not exist.

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.

ParameterTypeDescription
datasetIdstringThe unique ID for the dataset.
intentsarray of stringThe collection of intents that were added to this dataset.
isTemplatebooleanDescribes 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.
namestringThe name of the dataset. You can configure the name once creating a dataset in the dashboard.
createdAtstringThe timestamp of dataset creation. Uses the ISO-8601 standard.
updatedAtstringThe timestamp of last update. Uses the ISO-8601 standard.
descriptionstringThe optional description of the dataset.
lastTrainedAtstringThe 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 object

Language that was detected from the given phrase.

ParameterTypeDescription
iso6393CodestringThe ISO-639-3 code of the language.
namestringThe English name of the language.
languageCodestring from LanguageCodeThe enum value of the ISO639-3 language code.

LanguageCode enum

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

ValueDescription
LANGUAGE_INVALIDLanguage code is invalid.
LANGUAGE_UNDETERMINEDLanguage could not be determined.
ENGEnglish.
RUSRussian.
DEUGerman.
FRAFrench.
ITAItalian.
JPNJapanese.
SPASpanish.
CEBCebuano.
TURTurkish.
PORPortuguese.
UKRUkrainian.
EPOEsperanto.
POLPolish.
SWESwedish.
NLDDutch.
HEBHebrew.
ZHOChinese.
HUNHungarian.
ARAArabic.
CATCatalan.
FINFinnish.
CESCzech.
FASPersian.
SRPSerbian.
ELLGreek.
VIEVietnamese.
BULBulgarian.
KORKorean.
NORNorwegian.
MKDMacedonian.
RONRomanian.
INDIndonesian.
THAThai.
HYEArmenian.
DANDanish.
TAMTamil.
HINHindi.
HRVCroatian.
HBSSerbo-Croatian.
BELBelarusian.
KATGeorgian.
TELTelugu.
KAZKazakh.
WARWaray.
LITLithuanian.
GLGGalician.
SLKSlovak.
BENBengali.
EUSBasque.
SLVSlovenian.
KANKannada.
MALMalayalam.
MARMarathi.
ESTEstonian.
AZEAzerbaijani.
MSAMalay.
SQIAlbanian.
LATLatin.
BOSBosnian.
NNONorwegian Nynorsk.
URDUrdu.
LAVLatvian.
MYABurmese.
TATTatar.
AFRAfrikaans.
OCIOccitan.
NDSLow German.
KIRKirghiz.
ASTAsturian.
TGLTagalog.
ISLIcelandic.
INAInterlingua.
SINSinhala.
GUJGujarati.
KHMCentral Khmer.
BREBreton.
BAKBashkir.
UZBUzbek.
BODTibetan.
PANPanjabi.
VOLVolapük.
ALSTosk Albanian.
NEPNepali.
CYMWelsh.
JBOLojban.
FRYWestern Frisian.
MONMongolian.
LTZLuxembourgish.
CHEChechen.
UIGUighur.
TGKTajik.
SCOScots.
SANSanskrit.
CHVChuvash.
JAVJavanese.
MINMinangkabau.
IDOIdo.
ORIOriya.
ASMAssamese.
NEWNewari.
GLEIrish.
MLGMalagasy.
ARGAragonese.
CKBCentral Kurdish.
SWASwahili.
BARBavarian.
LMOLombard.
YIDYiddish.
ARZEgyptian Arabic.
MHREastern Mari.
AZBSouth Azerbaijani.
SAHYakut.
PNBWestern Panjabi.
SUNSundanese.
BPYBishnupriya.
PMSPiemontese.
ILOIloko.
WUUWu Chinese.
KURKurdish.
PUSPushto.
ILEInterlingue.
XMFMingrelian.
YUEYue Chinese.
GOMGoan Konkani.
LIMLimburgan.
MWLMirandese.
CORCornish.
SNDSindhi.
HSBUpper Sorbian.
SCNSicilian.
GLAScottish Gaelic.
PAMPampanga.
BHOBhojpuri.
MAIMaithili.
VECVenetian.
MLTMaltese.
DIVDhivehi.
WLNWalloon.
MZNMazanderani.
AMHAmharic.
QUEQuechua.
CBKChavacano.
TUKTurkmen.
ROHRomansh.
OSSOssetian.
VLSVlaams.
YORYoruba.
LAOLao.
LEZLezghian.
SOMSomali.
MYVErzya.
DIQDimli.
MRJWestern Mari.
DSBLower Sorbian.
FRRNorthern Frisian.
HATHaitian.
GRNGuarani.
BXRRussia Buriat.
KOMKomi.
SRDSardinian.
KRCKarachay-Balkar.
BCLCentral Bikol.
NAPNeapolitan.
GLVManx.
AVAAvaric.
RUERusyn.
XALKalmyk.
PFLPfaelzisch.
DTYDotyali.
HIFFiji Hindi.
COSCorsican.
LRCNorthern Luri.
VEPVeps.
TYVTuvinian.
NOBNorwegian Bokmål.
SNAShona.
KINKinyarwanda.
IBOIgbo.
SMOSamoan.
SOTSouthern Sotho.
MRIMaori.
WOLWolof.
XHOXhosa.
HAUHausa.
HAWHawaiian.
NYANyanja.
ZULZulu.
HMNHmong.

LanguageList object

List of recognized languages.

ParameterTypeDescription
languagesarray of LanguageThe collection of languages.

ListDatasetMode enum

Mode for listing datasets.

ValueDescription
ALLList all datasets.
ONLY_TEMPLATEList 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_USERList the user datasets.

ListDatasetsResponse object

A response containing the Intent datasets that were queried.

ParameterTypeDescription
datasetsarray of DatasetThe (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.
limitintegerThe 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.
nextCursorstringThe cursor that can be used to obtain the next paginated collection of datasets.

PredictIntentResponse object

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

ParameterTypeDescription
intentstringThe intent that is predicted for the given phrase.
intentPredictedbooleanBoolean indicating an intent was predicted. If false the phrase could not be matched with an intent.
Next upFaq

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings