Ada
App · 21 actions
Manage Ada knowledge sources, articles, tags, end-user profiles and glossary terms.
Actions
| Action | What it does |
|---|---|
| Create a glossary term | Create a glossary term. |
| Create end user | Create end user. |
| Create knowledge source | Create knowledge source. |
| Create or update knowledge articles | Create or update knowledge articles. |
| Create or update knowledge tags | Create or update knowledge tags. |
| Delete a glossary term | Delete a glossary term. |
| Delete knowledge article | Delete knowledge article. |
| Delete knowledge source | Delete knowledge source. |
| Delete knowledge tag | Delete knowledge tag. |
| Get a glossary term | Get a glossary term. |
| Get end user | Get end user. |
| Get knowledge article | Get knowledge article. |
| List end users | List end users. |
| List glossary terms | List glossary terms. |
| List knowledge articles | List knowledge articles. |
| List knowledge sources | List knowledge sources. |
| List knowledge tags | List knowledge tags. |
| Sync knowledge source | Re-crawl a web-import knowledge source in the background. |
| Update a glossary term | Update a glossary term. |
| Update end user | Update end user. |
| Update knowledge source | Update knowledge source. |
Create a glossary term
Create a glossary term.
Inputs
- External id
external_idtextRequired - Your own identifier for the term, unique within the AI Agent
- Translation mode
translation_modetext - `custom` restates detected `user_terms` using `ai_agent_terms`; `default` only surfaces the definition. Defaults to `default`.One of:
default,custom. Default:default. - User terms
user_termslist - The wordings a customer might use, per language
- Ai agent terms
ai_agent_termslist - The wordings the AI Agent should use, per language
- Voice detection enabled
voice_detection_enabledtrue/false - Improve how reliably the term is recognized in speech. Requires a voice platform on the AI Agent. Defaults to false.Default:
false. - Definition
definitiontext - A business definition of the term, shown to the AI Agent
- Voice pronunciations
voice_pronunciationslist - Phonetic respellings the AI Agent speaks in place of the written form on voice calls; omit or send null for none
- Availability rules
availability_rulesobject - The structured rule gating when this term applies; omit or send null for no rule, and an unknown variable id or a malformed rule is rejected with a 400
Outputs
dataobject- A glossary term: a word or phrase the AI Agent should recognize and, in `custom` mode, restate using your preferred wording
Example output
{
"data": {
"ai_agent_terms": [],
"availability_rules": {
"conditions": [],
"match": "all"
},
"definition": "example",
"external_id": "example",
"id": "example",
"translation_mode": "default",
"user_terms": [],
"voice_detection_enabled": false,
"voice_pronunciations": []
}
}Create end user
Create end user.
Inputs
- External id
external_idtext - Optional caller-supplied identifier (for example a CRM contact ID or a phone number). Maximum 36 characters; must not contain characters. Values are stored case-insensitively. If an end user with this external_id already exists, that existing user is returned with HTTP 200 (idempotent upsert); otherwise a new end user is created with HTTP 201. Available for custom channel integrations only (V1).
- Profile
profileobject - The end user's profile information. Optional: omitting profile creates a blank end user.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"created_at": "example",
"end_user_id": "example",
"external_id": "example",
"profile": {
"avatar": "example",
"display_name": "example",
"email": "example",
"first_name": "example",
"language": "example",
"last_name": "example",
"metadata": {},
"system_properties": {
"sunshine_user_id": "example"
}
},
"updated_at": "example"
}
}Create knowledge source
Create knowledge source.
Inputs
- Id
idtextRequired - A unique identifier for the knowledge source
- Name
nametextRequired - The name of the knowledge source
- Metadata
metadataobject - A dictionary of arbitrary key,value pairs. This data is not used by Ada, but can be used by the client to store additional information about the knowledge source.
- Availability rules
availability_rulesobject - An availability-rule template for the source. Each new article created under the source whose request omits `availability_rules` gets it. Set it here so the first import is covered. Omit or send `null` for no template. A source that an App creates then gets the rules set on its connection. See [Availability rules](/reference/introduction/availability-rules) for the schema and examples.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"availability_rules": {
"conditions": [],
"match": "all"
},
"created": "example",
"external_id": "example",
"id": "example",
"last_sync": "example",
"metadata": {},
"name": "example",
"status": "deleting",
"sync_schedule": {
"days": [],
"hours": [],
"timezone": "example"
},
"updated": "example"
}
}Create or update knowledge articles
Create or update knowledge articles.
Inputs
- Items
itemslistRequired - Items.
Outputs
datalist- Returned value.
Example output
{
"data": []
}Create or update knowledge tags
Create or update knowledge tags.
Inputs
- Items
itemslistRequired - A list of tags
Outputs
datalist- Returned value.
Example output
{
"data": []
}Delete a glossary term
Delete a glossary term.
Inputs
- Glossary term id
glossary_term_idtextRequired - The id of the glossary term
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Delete knowledge article
Delete knowledge article.
Inputs
- Id
idtextRequired - The id of the article to delete
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Delete knowledge source
Delete knowledge source.
Inputs
- Id
idtextRequired - id of the knowledge source to delete
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Delete knowledge tag
Delete knowledge tag.
Inputs
- Id
idtextRequired - The id of the article tag to delete
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Get a glossary term
Get a glossary term.
Inputs
- Glossary term id
glossary_term_idtextRequired - The id of the glossary term
Outputs
dataobject- A glossary term: a word or phrase the AI Agent should recognize and, in `custom` mode, restate using your preferred wording
Example output
{
"data": {
"ai_agent_terms": [],
"availability_rules": {
"conditions": [],
"match": "all"
},
"definition": "example",
"external_id": "example",
"id": "example",
"translation_mode": "default",
"user_terms": [],
"voice_detection_enabled": false,
"voice_pronunciations": []
}
}Get end user
Get end user.
Inputs
- End user id
end_user_idtextRequired - The Ada end_user_id
Outputs
dataobject- Returned value.
Example output
{
"data": {
"created_at": "example",
"end_user_id": "example",
"external_id": "example",
"profile": {
"avatar": "example",
"display_name": "example",
"email": "example",
"first_name": "example",
"language": "example",
"last_name": "example",
"metadata": {},
"system_properties": {
"sunshine_user_id": "example"
}
},
"updated_at": "example"
}
}Get knowledge article
Get knowledge article.
Inputs
- Id
idtextRequired - The id of the article to retrieve
Outputs
dataobject- Returned value.
Example output
{
"data": {
"availability_rules": {
"conditions": [],
"match": "all"
},
"content": "example",
"created": "example",
"enabled": false,
"external_created": "example",
"external_updated": "example",
"id": "example",
"knowledge_source_id": "example",
"language": "ar",
"metadata": {},
"name": "example",
"tag_ids": [],
"updated": "example",
"url": "example"
}
}List end users
List end users. Returns one page; use its continuation fields to request the next page.
Inputs
- Cursor
cursortext - The ID that marks the start or beginning of the returned records
- Limit
limitnumber - The number of records to returnFrom 1 to 100.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"data": [],
"meta": {
"next_page_url": "example"
}
}
}List glossary terms
List glossary terms. Returns one page; use its continuation fields to request the next page.
Inputs
- Cursor
cursortext - The id that marks the start of the returned records. Use the value from `meta.next_page_url` in the previous response.
- Limit
limitnumber - The number of records to returnFrom 1 to 100.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"data": [],
"meta": {
"next_page_url": "example"
}
}
}List knowledge articles
List knowledge articles. Returns one page; use its continuation fields to request the next page.
Inputs
- Cursor
cursortext - The article cursor that marks the start or beginning of the returned article records
- Limit
limitnumber - The number of article records to returnFrom 1 to 100.
- Id
idlist - Filter by article id
- Enabled
enabledlist - Filter by enabled status
- Language
languagelist - Filter by language
- Knowledge source
knowledge_source_idlist - Filter by knowledge source
- Tag ids
tag_idslist - Filter by tag ids
Outputs
dataobject- Returned value.
Example output
{
"data": {
"data": [],
"meta": {
"next_page_url": "example"
}
}
}List knowledge sources
List knowledge sources.
Inputs
None.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"data": []
}
}List knowledge tags
List knowledge tags.
Inputs
None.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"data": []
}
}Sync knowledge source
Re-crawl a web-import knowledge source in the background. Only web-import sources support this action, at most once every four hours.
Inputs
- Id
idtextRequired - id of the knowledge source to sync
Outputs
dataobject- Returned value.
Example output
{
"data": {}
}Update a glossary term
Update a glossary term.
Inputs
- Glossary term id
glossary_term_idtextRequired - The id of the glossary term
- External id
external_idtext - Rename the term's identifier. Rejected with 409 if another term in the AI Agent already uses it.
- Translation mode
translation_modetext - `custom` restates detected `user_terms` using `ai_agent_terms`; `default` only surfaces the definition.One of:
default,custom. - User terms
user_termslist - Replaces the existing list. Send `null` to clear it; omit to leave it unchanged.
- Ai agent terms
ai_agent_termslist - Replaces the existing list. Send `null` to clear it; omit to leave it unchanged.
- Voice detection enabled
voice_detection_enabledtrue/false - Whether the term is passed to the voice agent to improve how reliably it is recognized in speech.
- Definition
definitiontext - Send `null` to clear it; omit to leave it unchanged
- Voice pronunciations
voice_pronunciationslist - Replaces the existing list, send null to clear it, or omit to leave it unchanged
- Availability rules
availability_rulesobject - Omit to leave the current rule unchanged, send null to clear it, or send a rule to replace it; an unknown variable id or a malformed rule is rejected with a 400
Outputs
dataobject- A glossary term: a word or phrase the AI Agent should recognize and, in `custom` mode, restate using your preferred wording
Example output
{
"data": {
"ai_agent_terms": [],
"availability_rules": {
"conditions": [],
"match": "all"
},
"definition": "example",
"external_id": "example",
"id": "example",
"translation_mode": "default",
"user_terms": [],
"voice_detection_enabled": false,
"voice_pronunciations": []
}
}Update end user
Update end user.
Inputs
- End user id
end_user_idtextRequired - The Ada end_user_id
- External id
external_idtext - Set or update the external identifier for this end user. Pass null to remove the current external_id. Must be unique per AI Agent; maximum 36 characters; must not contain characters. Values are stored case-insensitively. Returns 409 if the external_id is already assigned to a different end user. Available for custom channel integrations only (V1).
- Profile
profileobjectRequired - The end user's profile information
Outputs
dataobject- Returned value.
Example output
{
"data": {
"created_at": "example",
"end_user_id": "example",
"external_id": "example",
"profile": {
"avatar": "example",
"display_name": "example",
"email": "example",
"first_name": "example",
"language": "example",
"last_name": "example",
"metadata": {},
"system_properties": {
"sunshine_user_id": "example"
}
},
"updated_at": "example"
}
}Update knowledge source
Update knowledge source.
Inputs
- Id
idtextRequired - id of the knowledge source to update
- External id
external_idtext - A unique identifier for the knowledge source
- Name
nametext - The name of the knowledge source
- Metadata
metadataobject - A dictionary of arbitrary key,value pairs. This data is not used by Ada, but can be used by the client to store additional information about the knowledge source.
- Sync frequency
sync_frequencytext - Deprecated. Send `sync_schedule` instead. The server translates a frequency into a schedule: `daily` syncs every day. `weekly` keeps the source's days when it has 1 to 6 of them, or else syncs on one weekday. Both keep the hours and the timezone the source already has; a source without hours gets 23:00 UTC. `never` syncs only on request and discards the hours and timezone. `sync_schedule` wins when both are sent.One of:
daily,weekly,never. - Sync schedule
sync_scheduleobject - When the website import syncs. Replaces the whole schedule: hours, days and timezone. Wins over `sync_frequency` when both are sent. Website imports only.
- Availability rules
availability_rulesobject - Replace the source's availability-rule template. Articles created after the change get the new template. Existing articles keep their own rules. Send `null` to remove the template. Omit to leave it unchanged.
Outputs
dataobject- Returned value.
Example output
{
"data": {
"availability_rules": {
"conditions": [],
"match": "all"
},
"created": "example",
"external_id": "example",
"id": "example",
"last_sync": "example",
"metadata": {},
"name": "example",
"status": "deleting",
"sync_schedule": {
"days": [],
"hours": [],
"timezone": "example"
},
"updated": "example"
}
}