Creating and using session IDs

Follow these steps to use a session ID with a REST API call.

Prerequisites: Before performing this task, you should have performed the Making your first REST API call quickstart to understand how to make a simple call. If you want to skip that quickstart, you should at least have a Bold360 AI account and knowledge base and know the basics about forming REST URLs.

Cookies should be enabled in the browser. If cookies are disabled, the collection of analytics data will be impacted.

About this task: This procedure shows how to call a Bold360 AI REST API endpoint that requires a session ID when performing an article search. You will first execute the /api/widget/v1/hello endpoint to obtain a session ID. You will then pass the session ID in the URL for the /api/kb/v1/autoComplete endpoint.

Session IDs are provided by the server upon request by the client. They allow an application to access certain REST API endpoints (and thus allow widgets to use those endpoints internally). Session IDs expire after a timeout configured on the server (usually 180 seconds), but they are refreshed by other APIs and can be renewed with a keep-alive endpoint. The endpoints that require a session ID are stateful, in that the server stores data associated with a visitor session, such as which KB and/or configuration is used for the session.

Steps:

Getting a session ID:
1. Open the Bold360 AI REST API Reference in a separate tab. Navigate to the "Start Session" /api/widget/v1/hello endpoint. Notice that while the documentation says only the url parameter is required, it also recommends that you specify either the kb or configId parameter.
2. Paste the /api/widget/v1/hello endpoint after the account and domain name portion of your URL.
3. Specify the kb in your URL. For example, https://account_name.nanorep.co/api/widget/v1/hello?kb=my_kb. (Alternately, you may specify the configID if you are working with a widget configuration.)
4. Add the url parameter, which is required. It identifies the page that loads a widget. The server can use this information to determine which widget configuration applies to this session. Since you aren't using a widget configuration in this example, you can specify something simple, such as http://example.com as the referring URL. For example, https://account_name.nanorep.co/api/widget/v1/hello?kb=my_kb&url=http://example.com.
5. Open the Developer Tools in a browser. Paste your URL into the browser's address bar and press Enter.
6. In the Network tab, view the results. You'll see that a session ID value is returned with a timeout in seconds.
  
  If you submit the same URL again, you'll receive a different session ID.
Using a session ID:
1. In the reference documentation navigate to the "Auto Complete" /api/kb/v1/autoComplete endpoint. For this endpoint, the sid and text parameters are required.
2. Paste the /api/kb/v1/autoComplete endpoint after the account and domain name portion of your URL.
3. Specify the text parameter in your URL with a request a customer might begin typing. For example, https://account_name.nanorep.co/api/kb/v1/autoComplete?text=how%20do%20I.
4. Specify the sid parameter by pasting the sessionID returned by your latest execution of the /api/widget/v1/hello endpoint. If it has been more than 3 minutes, run the /api/widget/v1/hello endpoint again. For example, https://account_name.nanorep.co/api/kb/v1/autoComplete?text=how%20do%20I&sid=8097155355223972100
5. Paste your URL into the browser's address bar and press Enter.
  
  You should see a list of records that match your text parameter. If your session ID has expired, you will receive a 400 (Bad Request) HTTP status code.

Notice that you do not need to identify the KB when you provide the session ID. That is because the KB was specified when you obtained the session ID. Information about which KB is used by a particular session ID is stored on the server, which makes session IDs stateful.

What next? Try specifying other parameters with the endpoints you used. For example, add the maxResults parameter to /api/kb/v1/autoComplete to specify how many articles to return.

Other endpoints that use a session ID include:

/api/kb/v1/search – Sends a query for articles.
/api/widget/v1/keepAlive – Keeps the session from expiring for another timeout period.
/api/widget/v1/die – Closes a session.
Endpoints related to channeling, analytics, voices, tickets, redirection, guidance, and permissions.