NAV Navbar
Logo
cURL javascript

FPT.AI API - 3.0 (for V2)

Introduction

FPT.AI is a conversational platform that allows developers to add a natural language interface to any app or any device. Common applications include:

There are two main components:

FPT.AI is available as a set of open APIs and SaaS products using latest cloud technologies. We offer a free tier for individual developers and comprehensive service packages for enterprise

General

Authentication

Every API request sent to FPT.AI must have an Authorization HTTP header with the token of bot.

Authorization: Bearer your_application_token

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/intent \
  -H 'Authorization: Bearer your_application_token'

You application token is retrieved from your bot:

Authen App Token

Error Code

FPT.AI response has list of error codes below:

Example response

{
    "code": "error_code",
    "message": "Not found"
}

NLP - Intent

List

Gets the list of all available intents for the application.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/intent \
  -H 'Authorization: Bearer your_application_token'

Example response

[
    {
        "code": "4lg0a7rcwikqwc38l32k3x5po79sfg8n",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "label": "ask_inventory",
        "description": "Import",
        "created_time": "2018-10-03T04:16:04Z",
        "intent_type": 0
    },
    {
        "code": "73z4bzfjh7jzv2th9f0w3f0pm1nhaccp",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "label": "ask_filter",
        "description": "Chức năng filter",
        "created_time": "2018-10-03T04:16:04Z",
        "intent_type": 0
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/intent

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a list of available intents for the application.

Create

Creates a new intent with the given parameters.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/intent \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
        "label":"product_info",
        "description":"Product information"
      }'

Example response

{
    "code": "ppmrtdpcuoxcxd0mg65lg4312pdg3u2e",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_info",
    "description": "Product information",
    "created_time": "2018-01-11T16:05:49.2237404+07:00"
}

Request

POST https://v3-api.fpt.ai/api/v3/intent

Parameters

Parameter Required Description
label yes name of the intent, must use a-z0-9_
description yes description of the intent

Response

Returns a JSON object represents the created intent.

Get

Gets an intent with the given name.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/intent/product_info \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "code": "ppmrtdpcuoxcxd0mg65lg4312pdg3u2e",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_info",
    "description": "Product information",
    "created_time": "2018-01-11T09:05:49Z"
}

Request

GET https://v3-api.fpt.ai/api/v3/intent/:intent_label

Parameters

Parameter Required Description
intent_label yes name of the intent

Response

Returns a JSON object that represents the intent.

Delete

Deletes an intent specified by name.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/intent/product_info \
  -H 'Authorization: Bearer your_application_token'

Example response

HTTP 200 OK

Request

DEL https://v3-api.fpt.ai/api/v3/intent/:intent_label

Parameters

Parameter Required Description
intent_label yes name of the intent

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an intent specified by its name with the given parameters. You can update the description only.

Example request

curl -X PUT \
  https://v3-api.fpt.ai/api/v3/intent/product_info \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "description":"New Description"
  }'

Example response:

{
    "code": "ppmrtdpcuoxcxd0mg65lg4312pdg3u2e",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_info",
    "description": "New Description",
    "created_time": "2018-01-11T09:05:49Z"
}

Request

PUT https://v3-api.fpt.ai/api/v3/intent/:intent_label

Parameters

Parameter Required Description
description yes new description of the intent

Response

Returns a JSON object that represents the updated intent.

List samples of intent

List samples of intent.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/intent/{label}/samples \
  -H 'Authorization: Bearer your_application_token'

Example response

