Agent Copilot: Upload your knowledge sources using the API (public beta)

(new)

Public Beta

Agent Copilot is currently available as a Public Beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Public Beta products are not covered by a SLA.

(warning)

Not a HIPAA Eligible Service or PCI Compliant

Agent Copilot is not a HIPAA Eligible Service or PCI compliant and should not be used in Flex workflows that are subject to HIPAA or PCI. However, we offer mitigation tools such as PII redaction. To learn more, see AI data use.

Overview

This guide describes how to upload your knowledge sources to Agent Copilot using the Knowledge API.

Step 1: Upload your knowledge sources

Upload a file

Upload a file for Agent Copilot to reference.

1curl --location 'https://knowledge.twilio.com/v1/Knowledge/Upload' \
2--header 'Authorization: {Token}' \
3--form 'name="purchase-details"' \
4--form 'type="File"' \
5--form 'file_0=@"/Users/Documents/Purchase Details.pdf"'

Response

1{
2   "id": "aia_know_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
3   "name": "purchase-details",
4   "ParentAccountSid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5   "type": "File",
6   "knowledge_source_details": {
7       "file_name": "Purchase Details.pdf"
8   },
9   "status": "QUEUED",
10   "return_direct": false,
11   "date_created": "2025-06-10T23:50:50.934129Z",
12   "date_updated": "2025-06-10T23:50:50.934129Z",
13   "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14   "url": "https://knowledge.twilio.com/v1/Knowledge/aia_know_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
15   "metadata": {}
16}

Upload text

Provide plain text for Agent Copilot.

1curl --location 'https://knowledge.twilio.com/v1/Knowledge' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Basic {TOken}' \
4--data '{
5    "description": "Text description",
6    "name": "Text source",
7    "type": "Text",
8    "knowledge_source_details": {
9        "content":"Text source with all the details"
10    }
11}'

Response

1{
2   "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3   "date_created": "2025-06-10T23:54:43Z",
4   "date_updated": "2025-06-10T23:54:43Z",
5   "description": "Text description",
6   "embedding_model": null,
7   "id": "aia_know_bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
8   "knowledge_source_details": {
9       "content": "Text source with all the details"
10   },
11   "name": "Text source",
12   "status": "QUEUED",
13   "type": "Text",
14   "url": "https://knowledge.twilio.com/v1/Knowledge/aia_know_bbbbbbbb-cccc-dddd-eeee-ffffffffffff"
15}

Crawl a website

Give Agent Copilot a publicly accessible URL to index information from.

1curl --location 'https://knowledge.twilio.com/v1/Knowledge' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Basic {Token}' \
4--data '{
5    "description": "Web description",
6    "name": "Twilio web",
7    "type": "Web",
8    "knowledge_source_details": {
9        "source":"https://en.wikipedia.org/wiki/Twilio",
10        "crawl_depth": 0,
11        "crawl_period_min": 10080
12    }
13}'

Response

1{
2   "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3   "date_created": "2025-06-11T00:00:10Z",
4   "date_updated": "2025-06-11T00:00:10Z",
5   "description": "Web description",
6   "embedding_model": null,
7   "id": "aia_know_cccccccc-dddd-eeee-ffff-gggggggggggg",
8   "knowledge_source_details": {
9       "crawl_period_min": 10080,
10       "source": "https://en.wikipedia.org/wiki/Twilio"
11   },
12   "name": "Twilio web",
13   "status": "QUEUED",
14   "type": "Web",
15   "url": "https://knowledge.twilio.com/v1/Knowledge/aia_know_cccccccc-dddd-eeee-ffff-gggggggggggg"
16}

Step 2: Add a copilot tag

Create a key called tw_product.

1curl --location 'https://knowledge.twilio.com/v1/Knowledge/Tags' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Basic {Token}' \
4--data '{
5	"key": "tw_product",
6	"twilio_tag": true,
7       "allows_multiple": true
8}'

Response

1{
2   "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3   "allows_multiple": true,
4   "date_created": "2025-06-12T03:22:18Z",
5   "date_updated": "2025-06-12T03:22:18Z",
6   "id": "aia_tags_dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb",
7   "key": "tw_product",
8   "twilio_tag": true,
9   "url": "https://knowledge.twilio.com/v1/Tags/aia_tags_dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb"
10}

Use the id generated from the previous step to set your tag_id and set the tag value to copilot.

1curl --location 'https://knowledge.twilio.com/v1/Knowledge/aia_know_cccccccc-dddd-eeee-ffff-gggggggggggg/Tags' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Basic {Token}' \
4--data '{
5	"value": "copilot",
6       "tag_id": "{{tag_id_from_above_step}}",
7       "enabled": true
8}'

Response

1{
2   "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3   "date_created": "2025-06-11T00:11:54Z",
4   "date_updated": "2025-06-11T00:11:54Z",
5   "enabled": true,
6   "id": "aia_tgvl_eeeeeeee-ffff-aaaa-bbbb-cccccccccccc",
7   "resource_id": "aia_know_cccccccc-dddd-eeee-ffff-gggggggggggg",
8   "resource_type": "knowledge",
9   "tag_id": "aia_tags_dddddddd-eeee-ffff-aaaa-bbbbbbbbbbbb",
10   "url": "https://knowledge.twilio.com/v1/Knowledge/aia_know_cccccccc-dddd-eeee-ffff-gggggggggggg/Tags",
11   "value": "copilot"
12}

Step 3: Check upload status

When you create a knowledge source, Twilio processes it so Agent Copilot can start using it. Knowledge sources can take a few minutes to upload and reach completed.

To check on the status, use the following command. The upload status can be queued, processing, completed, or failed. Make sure to wait until the upload is completed before you test Agent Copilot.

1curl --location 'https://knowledge.twilio.com/v1/knowledges/aia_know_ffffffff-aaaa-bbbb-cccc-dddddddddddd/status' \
2--header 'Authorization: Basic {Token}'

Response

1{
2   "account_sid": null,
3   "date_updated": "2025-06-12T15:40:48Z",
4   "last_status": null,
5   "status": "COMPLETED"
6}

Step 4: Turn on queues for Agent Copilot

To test how Agent Copilot is using your knowledge sources, you must have queues enabled first. To enable queues:

In Twilio Console, go to Flex > AI features > Agent Copilot.
Under Access control settings, select Only selected queues or All queues.
You can select up to 25 queues for Only selected queues. If you need more queues, you must select All queues.
Click Save access control settings.

Limits

You can select up to 25 queues for Only selected queues. If you need more queues, you must select All queues.