Create and configure a scripted REST API for your custom chat integration

Create a scripted REST API, add a scripted REST resource, set security and content negotiation, and set REST API rate limits.

Before you begin

Map rich controls to the channel in your custom chat integration.

Role required: admin

Procedure

Create the REST API.
1. Navigate to All > System web services > Scripted Web Services > Scripted REST APIs.
2. Click New.
3. On the form, fill in the fields.

Field	Description
Name	Name of your API. For example, `ACME Mobile App Chat Adapter`.
API ID	API identifier. For example, `acme_chat`.
Protection policy	The protection policy for the script.- Read-only: Script is viewable only. Protected: Users with password permissions can edit the script.
Application	The application containing the script record. Global is selected by default.
API namespace	The namespace the API belongs to. The value depends on the current application scope.

4. Click **Submit**.

5.  Open the new record, navigate to **Related Links** and click **Enable Versioning**, and then click **OK**.

    Click **Update** to save your changes.

Add a scripted REST resource to your new REST API.

The scripted REST resource defines the scripted REST API definition that you created.
1. Open the REST API record you created, and then navigate to the Resources tab under Related Links.
2. Click New.
  
  Retrieve the payload from the request, and then write it to a hybrid queue.
3. On the form, fill in the fields.

Field	Description
API Definition	Name of the parent API.
Application	The application containing the script record.
Name	Name of your API REST Resource. For example, ACME chat.
API version	API version. For example, v1.This field displays only if you enabled versioning for the REST API.
Active	Option to make the REST resource active.
HTTP method	HTTP method, such as POST, GET, and so forth.
Relative path	Relative path to the resource.
Script	Script for the REST resource.
Protection policy	The protection policy for the script.- Read-only: Script is viewable only. Protected: Users with password permissions can edit the script.

Example of a scripted REST resource:

    ```
    (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
        var body = request.body;
        var queryParams = request.queryParams; // incoming content is application/x-www-form-urlencoded in this example    
        // 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.
        var providerAppId = "a5f8b75b7377001042281188caf6a73a";    
        // the time of receipt is recorded for analytics purposes
        var d = new Date();
        var logTime = d.getTime();    
        // add this message to the VA Server queue for processing
        var queued = sn_cs.VASystemObject.enqueueCustomAdapterMessage(providerAppId, JSON.stringify(queryParams), JSON.stringify(request.headers), logTime);
        if (queued == false) {
    	response.setError(new sn_ws_err.BadRequestError('Failed to process the request.'));
        }
    })(request, response);
    
    ```

Set security and content negotiation for your scripted REST resource.

Choose to set authentication and request formats. If your custom integration does not rely on authentication, you may want to remove it as follows.
1. In the new record for the Scripted REST Resource, navigate to the Security tab.
2. Clear Requires authentication.
3. Click the Content Negotiation tab, and then select Override supported request formats.
4. Click Submit.
Set REST API rate limits to define the rate of incoming requests.
1. Navigate to All > System web services > REST > Rate Limit Rules.
2. Click New.
3. On the form, fill in the fields.

Field	Description
Name	Unique name for the rate limit rule.
REST API	REST API that you created in an earlier step.
Version	Version of the REST API. Values listed depend on the selected REST API.
Resource	Resource for the specified Version. Values listed depend on the selected Version.
Active	Check 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.
Request limit per hour	Maximum 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.
Apply to	Users restricted by this rule. Select All users.

4. Click **Submit**.

What to do next

Create the action scripts for your custom chat integration

title	Create and configure a scripted REST API for your custom chat integration
description	Create a scripted REST API, add a scripted REST resource, set security and content negotiation, and set REST API rate limits.
locale	en-US
canonical_url	https://www.servicenow.com/docs/r/conversational-interfaces/virtual-agent/configure-rest-api-va-cccif.html
release	brazil
product	Virtual Agent
classification	virtual-agent
topic_type	task
last_updated	2026-09-10
reading_time_minutes	3
breadcrumb	Create conversational custom chat integrationCreate custom chat integrationsConfigureVirtual AgentConversational Interfaces