[
    {
        "code": "m1iid0dbif63meubpw5v2xn72k8g7hh4",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Hi, em có người yêu chưa",
        "created_time": "2018-10-03T04:16:11Z",
        "intent_label": "chao_hoi",
        "intent_type": 0,
        "entities": []
    },
    {
        "code": "b7fxxr2sq6ycdrimaxlvcitr6x35tieo",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Shop ơi cho em hỏi chút thông tin với",
        "created_time": "2018-10-03T04:16:10Z",
        "intent_label": "chao_hoi",
        "intent_type": 0,
        "entities": []
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/intent/{label}/samples

Parameters

Parameter Required Description
label yes The label of intent

Response

Returns a list of samples of intent for the application.

Delete all samples of intent

Delete all samples of intent.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/intent/{label}/samples \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DELETE https://v3-api.fpt.ai/api/v3/intent/{label}/samples

Parameters

Parameter Required Description
label yes The label of intent

Response

Returns a message of status of delete request.

NLP - Entity

List

Gets the list of all available entities for the application.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/entity \
  -H 'Authorization: Bearer your_application_token'

Example response

[
    {
        "code": "7j0lqsf2phw10oik1vkckl0dlf1k9msz",
        "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
        "label": "qty",
        "type": 1,
        "description": "Quantity",
        "created_time": "2018-01-11T09:22:40Z"
    },
    {
        "code": "qj9rbjqjazy8w73fr1h2q71zqct6dsz8",
        "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
        "label": "product_name",
        "type": 1,
        "description": "Product name",
        "created_time": "2018-01-11T09:18:31Z"
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/entity

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a list of available entities for the application.

Create

Creates a new entity with the given parameters.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/entity \
  -H 'Authorization: Bearer your_application_token'
  -d '{
          "label":"product_name",
          "description":"Product name",
          "type": 1
      }'

Example response

{
    "code": "qj9rbjqjazy8w73fr1h2q71zqct6dsz8",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_name",
    "type": 1,
    "description": "Product name",
    "created_time": "2018-01-11T16:18:31.1608251+07:00"
}

HTTP Request

POST https://v3-api.fpt.ai/api/v3/entity

Parameters

Parameter Required Description
label yes name of the entity, must use a-z0-9_
description yes description of the entity
type yes type of the entity, value: 1: keyword & freetext; 2: keyword; 3: freetext

Response

Returns a JSON object represents the created entity.

Get

Gets an entity with the given name.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/entity/product_name \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "code": "qj9rbjqjazy8w73fr1h2q71zqct6dsz8",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_name",
    "type": 1,
    "description": "Product name",
    "created_time": "2018-01-11T09:18:31Z"
}

HTTP Request

GET https://v3-api.fpt.ai/api/v3/entity/:label

Parameters

Parameter Required Description
label yes name of the entity

Response

Returns a JSON object that represents the intent.

Delete

Deletes an entity specified by name.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/entity/product_name \
  -H 'Authorization: Bearer your_application_token'

Example response

HTTP 200 OK

HTTP Request

DEL https://v3-api.fpt.ai/api/v3/entity/:label

Parameters

Parameter Required Description
label yes name of the entity

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an entity specified by its name with the given parameters. You can update the description only.

Example request

curl -X PUT \
  https://v3-api.fpt.ai/api/v3/entity/product_name \
  -H 'Authorization: Bearer your_application_token'
  -d {
    "description":"New Description",
    "type":1
}

Example response

{
    "code": "qj9rbjqjazy8w73fr1h2q71zqct6dsz8",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "label": "product_name",
    "type": 1,
    "description": "New Description",
    "created_time": "2018-01-11T09:18:31Z"
}

Request

PUT https://v3-api.fpt.ai/api/v3/entity/:label

Parameters

Parameter Required Description
description yes new description of the entity
type yes type of the entity, value: 1: keyword & freetext; 2: keyword; 3: freetext

Response

Returns a JSON object that represents the updated entity.

Get all samples of entity

List all samples of entity.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/entity/{lable}/samples \
  -H 'Authorization: Bearer your_application_token'

Example response

[
  {
        "code": "alpqyg5bnzqsl2p8ftnp6ufesa9ocigj",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Thẻ nhớ ngoài hỗ trợ bao nhiêu GB?",
        "created_time": "2018-10-03T04:16:07Z",
        "intent_label": "ask_attribute",
        "intent_type": 0,
        "entities": [
            "the_nho_ngoai"
        ]
    },
    {
        "code": "d1ujxrmhebjv59mxbxsepr64pd3pxm49",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Redmi note 5 có hỗ trợ thẻ nhớ không",
        "created_time": "2018-10-03T04:16:07Z",
        "intent_label": "ask_attribute_y_n",
        "intent_type": 0,
        "entities": [
            "the_nho_ngoai"
        ]
    }
]

Request

PUT https://v3-api.fpt.ai/api/v3/entity/{label}/samples

Parameters

Parameter Required Description
label yes The label of the entity

Response

Returns the list of samples of entity.

Delete all samples of entity

Delete all samples of entity.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/entity/{label}/samples \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DELETE https://v3-api.fpt.ai/api/v3/entity/{label}/samples

Parameters

Parameter Required Description
label yes The label of entity

Response

Returns a message of status of delete request.

NLP - Sample

List

Gets the list of all available samples.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/sample \

Example response:

[
    {
        "code": "0lvh6j25vvzw5bfq9ew45g0u3x8ndumc",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Cho hỏi đổi cũ lấy samsung-galaxy-s9-22246 như thế nào?",
        "created_time": "2018-10-03T04:16:11Z",
        "intent_label": "ask_general_information",
        "intent_type": 0,
        "entities": [
            "thu_cu_doi_moi"
        ]
    },
    {
        "code": "2890odc6jatr4wxlvqv8txzk3rtkv5ip",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "Có phụ kiện máy samsung-galaxy-s9-22246 không?",
        "created_time": "2018-10-03T04:16:11Z",
        "intent_label": "ask_product",
        "intent_type": 0,
        "entities": [
            "phu_kien"
        ]
    },
    {
        "code": "3ov9x6gowo1uvwewou9xg7qhljz3ht5e",
        "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
        "content": "cho hỏi về dòng máy có intel-hd-graphics",
        "created_time": "2018-10-03T04:16:11Z",
        "intent_label": "",
        "intent_type": 0,
        "entities": []
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/sample

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a list of available samples.

Create

Creates new sample.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/sample \
  -d '{
        "content": "Do you have fresh checken eggs?"
      }'

Example response

{
    "code": "inde8872kkv40g6jga8eyszfm0dz47vz",
    "app_code": "ryca8xy0bza17j0f2xiv00ljg8j8gscs",
    "content": "Do you have fresh checken eggs?",
    "created_time": "2018-01-11T16:00:44.025515Z"
}

HTTP Request

POST https://v3-api.fpt.ai/api/v3/sample

Parameters

Parameter Required Description
content yes content of the sample

Response

Returns a JSON object represents the created sample.

Get

Gets an sample with the given sample code.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/sample/2fcli497oqfbrvte2nevm5ft962y5svp \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "code": "2fcli497oqfbrvte2nevm5ft962y5svp",
    "app_code": "0xtqlndqkmuht0z1xcgzg0eyplz1jztk",
    "content": "Sample text 1",
    "created_time": "2017-10-24T13:47:17Z",
    "intent": {
        "intent_sample_code": "il6pc9dvz1t8px2weebep60ygczav4b2",
        "intent_code": "7sdsWZJDQp",
        "sample_code": "2fcli497oqfbrvte2nevm5ft962y5svp",
        "intent_label": "intent_label"
    },
    "entities": [
        {
            "entity_sample_code": "7apu89e0co3hmcjai036yh695xqhsktv",
            "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
            "sample_code": "2fcli497oqfbrvte2nevm5ft962y5svp",
            "parent_code": "",
            "value": "SomeValue",
            "start": 2,
            "end": 5,
            "created_time": "",
            "label": "sample_label_1",
            "Type": 1
        },
        {
            "entity_sample_code": "gudgybpeqxjokerfmrd96jxbjx5ngeae",
            "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
            "sample_code": "2fcli497oqfbrvte2nevm5ft962y5svp",
            "parent_code": "",
            "value": "SomeValue",
            "start": 2,
            "end": 5,
            "created_time": "",
            "label": "sample_label_1",
            "Type": 1
        }
    ]
}

Request

GET https://v3-api.fpt.ai/api/v3/sample/:sample_code

Parameters

Parameter Required Description
sample_code yes code of the sample

Response

Returns a JSON object that represents the sample.

Delete

Deletes an sample specified by its code.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/sample/2fcli497oqfbrvte2nevm5ft962y5svp \
  -H 'Authorization: Bearer your_application_token'

Example response

{
  "message": "Deleted"
}

Request

DEL https://v3-api.fpt.ai/api/v3/sample/:sample_code

Parameters

Parameter Required Description
sample_code yes code of the sample

Response

Returns HTTP Status 200 if the request succeed.

Update

Updates an sample with the given parameters.

Example request

curl -X PUT \
  https://v3-api.fpt.ai/api/v3/sample/2fcli497oqfbrvte2nevm5ft962y5svp \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "content": "Sample text content updated"
}'

Example response

{
    "code": "2fcli497oqfbrvte2nevm5ft962y5svp",
    "app_code": "0xtqlndqkmuht0z1xcgzg0eyplz1jztk",
    "content": "Sample text content updated",
    "created_time": "2017-10-24T13:38:59Z"
}

Request

PUT https://v3-api.fpt.ai/api/v3/sample/:sample_code

Query Parameters

Parameter Required Description
sample_code yes code of the sample
content yes content of the sample

Response

Returns a JSON object that represents the updated sample.

Intent-Sample mapping - Create

Maps an intent with a sample.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/intent-sample \
  -d '{
  "intent_code": "slyv8l0it363mh9kl922j2z8uvy9o4i1",
  "sample_code": "8hal2kmfr9nj0ys323pxzjbcdxmaalra"
}'

