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

descriptionstring

Optional

Not PII

The type of knowledge source.

idstringrequired

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_detailsobject

Optional

Not PII

The details of the knowledge source based on the type.

namestringrequired

Not PII

The name of the knowledge source.

statusstring

Optional

Not PII

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

typestringrequired

Not PII

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

urlstring

Optional

Not PII

The url of the knowledge resource.

embedding_modelstring

Optional

Not PII

The embedding model to be used for the knowledge source.

date_createdstring<date-time>required

Not PII

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

date_updatedstring<date-time>required

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_idstring

Optional

Not PII

The Assistant ID.

Pattern: ^aia_asst_*$

descriptionstring

Optional

Not PII

The description of the knowledge source.

knowledge_source_detailsobject

Optional

Not PII

The details of the knowledge source based on the type.

namestringrequired

Not PII

The name of the tool.

policyobject

Optional

Not PII

The policy associated with the knowledge source.

Show child properties for policy

typestringrequired

Not PII

The type of the knowledge source.

embedding_modelstring

Optional

Not PII

The embedding model to be used for the knowledge source. It's required for 'Database' type but disallowed for other types.

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

Get a Knowledge source

Fetch details about a single Knowledge source

Get a Knowledge source

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("aia_know").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  "embedding_model": "embedding_model",
7  "id": "aia_know",
8  "knowledge_source_details": {},
9  "name": "name",
10  "status": "status",
11  "type": "type",
12  "url": "url"
13}

Fetch status of a Knowledge source

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

When you create a Knowledge source, Twilio AI Assistants processes the Knowledge so it's accessible to your Assistant. You can fetch the status of processing for a given Knowledge Source.

Get the status of a Knowledge source

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 fetchKnowledgeStatus() {
11  const knowledgeStatus = await client.assistants.v1
12    .knowledge("aia_know")
13    .knowledgeStatus()
14    .fetch();
15
16  console.log(knowledgeStatus.accountSid);
17}
18
19fetchKnowledgeStatus();

Output

1{
2  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "date_updated": "2009-07-06T20:30:00Z",
4  "last_status": "last_status",
5  "status": "status"
6}

List Knowledge sources

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

Query parameters

Property nameTypeRequiredPIIDescription

AssistantIdstring

Optional

Not PII

Pageinteger

Optional

Not PII

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

Minimum: 0

PageSizeinteger

Optional

Not PII

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

Minimum: 1Maximum: 1000

PageTokenstring

Optional

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      "embedding_model": "embedding_model",
13      "date_created": "2009-07-06T20:30:00Z",
14      "date_updated": "2009-07-06T20:30:00Z"
15    }
16  ],
17  "meta": {
18    "first_page_url": "https://www.example.com",
19    "key": "key",
20    "next_page_url": "https://www.example.com",
21    "page": 42,
22    "page_size": 42,
23    "previous_page_url": "https://www.example.com",
24    "url": "https://www.example.com"
25  }
26}

Delete a Knowledge source

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

Path parameters

Property nameTypeRequiredPIIDescription

idstringrequired

Not PII

the Knowledge ID.

Delete a Knowledge source

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 deleteKnowledge() {
11  await client.assistants.v1.knowledge("aia_know").remove();
12}
13
14deleteKnowledge();