# Custom NLP

{% hint style="info" %}
This feature is currently available to enterprise tiers only.
{% endhint %}

### Why use a custom NLP?

Off-the shelf NLP providers, such as Amazon Lex or Google Dialogflow, may not possess the functionality a business requires for handling conversations with its users. Large enterprises often resort to tailored solutions with a custom NLP model. 

#### How does NLX handle my custom NLP?

Just as Amazon Lex or Google Dialogflow provide APIs to ensure their NLPs are compatible with conversational AI builders, NLX provides you with simple API specifications that allow your custom NLP to handle the same actions. These include the build and deployment of an application as well as essential conversation runtime operations, such as disambiguating a user utterance. 

Identical to using off-the-shelf NLPs, testing utterances through our [automated test suite](https://docs.nlx.ai/platform/nlx-platform-guide/ai-applications/types/core/automated-tests), architecting and building flows using the [Canvas builder](https://docs.nlx.ai/platform/nlx-platform-guide/flows-and-building-blocks/overview/canvas), and tracking performance of conversations with [analytics](https://docs.nlx.ai/platform/nlx-platform-guide/monitoring/analytics) can all be done with a custom NLP.

After your custom NLP's API is made compatible and is integrated in NLX, you may select it as the engine of choice when [deploying your application](https://docs.nlx.ai/platform/nlx-platform-guide/ai-applications/types/core#deployment).

### Create compatible API

Your custom NLP's API interfaces with NLX to build your conversation flows and process user utterances.

<figure><img src="https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2FqN5wEvAihfZfjmJMLZT2%2FIntegration%20architecture.png?alt=media&#x26;token=62a1e4c8-45ed-4ba6-846c-c3c6987d09ee" alt=""><figcaption><p>Integration architecture</p></figcaption></figure>

As a result, before you can link your custom NLP in NLX, an API endpoint must be configured using our specification:

{% openapi src="<https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media&token=ece3f01f-ef37-4987-ad77-c0cf9301a914>" path="/disambiguate" method="post" %}
[nlx-custom-nlp-openapi.yaml](https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media\&token=ece3f01f-ef37-4987-ad77-c0cf9301a914)
{% endopenapi %}

{% openapi src="<https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media&token=ece3f01f-ef37-4987-ad77-c0cf9301a914>" path="/builds" method="post" %}
[nlx-custom-nlp-openapi.yaml](https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media\&token=ece3f01f-ef37-4987-ad77-c0cf9301a914)
{% endopenapi %}

The `signedUrl` attribute in the request body refers to [presigned S3 URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html) for accessing the bot's build metadata. The URL expires in 5 minutes, and should suffice for downloading and caching the metadata within `customNLP`. `customNLP` may cache and use the build metadata for disambiguation requests. The artifact is a zipped file containing the following top-level files and directories:

1. `intents` - A directory with information about the bot's intents.
   * Includes a sub-directory for each `languageCode`.
   * Within each `languageCode`, there is one JSON file per intent containing metadata such as `utterances`, `intentId`, and `slots`, with each utterance translated to the respective `languageCode`.
2. `slotTypes` - A directory with information about the bot's slots.
   * Includes a sub-directory for each `languageCode`.
   * Within each `languageCode`, there is one JSON file per slot with metadata like `values` and `synonyms` translated to the relevant `languageCode`.
3. `manifest.json` - A JSON file with metadata about the build, including attributes like `botId`, `buildId`, supported `languageCodes` and `createdTimestamp`.

{% openapi src="<https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2FBRBLzHhizYaeFxtZ9m6G%2Fnlx-custom-nlp-openapi.yaml?alt=media&token=29f90d9c-16af-4070-8635-47fc0b154fd6>" path="/builds/{buildId}" method="get" %}
[nlx-custom-nlp-openapi.yaml](https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2FBRBLzHhizYaeFxtZ9m6G%2Fnlx-custom-nlp-openapi.yaml?alt=media\&token=29f90d9c-16af-4070-8635-47fc0b154fd6)
{% endopenapi %}

{% openapi src="<https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media&token=ece3f01f-ef37-4987-ad77-c0cf9301a914>" path="/builds/{buildId}" method="put" %}
[nlx-custom-nlp-openapi.yaml](https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media\&token=ece3f01f-ef37-4987-ad77-c0cf9301a914)
{% endopenapi %}

{% hint style="warning" %}
Make sure to set up an API key for your API, as it will be required during the integration step. If you require private connectivity between NLX and your on-premises API, please contact your NLX Customer Success Manager.
{% endhint %}

Download full OpenAPI Specification:

{% file src="<https://2737319166-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHCxYxhIU0Bqkjj942mGk%2Fuploads%2F2x7mdIhCnGTxxUSQQ014%2Fnlx-custom-nlp-openapi.yaml?alt=media&token=ece3f01f-ef37-4987-ad77-c0cf9301a914>" %}

{% hint style="info" %}
You can import and visualize the NLX OpenAPI specifications using [Swagger Editor](https://editor-next.swagger.io/).
{% endhint %}

### Integrate your API

1. Select *Resources* from your workspace menu and choose *Integrations* card
2. Click *+ Add integration* > Choose *Custom NLP* from the dropdown
3. Provide your integration a name
4. Enter both your Endpoint URL and API key
5. Select *Create integration*

{% hint style="success" %}
Your integration is now available for selection when choosing an AI engine on your [custom app's configuration](https://docs.nlx.ai/platform/nlx-platform-guide/ai-applications/types/core#configuration).
{% endhint %}