Example response

{
    "intent_sample_code": "5g69998jk1ye6o8n6k0bbhc6s9is6g5m",
    "intent_code": "slyv8l0it363mh9kl922j2z8uvy9o4i1",
    "sample_code": "8hal2kmfr9nj0ys323pxzjbcdxmaalra",
    "intent_label": "",
    "intent_type": 0,
    "intent_description": ""
}

HTTP Request

POST https://v3-api.fpt.ai/api/v3/intent-sample

Parameters

Parameter Required Description
intent_code yes code of the intent
sample_code yes code of the sample

Response

Returns a JSON object represents the created intent-sample mapping.

Intent-Sample mapping - Delete

Unmap an intent from a sample by intent_sample_code.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/intent-sample/0X8pYfI0vWUR0uuVspjiaJRIQcf30e96 \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DEL https://v3-api.fpt.ai/api/v3/intent-sample/:intent_sample_code

Parameters

Parameter Required Description
intent_sample_code yes code of the map between intent and sample

Response

Returns a JSON object represents the result of deleting intent-sample mapping.

Intent-Sample mapping - Import

Create multiple intent-sample mappings.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/intent-sample/import_intent_samples \
  -d '[ 
          {
              "intent": "intent_1",
              "sample": "sample text 1"
          },
          {
              "intent": "intent_2",
              "sample": "sample text 2"
          }
      ]'

