Ada

App · 21 actions

Manage Ada knowledge sources, articles, tags, end-user profiles and glossary terms.

Actions

ActionWhat it does
Create a glossary termCreate a glossary term.
Create end userCreate end user.
Create knowledge sourceCreate knowledge source.
Create or update knowledge articlesCreate or update knowledge articles.
Create or update knowledge tagsCreate or update knowledge tags.
Delete a glossary termDelete a glossary term.
Delete knowledge articleDelete knowledge article.
Delete knowledge sourceDelete knowledge source.
Delete knowledge tagDelete knowledge tag.
Get a glossary termGet a glossary term.
Get end userGet end user.
Get knowledge articleGet knowledge article.
List end usersList end users.
List glossary termsList glossary terms.
List knowledge articlesList knowledge articles.
List knowledge sourcesList knowledge sources.
List knowledge tagsList knowledge tags.
Sync knowledge sourceRe-crawl a web-import knowledge source in the background.
Update a glossary termUpdate a glossary term.
Update end userUpdate end user.
Update knowledge sourceUpdate knowledge source.

Create a glossary term

Create a glossary term.

Inputs

External idexternal_idtextRequired
Your own identifier for the term, unique within the AI Agent
Translation modetranslation_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 termsuser_termslist
The wordings a customer might use, per language
Ai agent termsai_agent_termslist
The wordings the AI Agent should use, per language
Voice detection enabledvoice_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.
Definitiondefinitiontext
A business definition of the term, shown to the AI Agent
Voice pronunciationsvoice_pronunciationslist
Phonetic respellings the AI Agent speaks in place of the written form on voice calls; omit or send null for none
Availability rulesavailability_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 idexternal_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).
Profileprofileobject
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

IdidtextRequired
A unique identifier for the knowledge source
NamenametextRequired
The name of the knowledge source
Metadatametadataobject
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 rulesavailability_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

ItemsitemslistRequired
Items.

Outputs

datalist
Returned value.
Example output
{
  "data": []
}

Create or update knowledge tags

Create or update knowledge tags.

Inputs

ItemsitemslistRequired
A list of tags

Outputs

datalist
Returned value.
Example output
{
  "data": []
}

Delete a glossary term

Delete a glossary term.

Inputs

Glossary term idglossary_term_idtextRequired
The id of the glossary term

Outputs

dataobject
Returned value.
Example output
{
  "data": {}
}

Delete knowledge article

Delete knowledge article.

Inputs

IdidtextRequired
The id of the article to delete

Outputs

dataobject
Returned value.
Example output
{
  "data": {}
}

Delete knowledge source

Delete knowledge source.

Inputs

IdidtextRequired
id of the knowledge source to delete

Outputs

dataobject
Returned value.
Example output
{
  "data": {}
}

Delete knowledge tag

Delete knowledge tag.

Inputs

IdidtextRequired
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 idglossary_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 idend_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

IdidtextRequired
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

Cursorcursortext
The ID that marks the start or beginning of the returned records
Limitlimitnumber
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

Cursorcursortext
The id that marks the start of the returned records. Use the value from `meta.next_page_url` in the previous response.
Limitlimitnumber
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

Cursorcursortext
The article cursor that marks the start or beginning of the returned article records
Limitlimitnumber
The number of article records to returnFrom 1 to 100.
Ididlist
Filter by article id
Enabledenabledlist
Filter by enabled status
Languagelanguagelist
Filter by language
Knowledge sourceknowledge_source_idlist
Filter by knowledge source
Tag idstag_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

IdidtextRequired
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 idglossary_term_idtextRequired
The id of the glossary term
External idexternal_idtext
Rename the term's identifier. Rejected with 409 if another term in the AI Agent already uses it.
Translation modetranslation_modetext
`custom` restates detected `user_terms` using `ai_agent_terms`; `default` only surfaces the definition.One of: default, custom.
User termsuser_termslist
Replaces the existing list. Send `null` to clear it; omit to leave it unchanged.
Ai agent termsai_agent_termslist
Replaces the existing list. Send `null` to clear it; omit to leave it unchanged.
Voice detection enabledvoice_detection_enabledtrue/false
Whether the term is passed to the voice agent to improve how reliably it is recognized in speech.
Definitiondefinitiontext
Send `null` to clear it; omit to leave it unchanged
Voice pronunciationsvoice_pronunciationslist
Replaces the existing list, send null to clear it, or omit to leave it unchanged
Availability rulesavailability_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 idend_user_idtextRequired
The Ada end_user_id
External idexternal_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).
ProfileprofileobjectRequired
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

IdidtextRequired
id of the knowledge source to update
External idexternal_idtext
A unique identifier for the knowledge source
Namenametext
The name of the knowledge source
Metadatametadataobject
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 frequencysync_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 schedulesync_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 rulesavailability_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"
  }
}

On this page