API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIIntegrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

FAQ

The MessageBird FAQ API enables answering questions from an FAQ dataset created. Datasets can be created and managed using the dataset section of the MessageBird Dashboard.

FAQ datasets are created by giving multiple variations of questions that correspond to an answer. There can be multiple answers, each with multiple corresponding questions. The MessageBird FAQ API applies machine learning to generalize from the questions and answers that you added to your datasets so that unseen questions are automatically mapped to the right answer.

You can view and edit the questions and answers in the datasets section of the dashboard. An effective way to iterate and improve the FAQ recognition accuracy is to leverage 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:

faq.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 answers and corresponding questions. You can choose to list only your own datasets, as well as template datasets, or both. You might need to iterate over multiple pages to obtain all of your datasets.

GET /api/v1/datasets

Query Parameters

ParameterTypeDescriptionRequiredDefault
listModestring from ListDatasetsModeThe list mode indicating to query public datasets, only user datasets or both. - LIST_MODE_UNDEFINED: The list dataset mode type undefined. - 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.FalseLIST_MODE_UNDEFINED
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://faq.messagebird.com/api/v1/datasets" \
-H "Authorization: AccessKey your_access_key"

Response (ListDatasetsResponse)

A response containing the FAQ 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 query the next paginated collection of results.
{
"datasets": [
{
"created_at": "2021-08-24T12:04:32Z",
"dataset_id": "dde4eeae-7652-4bc8-8be1-1cd6ac898dc7",
"description": "This dataset has a list of frequently asked questions about MessageBird",
"is_template": false,
"last_trained_at": "2021-08-24T12:04:32Z",
"name": "MessageBird FAQ",
"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.

GET /api/v1/datasets/{datasetId}

URL Parameters

ParameterTypeDescriptionRequiredDefault
datasetIdstringThe unique ID for the dataset.True-
curl -X GET "https://faq.messagebird.com/api/v1/datasets/{datasetId}" \
-H "Authorization: AccessKey your_access_key"

Response (Dataset)

A collection of answers with matching questions. There can be multiple matching questions per answer.

ParameterTypeDescription
datasetIdstringThe unique ID for the dataset.
namestringThe name of the dataset.
createdAtstringThe timestamp of dataset creation. Uses the ISO-8601 standard.
updatedAtstringThe timestamp of last update. Uses the ISO-8601 standard.
isTemplatebooleanWhether 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.
descriptionstringThe optional description of the dataset.
lastTrainedAtstringThe timestamp of last model that completed training. Uses the ISO-8601 standard.
{
"createdAt": "2021-08-24T12:04:32Z",
"datasetId": "dde4eeae-7652-4bc8-8be1-1cd6ac898dc7",
"description": "This dataset has a list of frequently asked questions about MessageBird",
"isTemplate": false,
"lastTrainedAt": "2021-08-24T12:04:32Z",
"name": "MessageBird FAQ",
"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.

PredictAnswer

Predicts an answer corresponding to a question which is possibly contained in the phrase given an FAQ dataset. The FAQ API uses machine learning to generalize from the questions and answers in the dataset to infer the answer of the given question. This requires the active model for the dataset to be trained. Training a model usually takes around 1 minute 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-answer

URL Parameters

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

Request (PredictAnswerRequest)

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

ParameterTypeDescription
phrasestringThe phrase that might contain a question to be answered.
curl -X POST "https://faq.messagebird.com/api/v1/datasets/{datasetId}/predict-answer" \
-H "Authorization: AccessKey your_access_key" \
-H "Content-Type: application/json" \
-d '{
"phrase": "Who founded MessageBird?"
}'

Response (PredictAnswerResponse)

A response that contains the answer and its related metadata, such as a URL pointing to more details. If the FAQ API could not find a corresponding answer, the answer field will not be populated.

ParameterTypeDescription
answerAnswerAn answer which corresponds to one or more example questions in the dataset.
answerPredictedbooleanIndicates if an answer was predicted. If false, the phrase could not be matched with an answer.
{
"answer": {
"text": "Messagebird was founded by Robert Vis in 2011.",
"title": "MessageBird Founder",
"url": "https://messagebird.com/en/about"
},
"answerPredicted": false
}
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 FAQ API.

GET /api/v1/supported-languages
curl -X GET "https://faq.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

Answer object

An answer which corresponds to one or more example questions in the dataset.

ParameterTypeDescription
textstringThe text containing the answer.
urlstringThe URL with additional information for this answer.
titlestringThe short title representing the answer.

Dataset object

A collection of answers with matching questions. There can be multiple matching questions per answer.

ParameterTypeDescription
datasetIdstringThe unique ID for the dataset.
namestringThe name of the dataset.
createdAtstringThe timestamp of dataset creation. Uses the ISO-8601 standard.
updatedAtstringThe timestamp of last update. Uses the ISO-8601 standard.
isTemplatebooleanWhether 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.
descriptionstringThe optional description of the dataset.
lastTrainedAtstringThe timestamp of last model that completed training. Uses the ISO-8601 standard.

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.

ListDatasetsMode enum

The list mode indicating to query public datasets, only user datasets or both.

ValueDescription
LIST_MODE_UNDEFINEDThe list dataset mode type undefined.
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 FAQ 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 query the next paginated collection of results.

PredictAnswerResponse object

A response that contains the answer and its related metadata, such as a URL pointing to more details. If the FAQ API could not find a corresponding answer, the answer field will not be populated.

ParameterTypeDescription
answerAnswerThe answer that is predicted for the given phrase. If no matching answer was found, this field will not be populated.
answerPredictedbooleanIndicates if an answer was predicted. If false, the phrase could not be matched with an answer.

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