Example response

{
    "number_of_duplicate_sample": 0,
    "number_of_empty_intent": 0,
    "number_of_imported_intent": 2,
    "number_of_imported_sample": 2,
    "number_of_invalid_intent": 0
}

HTTP Request

POST https://v3-api.fpt.ai/api/v3/intent-sample/import_intent_samples

Parameters

Parameter Required Description
content yes list of intent-sample mappings (JSON format)

Response

Returns a JSON object represents the created intent-sample mapping.

Entity-Sample mapping - Create

Maps an entity with a sample via tagging words and start/end position of that tagging words in the sample.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/entity-sample \
  -d '{
  "entity_code":"we2y0ceca052thxtf7jq29kk2610vjgl",
  "sample_code":"8hal2kmfr9nj0ys323pxzjbcdxmaalra",
  "value":"SomeValue",
  "start":2,
  "end":5
}'

Example response

{
    "entity_sample_code": "rlrpyxl68d2gufk441na152zyby6l4ww",
    "entity_code": "we2y0ceca052thxtf7jq29kk2610vjgl",
    "sample_code": "8hal2kmfr9nj0ys323pxzjbcdxmaalra",
    "parent_code": "",
    "value": "SomeValue",
    "start": 2,
    "end": 5,
    "created_time": "2018-10-08T03:29:02Z",
    "label": "",
    "Type": 0
}

HTTP Request

POST https://v3-api.fpt.ai/api/v3/entity-sample

Parameters

Parameter Required Description
entity_code yes code of the entity
sample_code yes code of the sample
value yes tagging words
start yes star position of tagging words in the sample
end yes end position of tagging words in the sample

Response

Returns a JSON object represents the created entity-sample mapping.

Entity-Sample mapping - Delete

Unmap an entity from a sample by entity_sample_code.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/entity-sample/7apu89e0co3hmcjai036yh695xqhsktv \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DEL https://v3-api.fpt.ai/api/v3/entity-sample/:entity_sample_code

Parameters

Parameter Required Description
entity_sample_code yes code of the map between entity and sample

Response

Returns a JSON object represents the result of deleting entity-sample mapping.

NLP - Train

All

Requests FPT.AI to train/re-retrain for both intent model and entity model for the application.

Note: You MUST have at least 2 intents and 2 samples to train.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/train \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
    "message": "training request is accepted",
    "status": [
        {
            "code": "mlne8hmzfy4jmgvpn3itoh7w8jyks1ut",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 1,
            "state": 0,
            "message": "",
            "model_file": "",
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1": 0,
            "created_time": "2018-10-08T03:33:09Z",
            "finished_time": "2018-10-08T03:33:10Z",
            "started_time": "2018-10-08T03:33:10Z"
        },
        {
            "code": "g0a50948j6dd0asshcgszrhtaeeg807h",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 2,
            "state": 1,
            "message": "training",
            "model_file": "",
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1": 0,
            "created_time": "2018-10-08T03:33:09Z",
            "finished_time": "2018-10-08T03:33:10Z",
            "started_time": "2018-10-08T03:33:10Z"
        }
    ]
}

Request

POST https://v3-api.fpt.ai/api/v3/train

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON message represents the training status.

Training status

Requests FPT.AI get current train status of the application.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/train/status \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
    "last_success_time": "0001-01-01T00:00:00Z",
    "status": 1,
    "trainable": false
}

Request

POST https://v3-api.fpt.ai/api/v3/train/status

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON message represents the training status.

Status value Description
0 Waiting to train
1 Training
2 Train Success
3 Train Failed

Intent

Requests FPT.AI to train/re-retrain intent model for the application.

Note: You MUST have at least 2 intents to train.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/train/intent \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
    "message": "training request is accepted",
    "status": [
        {
            "code": "cxx6gfj2pypbp8s2ohxyiufw807bl34r",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 1,
            "state": 0,
            "message": "",
            "model_file": "",
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1": 0,
            "created_time": "2018-10-08T04:02:04Z",
            "finished_time": "2018-10-08T04:02:05Z",
            "started_time": "2018-10-08T04:02:05Z"
        },
        {
            "code": "g0a50948j6dd0asshcgszrhtaeeg807h",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 2,
            "state": 2,
            "message": "Model trained successfully with engine v2_entity and took 1034 seconds.",
            "model_file": "2018-10-08_10-33-17__v2_entity",
            "accuracy": 100,
            "precision": 100,
            "recall": 100,
            "f1": 100,
            "created_time": "2018-10-08T03:33:09Z",
            "finished_time": "2018-10-08T03:50:35Z",
            "started_time": "2018-10-08T03:33:10Z"
        }
    ]
}

