{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":4844,"path":"conversational-interfaces/virtual-agent/configure-rest-api-va-cccif.md","title":"Create and configure a scripted REST API for your custom chat integration","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create and configure a scripted REST API for your custom chat integration\n\nCreate a scripted REST API, add a scripted REST resource, set security and content negotiation, and set REST API rate limits.\n\n## Before you begin\n\n[Map rich controls to the channel in your custom chat integration](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/map-rich-controls-va-cccif.md).\n\nRole required: admin\n\n## Procedure\n\n1. Create the REST API.\n\n 1. Navigate to **All** > **System web services** > **Scripted Web Services** > **Scripted REST APIs**.\n\n 2. Click **New**.\n\n 3. On the form, fill in the fields.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nName\n\n\n\nName of your API. For example, `ACME Mobile App Chat Adapter`.\n\n
\n\nAPI ID\n\n\n\nAPI identifier. For example, `acme_chat`.\n\n
\n\nProtection policy\n\n\n\nThe protection policy for the script.- **Read-only**: Script is viewable only.\n- **Protected**: Users with password permissions can edit the script.\n\n\n
\n\nApplication\n\n\n\nThe application containing the script record. **Global** is selected by default.\n\n
\n\nAPI namespace\n\n\n\nThe namespace the API belongs to. The value depends on the current application scope.\n\n
4. Click **Submit**.\n\n 5. Open the new record, navigate to **Related Links** and click **Enable Versioning**, and then click **OK**.\n\n Click **Update** to save your changes.\n\n2. Add a scripted REST resource to your new REST API.\n\n The scripted REST resource defines the scripted REST API definition that you created.\n\n 1. Open the REST API record you created, and then navigate to the **Resources** tab under **Related Links**.\n\n 2. Click **New**.\n\n Retrieve the payload from the request, and then write it to a hybrid queue.\n\n 3. On the form, fill in the fields.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nAPI Definition\n\n\n\nName of the parent API.\n\n
\n\nApplication\n\n\n\nThe application containing the script record.\n\n
\n\nName\n\n\n\nName of your API REST Resource. For example, **ACME chat**.\n\n
\n\nAPI version\n\n\n\nAPI version. For example, **v1**.This field displays only if you enabled versioning for the REST API.\n\n
\n\nActive\n\n\n\nOption to make the REST resource active.\n\n
\n\nHTTP method\n\n\n\nHTTP method, such as POST, GET, and so forth.\n\n
\n\nRelative path\n\n\n\nRelative path to the resource.\n\n
\n\nScript\n\n\n\nScript for the REST resource.\n\n
\n\nProtection policy\n\n\n\nThe protection policy for the script.- **Read-only**: Script is viewable only.\n- **Protected**: Users with password permissions can edit the script.\n\n\n
Example of a scripted REST resource:\n\n ```\n (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {\n var body = request.body;\n var queryParams = request.queryParams; // incoming content is application/x-www-form-urlencoded in this example \n // get the provider application sys id. this can be done via a glide query using incoming data such as where the original message is being sent to. or it can be hard-coded such as this example.\n var providerAppId = \"a5f8b75b7377001042281188caf6a73a\"; \n // the time of receipt is recorded for analytics purposes\n var d = new Date();\n var logTime = d.getTime(); \n // add this message to the VA Server queue for processing\n var queued = sn_cs.VASystemObject.enqueueCustomAdapterMessage(providerAppId, JSON.stringify(queryParams), JSON.stringify(request.headers), logTime);\n if (queued == false) {\n \tresponse.setError(new sn_ws_err.BadRequestError('Failed to process the request.'));\n }\n })(request, response);\n ​\n ```\n\n3. Set security and content negotiation for your scripted REST resource.\n\n Choose to set authentication and request formats. If your custom integration does not rely on authentication, you may want to remove it as follows.\n\n 1. In the new record for the Scripted REST Resource, navigate to the **Security** tab.\n\n 2. Clear **Requires authentication**.\n\n 3. Click the **Content Negotiation** tab, and then select **Override supported request formats**.\n\n 4. Click **Submit**.\n\n4. Set REST API rate limits to define the rate of incoming requests.\n\n 1. Navigate to **All** > **System web services** > **REST** > **Rate Limit Rules**.\n\n 2. Click **New**.\n\n 3. On the form, fill in the fields.\n\n\n
\n\nField\n\n\n\nDescription\n\n
\n\nName\n\n\n\nUnique name for the rate limit rule.\n\n
\n\nREST API\n\n\n\nREST API that you created in an earlier step.\n\n
\n\nVersion\n\n\n\nVersion of the REST API. Values listed depend on the selected REST API.\n\n
\n\nResource\n\n\n\nResource for the specified Version. Values listed depend on the selected Version.\n\n
\n\nActive\n\n\n\nCheck box to indicate that the rate limit rule is active.Rate limit rules are activated by default as soon as you create them. You can deactivate rate limit rules to stop enforcing a rate limit or activate rate limit rules to resume enforcing a rate limit.\n\n
\n\nRequest limit per hour\n\n\n\nMaximum number of requests allowed per hour.**Note:** Whenever you update the value of this field, the ServiceNow AI Platform resets the count of requests to 0 and deletes all violations for the current hour.\n\n
\n\nApply to\n\n\n\nUsers restricted by this rule. Select **All users**.\n\n
4. Click **Submit**.\n\n\n## What to do next\n\n[Create the action scripts for your custom chat integration](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/create-action-scripts-va-cccif.md)\n\n**Parent Topic:**[Create a Virtual Agent conversational custom chat integration](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/conversational-interfaces/virtual-agent/create-adapter-for-virtual-agent.md)\n\n"}}