On this page

Knowledge Resource

Knowledge provides your Assistant with access to unstructured data sources. This API allows you to programatically upload Knowledge for your Assistant to consume.

Knowledge Properties

Property nameTypeRequiredDescriptionChild properties

descriptionstringOptional

Not PII

The type of knowledge source.

idstringOptional

Not PII

The description of knowledge.

Pattern: ^aia_know_*$

account_sidSID<AC>Optional

Not PII

The SID of the Account that created the Knowledge resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

knowledge_source_detailsobjectOptional

Not PII

The details of the knowledge source based on the type.

namestringOptional

Not PII

The name of the knowledge source.

statusstringOptional

Not PII

The status of processing the knowledge source ('QUEUED', 'PROCESSING', 'COMPLETED', 'FAILED')

typestringOptional

Not PII

The type of knowledge source ('Web', 'Database', 'Text', 'File')

urlstringOptional

Not PII

The url of the knowledge resource.

date_createdstring<date-time>Optional

Not PII

The date and time in GMT when the Knowledge was created specified in ISO 8601 format.

date_updatedstring<date-time>Optional

Not PII

The date and time in GMT when the Knowledge was last updated specified in ISO 8601 format.

Create new Knowledge sources

POST https://assistants.twilio.com/v1/Knowledge

Request body parameters

Encoding type:application/json

Schema

Property nameTypeRequiredDescriptionChild properties

assistant_idstringOptional

Not PII

The Assistant ID.

Pattern: ^aia_asst_*$

descriptionstringOptional

Not PII

The description of the knowledge source.

knowledge_source_detailsobjectOptional

Not PII

The details of the knowledge source based on the type.

namestringrequired

Not PII

The name of the tool.

policyobjectOptional

Not PII

The policy associated with the knowledge source.

Show child properties for policy

typestringrequired

Not PII

The type of the knowledge source.

You can configure Knowledge sources of type: Web, Text, and File from the API.

Crawl a website

Give your Assistant a publicly-accessible URL to index information from. See additional details about web crawling limits.

Crawl a website

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createKnowledge() {
11  const knowledge = await client.assistants.v1.knowledge.create({
12    name: "Info about Twilio Alpha",
13    type: "Web",
14    description: "Use this for information about Twilio Alpha or AI Assistants",
15    knowledge_source_details: {
16      source: "https://twilioalpha.com",
17    },
18  });
19
20  console.log(knowledge.description);
21}
22
23createKnowledge();

Upload text

Provide plain text for your Assistant.

Upload text

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createKnowledge() {
11  const knowledge = await client.assistants.v1.knowledge.create({
12    name: "Star Wars Quotes",
13    type: "Text",
14    description: "Use this for famous Star Wars quotes",
15    knowledge_source_details: {
16      content: "This is the ship that made the Kessel Run in fourteen parsecs?",
17    },
18  });
19
20  console.log(knowledge.description);
21}
22
23createKnowledge();

Upload a file

Upload a file for your Assistant to reference. See supported file types.

Upload a file

1const fs = require('fs');
2// Before running this code, install "form-data" and "axios" using `npm install form-data axios`
3const FormData = require('form-data');
4const axios = require('axios');
5
6// Provision API Keys at twilio.com/console/runtime/api-keys
7// and set the environment variables. See http://twil.io/secure
8const apiKey = process.env.TWILIO_API_KEY;
9const apiSecret = process.env.TWILIO_API_SECRET;
10
11const uploadUrl = `https://assistants-upload.twilio.com/v1/Knowledge/Upload`;
12
13const form = new FormData();
14form.append('name', 'File Demo');
15form.append('description', 'A description of this file')
16form.append('type', 'File');
17form.append('assistant_id', 'aia_asst_xxxxxxxxxxxxxxxx');
18form.append('file_0', fs.createReadStream('README.md'), {
19  contentType: 'text/markdown',
20});
21
22// Create a new Function Version
23axios
24  .post(uploadUrl, form, {
25    auth: {
26      username: apiKey,
27      password: apiSecret,
28    },
29    headers: form.getHeaders(),
30  })
31  .then((response) => {
32    const newKnowledgeId = response.data.id;
33    console.log(newKnowledgeId);
34  });

Get a Knowledge source

GET https://assistants.twilio.com/v1/Knowledge/{id}

Path parameters

Property nameTypeRequiredPIIDescription

idstringrequired

Not PII

Fetch a Knowledge

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchKnowledge() {
11  const knowledge = await client.assistants.v1.knowledge("id").fetch();
12
13  console.log(knowledge.description);
14}
15
16fetchKnowledge();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "date_created": "2009-07-06T20:30:00Z",
4  "date_updated": "2009-07-06T20:30:00Z",
5  "description": "description",
6  "id": "id",
7  "knowledge_source_details": {},
8  "name": "name",
9  "status": "status",
10  "type": "type",
11  "url": "url"
12}

List Knowledge sources

GET https://assistants.twilio.com/v1/Knowledge

Query parameters

Property nameTypeRequiredPIIDescription

AssistantIdstringOptional

Not PII

PageintegerOptional

Not PII

The page index. This value is simply for client state.

Minimum: 0

PageSizeintegerOptional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000

PageTokenstringOptional

Not PII

The page token. This is provided by the API.

List multiple Knowledges

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listKnowledge() {
11  const knowledge = await client.assistants.v1.knowledge.list({ limit: 20 });
12
13  knowledge.forEach((k) => console.log(k.description));
14}
15
16listKnowledge();

Output

1{
2  "knowledge": [
3    {
4      "description": "description",
5      "id": "aia_know",
6      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7      "knowledge_source_details": {},
8      "name": "name",
9      "status": "status",
10      "type": "type",
11      "url": "url",
12      "date_created": "2009-07-06T20:30:00Z",
13      "date_updated": "2009-07-06T20:30:00Z"
14    }
15  ],
16  "meta": {
17    "first_page_url": "https://www.example.com",
18    "key": "key",
19    "next_page_url": "https://www.example.com",
20    "page": 42,
21    "page_size": 42,
22    "previous_page_url": "https://www.example.com",
23    "url": "https://www.example.com"
24  }
25}