Request

POST https://v3-api.fpt.ai/api/v3/train/intent

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON message represents the training status.

Entity

Requests FPT.AI to train/re-retrain entity model for the application.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/train/entity \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
    "message": "training request is accepted",
    "status": [
        {
            "code": "cxx6gfj2pypbp8s2ohxyiufw807bl34r",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 1,
            "state": 1,
            "message": "training",
            "model_file": "",
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1": 0,
            "created_time": "2018-10-08T04:02:04Z",
            "finished_time": "2018-10-08T04:02:05Z",
            "started_time": "2018-10-08T04:02:29Z"
        },
        {
            "code": "pxkaxumjdkqkr6ojd73a3upsvwfkvbg5",
            "app_code": "dfd6908df08cf9d825f9ca9d38bf4677",
            "type": 2,
            "state": 0,
            "message": "",
            "model_file": "",
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1": 0,
            "created_time": "2018-10-08T04:03:40Z",
            "finished_time": "2018-10-08T04:03:41Z",
            "started_time": "2018-10-08T04:03:41Z"
        }
    ]
}

Request

POST https://v3-api.fpt.ai/api/v3/train/entity

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON message represents the training status.

NLP - Predict

All

Requests FPT.AI to predict for both intents of and entities in the given text.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/predict \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "content": "Shop bán iPhone không?",
  "save_history": false
}'

Example response

{
    "status": {
        "code": 200,
        "message": "Predict All successful",
        "module": "",
        "api_code": 0,
        "err_code": 0
    },
    "data": {
        "intents": [
            {
                "label": "ask_product",
                "confidence": 0.92
            },
            {
                "label": "ask_general_information",
                "confidence": 0.04
            },
            {
                "label": "ask_inventory",
                "confidence": 0.03
            }
        ],
        "entities": [
            {
                "start": 9,
                "end": 15,
                "value": "iPhone",
                "real_value": "apple-iphone",
                "entity": "filter_brand",
                "subentities": null
            }
        ]
    },
    "history_id": 0
}

Request

POST https://v3-api.fpt.ai/api/v3/predict

Parameters

Parameter Required Description
content yes text to predict
save_history no save to history

Response

Returns a JSON object that contains predicted intents and entities with confidence values.

Intent

Requests FPT.AI to predict for intents of the given text.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/predict/intent \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "content": "do you have fresh chicken eggs?"
}'

Example response

{
    "status": {
        "code": 200,
        "message": "Predict Intents successful",
        "module": "",
        "api_code": 0,
        "err_code": 0
    },
    "data": {
        "intents": [
            {
                "label": "product_info",
                "confidence": 0.99
            },
            {
                "label": "purchase",
                "confidence": 0.005
            }
        ]
    }
}

Request

POST https://v3-api.fpt.ai/api/v3/predict/intent

Paramenters

Parameter Required Description
content yes text to predict
save_history no save to history

Response

Returns a JSON object that contains predicted intents with confidence values.

Entity

Requests FPT.AI to predict for entities in the given text.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/predict/entity \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
  "content": "I'd like to purchase some fresh vegetable",
  "save_history": false
}'

Example response

{
    "status": {
        "code": 200,
        "message": "Recognize Entities successful",
        "module": "",
        "api_code": 0,
        "err_code": 0
    },
    "data": {
        "entities": [
            {
                "start": 32,
                "end": 41,
                "value": "vegetable",
                "real_value": "vegetable",
                "entity": "product_name",
                "subentities": []
            }
        ]
    }
}

Request

POST https://v3-api.fpt.ai/api/v3/predict/entity

Paramenters

Parameter Required Description
content yes text to predict

Response

Returns a JSON object that contains predicted entities with confidence values.

NLP - Keyword

List

Gets the list of all available keywords for the entity.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label \
  -H 'Authorization: Bearer your_application_token'

Example response

[
    {
        "code": "m7hu5iywe8sz7n9puleell0kn1dpv4rl",
        "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
        "value": "keyword 1",
        "synonym": "[]",
        "type": 2
    },
    {
        "code": "s90q14jnvh8hb7fe5xfhdskmmr1emuro",
        "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
        "value": "keyword 2",
        "synonym": "[\"syn1\", \"syn2\"]",
        "type": 1
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/keyword/:entity_label

Parameters

Parameter Required Description
entity_label yes label of the entity

Response

Returns a list of available keywords for the entity.

Create

Creates a new keyword of the entity with the given parameters.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "value": "keyword",
    "synonym": "[\"synonym\"]"
}'

Example response

{
    "code": "lpnakotptlo06bhnz9ttzfgaielxxi7j",
    "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
    "value": "keyword",
    "synonym": "[\"synonym\"]",
    "type": 2
}

Request

POST https://v3-api.fpt.ai/api/v3/keyword/:entity_label

Parameters

Parameter Required Description
entity_label yes label of the entity
value yes keyword
synonym no list of synonyms for the keyword

Response

Returns a JSON object represents the created keyword for the entity.

Get

Gets an keyword of entity with the given keyword code.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label/lpnakotptlo06bhnz9ttzfgaielxxi7j \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "code": "lpnakotptlo06bhnz9ttzfgaielxxi7j",
    "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
    "value": "keyword",
    "synonym": "[\"synonym\"]",
    "type": 2
}

Request

GET https://v3-api.fpt.ai/api/v3/keyword/:entity_label/:keyword_code

Parameters

Parameter Required Description
entity_label yes label of the entity
keyword_code yes code of the keyword

Response

Returns a JSON object that represents the keyword.

Delete

Deletes an intent specified by name.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label/lpnakotptlo06bhnz9ttzfgaielxxi7j \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DEL https://v3-api.fpt.ai/api/v3/keyword/:entity_label/:keyword_code

Parameters

Parameter Required Description
entity_label yes label of the entity
keyword_code yes code of the keyword

Response

Returns a JSON object that represents deleting result.

Force delete

Force an intent specified by name.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label/lpnakotptlo06bhnz9ttzfgaielxxi7j/force-delete \
  -H 'Authorization: Bearer your_application_token'

Example response

{
    "message": "Deleted"
}

Request

DEL https://v3-api.fpt.ai/api/v3/keyword/:entity_label/:keyword_code/force-delete

Parameters

Parameter Required Description
entity_label yes label of the entity
keyword_code yes code of the keyword

Response

Returns a JSON object that represents deleting result.

Update

Updates an keyword specified by its code with the given parameters.

Example request

curl -X PUT \
  https://v3-api.fpt.ai/api/v3/keyword/entity_label/lpnakotptlo06bhnz9ttzfgaielxxi7j \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "value": "keyword",
    "synonym": "[\"synonym\"]"
}'

Example response:

{
    "code": "lpnakotptlo06bhnz9ttzfgaielxxi7j",
    "entity_code": "vfxpyqk5v9rn49zfcxf74hdra9h6zqx8",
    "value": "keyword",
    "synonym": "[\"synonym\"]",
    "type": 2
}

Request

PUT https://v3-api.fpt.ai/api/v3/keyword/:entity_label/:keyword_code

Parameters

Parameter Required Description
entity_label yes label of the entity
keyword_code yes code of the keyword
value yes value of the keyword
synonym yes list of synonyms for the keyword

Response

Returns a JSON object that represents the updated keyword.

NLP - Dictionary

Get list of dictionaries

Requests FPT.AI the list of dictionaries.

Example request

curl -X GET \
  https://v3-api.fpt.ai/api/v3/dictionary
  -H 'Authorization: Bearer your_application_token'

Example response

[
    {
        "code": "wnz56qw6exaytelvqtvw85tq39pm7njc",
        "word": "coffe",
        "meaning": "[\"cofe\",\"cà phê\", \"cà fe\"]"
    },
    {
        "code": "xyw9zvnwoolfya400tkg2mmwcoe083lg",
        "word": "thu nhập cá nhân",
        "meaning": "tncn"
    }
]

Request

GET https://v3-api.fpt.ai/api/v3/dictionary

Parameters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON contain list of dictionaries.

Create

Create a dictionary.

Example request

curl -X POST \
  https://v3-api.fpt.ai/api/v3/dictionary \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "word": "coffe",
    "meaning": "[\"cofe\",\"cà phê\", \"cà fe\"]"
}'

Example response

{
    "code": "l2i1ylfx9zo40q3n2vvoswzlcm9y3zc2",
    "word": "coffe",
    "meaning": "[\"cofe\",\"cà phê\", \"cà fe\"]"
}

Request

POST https://v3-api.fpt.ai/api/v3/dictionary

Paramenters

Parameter Required Description
word yes The key word of dictionary
meaning no Desciption of the key word

Response

Returns a JSON object that contains information of one elememt in dictionary.

Update

Update a dictionary.

Example request

curl -X PUT \
  https://v3-api.fpt.ai/api/v3/dictionary/l2i1ylfx9zo40q3n2vvoswzlcm9y3zc2 \
  -H 'Authorization: Bearer your_application_token' \
  -d '{
    "word": "coffe",
    "meaning": "[\"cofe\",\"cofee\",\"cà phê\", \"cà fe\"]"
}'

Example response

{
    "message": "Updated"
}

Request

POST https://v3-api.fpt.ai/api/v3/dictionary/{word_code}

Paramenters

Parameter Required Description
word yes The key word of dictionary
meaning no Desciption of the key word

Response

Returns a JSON object that contain message of result.

Delete

Delete a dictionary.

Example request

curl -X DELETE \
  https://v3-api.fpt.ai/api/v3/dictionary/l2i1ylfx9zo40q3n2vvoswzlcm9y3zc2  \
  -H 'Authorization: Bearer your_application_token' \

Example response

{
    "message": "Deleted"
}

Request

DELETE https://v3-api.fpt.ai/api/v3/dictionary/{word_code}

Paramenters

Parameter Required Description
n/a n/a n/a

Response

Returns a JSON object that contain message of result.

NLP - Migration from V2

  1. Go to FPT AI
  2. Select your app
  3. Go to Setting
  4. Go to Data management zone
  5. Click button Migrate from V2
  6. Input V2 app token into popup
  7. Click button Migrate

DME - Get answer

DME Get answer API

The request to send message to Webhook. You need setting your Webhook in Setting of bot. You send request to FPT.AI then FPT.AI will send result after finish proccess your content via your Webhook.

Example request

curl -X POST \
  https://bot.fpt.ai/api/get_answer/ \
  -H 'Authorization: Bearer <bot_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "api",
  "app_code": "137793bf9473297fb660e3e7adf5af25",
  "sender_id": "sender_id_abc",
  "type": "text",
  "message": {
    "content": "dat hang",
    "type": "text"
  }
}
'

Example response

HTTP 200 OK

Request

POST https://bot.fpt.ai/api/get_answer/

Parameters

Parameter Required Description
channel yes Always is api
messages yes Message content
app_code yes Bot code
sender_id yes ID of end user
type yes text or payload

Text Type

Example request

curl -X POST \
  https://bot.fpt.ai/api/get_answer/ \
  -H 'Authorization: Bearer <bot_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "api",
  "app_code": "137793bf9473297fb660e3e7adf5af25",
  "sender_id": "sender_id_abc",
  "type": "text",
  "message": {
    "content": "dat hang",
    "type": "text"
  }
}
'

Example response

HTTP 200 OK

Parameters

Parameter Required Description
channel yes Always is api
messages yes Message content
app_code yes Bot code
sender_id yes ID of end user
type yes text
content yes Content send to DME

Payload Type

Example request

curl -X POST \
  https://bot.fpt.ai/api/get_answer/ \
  -H 'Authorization: Bearer <bot_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "api",
  "app_code": "d9b1affb025bacb03a59abdf6773025e",
  "sender_id": "005232c6c845ed1606715f598828b9cd",
  "type": "payload",
  "message": {
    "content": "d776591574547b2d43b0b7697b9fbdda", 
    "type": "payload"
  }
}
'

Example response

HTTP 200 OK

Parameters

Parameter Required Description
channel yes Always is api
messages yes Message content
app_code yes Bot code
sender_id yes ID of end user
type yes payload
content yes Step code

Response

Returns a JSON message represents the request status.

DME - Broadcast

Send messages directly

The request to send message direct to end user.

Example request

curl -X POST \
  https://bot.fpt.ai/api/send_messages/ \
  -H 'Authorization: Bearer <bot_token>' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "content": {
        "text": "Toi la AI Bot, co the giup gi cho ban?"
      },
      "type": "text"
    }
  ],
  "app_code": "<bot code>",
  "sender_id": "<sender id>",
  "channel": "facebook"
}
'

Example response

HTTP 200 OK

Request

POST https://bot.fpt.ai/api/send_messages/

Parameters

Parameter Required Description
messages yes Message content send to user
app_code yes Bot code
sender_id yes ID of end user
channel yes One channel in: facebook, livechat or viber

Response

Returns a JSON message represents the request status.

DME - JSON Card

DME JSON API card

FPT.AI will call API and send message to user.

Declare variable

Declare variable

Json Card configure

Declare variable

Result of API (for example: https://api.sample.com)

Example response

{
  "set_attributes": {
    "voucher_code": "AKKSKKSKkSODS"
  },
  "messages": [
    {
      "type": "text",
      "content": {
        "text": "Ma uu dai cua ban la: AKKSKKSKkSODS"
      },
      "buttons": [
        {
          "title": "Chi tiet",
          "payload": "7f09e4b2cb63dc3fc98eb59e85f61dde"
        },
        {
          "title": "Thong tin chuong trinh",
          "url": "https://kichikichi.com.vn/dsfajsdljfla"
        }
      ]
    }
  ]
}

voucher_code: value will apply to "voucher_code" variable in "Scenario". messages: the list of message will send to user, this can declare in bot.fpt.ai affter json_card.

The types of message

Please read in DME - Types of the message part.

DME - Types of the message

DME have some types of the message include: Text, Image, Carousel, Form, Quick reply card

Text message

The message send to user.

Formart of message is:

{
  "channel": "api",
  "app_code": "cca157c89f060dbaa6250da371ca363b",
  "messages": [
    {
      "type": "text",
      "content": {
        "text": "Content of message",
        "buttons": [
          {
            "title": "B1",
            "payload": "42cd8262372b591cef7c5e1126cbac76"
          },
          {
            "title": "B2",
            "url": "https://v3.fpt.ai"
          },
          {
            "title": "B3",
            "phone_number": "+84999999999"
          }
        ]
      }
    }
  ],
  "sender_id": "sender_id_abc"
}

Description

Property Required Description
channel yes Channel of message
app_code yes Bot code
sender_id yes ID of end user
type yes Type of message in this case is 'text'
content.text yes Content of message
content.buttons No Buttons array of message. It can is empty
content.buttons.title yes Text label for button
content.buttons.payload no Step code will jump to
content.buttons.url no URL will open
content.buttons.phone_number no Phone number will call

Image message

The message is images send to user.

Formart of message is:

{
  "channel": "api",
  "app_code": "cca157c89f060dbaa6250da371ca363b",
  "messages": [
    {
      "type": "image",
      "content": {
        "title": "",
        "url": "https://cdn-static-v3.fpt.ai/upload/cca157c89f060dbaa6250da371ca363b/46954f056fcd28e60be401d9354fd68c.png"
      }
    }
  ],
  "sender_id": "sender_id_abc"
}

Description

Property Required Description
channel yes Channel of message
app_code yes Bot code
sender_id yes ID of end user
type yes Type of message (in this type is 'image')
content.title yes Title of image
content.url yes URL of image

The message is carousel send to user.

Formart of message is:

{
  "channel": "api",
  "app_code": "cca157c89f060dbaa6250da371ca363b",
  "messages": [
    {
      "type": "carousel",
      "content": {
        "carousel_cards": [
          {
            "image_url": "https://cdn-static-v3.fpt.ai/upload/cca157c89f060dbaa6250da371ca363b/f38b1c079ba87dc8d8c0ba57573fcf34.png",
            "subtitle": "B1 Desc",
            "title": "New Carousel",
            "buttons": [
              {
                "title": "B1",
                "payload": "42cd8262372b591cef7c5e1126cbac76"
              }
            ],
            "item_url": ""
          },
          {
            "image_url": "https://v3.fpt.ai/static/fptai/img/default-image.png",
            "subtitle": "B2 Desc",
            "title": "New carousel",
            "buttons": [
              {
                "title": "B2",
                "payload": "42cd8262372b591cef7c5e1126cbac76"
              }
            ],
            "item_url": ""
          }
        ]
      }
    }
  ],
  "sender_id": "sender_id_abc"
}

Description

Property Required Description
channel yes Channel of message
app_code yes Bot code
sender_id yes ID of end user
type yes Type of message (in this type is 'carousel')
content.carousel_cards yes The array of Carousel cards.
content.carousel_cards.title yes Title of card
content.carousel_cards.subtitle yes Description of card
content.carousel_cards.button no The array of buttons
content.carousel_cards.item_url no The link will open if click on item of carousel

Form message

The message send to user.

Formart of message is:

{
  "channel": "api",
  "app_code": "cca157c89f060dbaa6250da371ca363b",
  "messages": [
    {
      "type": "text",
      "content": {
        "text": "Cau hoi 2?"
      }
    }
  ],
  "sender_id": "sender_id_abc"
}

Description

Property Required Description
channel yes Channel of message
app_code yes Bot code
sender_id yes ID of end user
type yes Type of message in this case is 'text'
content.text yes Content of message

Quick Reply Card message

The message send to user.

Formart of message is:

{
  "channel": "api",
  "app_code": "cca157c89f060dbaa6250da371ca363b",
  "messages": [
    {
      "type": "quick_reply",
      "content": {
        "text": "Content of message",
        "buttons": [
          {
            "title": "B1",
            "payload": "42cd8262372b591cef7c5e1126cbac76"
          },
          {
            "title": "B2",
            "url": "https://v3.fpt.ai"
          },
          {
            "title": "B3",
            "phone_number": "+84999999999"
          }
        ]
      }
    }
  ],
  "sender_id": "sender_id_abc"
}

Description

Property Required Description
channel yes Channel of message
app_code yes Bot code
sender_id yes ID of end user
type yes Type of message in this case is 'quick_reply'
content.text yes Content of message
content.buttons No Buttons array of message. It can is empty
content.buttons.title yes Text label for button
content.buttons.payload no Step code will jump to
content.buttons.url no URL will open
content.buttons.phone_number no Phone number will call