# Socotra Assistant Configuration



The [Socotra Assistant](/ai-guide/assistant/overview) can be configured through the top-level <ApiLink name="AssistantRef">AssistantRef</ApiLink> configuration object. This configuration allows the assistant to authenticate requests performed on behalf of a tenant and controls how inbound emails are routed to [tasks](/features/work-management/tasks) in the [email intake workflow](/ai-guide/assistant/email-intake).

Here's an example of an `AssistantRef` configuration:

```json
{
	"assistant": {
		"patTokenSecretRef": {
			"name": "SocotraAssistantPat",
			"key": "patToken"
		},
		"inquiryIntents": {
			"newQuoteIntake": {
				"intentType": "newQuote",
				"taskType": "newSubmission",
				"workgroup": "new-business-team"
			},
			"generalIntake": {
				"intentType": "unknown",
				"taskType": "emailIntake"
			}
		}
	}
}
```

Secrets [#secrets]

The `patTokenSecretRef` object references the static name of the <ApiLink name="SecretRef">SecretRef</ApiLink> configuration object containing the [personal access token](/features/security/personal-access-tokens) (PAT) used by the Socotra Assistant, and contains the following fields:

* `name` - The static name of the SecretRef object
* `key` - The name of the secret item containing the PAT

Secrets can be created by using the <ApiLink name="createSecret">Create a Secret</ApiLink> API endpoint. Once a secret is created, it must be added to a [resource group](/api/resources/resource-service) by using the <ApiLink name="createResourceGroup">Create a Resource Group</ApiLink> or <ApiLink name="updateResourceGroup">Update a Resource Group</ApiLink> API endpoint.

<Callout>
  Ensure secret configurations are deployed before using the Socotra Assistant.
</Callout>

Intent Plans [#intent-plans]

When the Socotra Assistant intercepts an inbound email, the assistant classifies the email into an intent and creates a [task](/features/work-management/tasks) using the matching intent plan. The `inquiryIntents` object maps intent plan names to intent plans.

Each intent plan contains the following fields:

* `intentType` - The intent handled by the plan. Supported values are `newQuote`, `policyChange`, `policyCancellation`, `policyReinstatement`, and `unknown`.
* `taskType` - The type of task that will be created for emails matching the intent. The value must match a task type defined in the <ApiLink name="WorkManagementRef">WorkManagementRef</ApiLink> configuration for your tenant.
* `workgroup` - An optional reference to the name of the [workgroup](/features/work-management/workgroups) used to auto-assign tasks created for the intent

Workgroup names must be between 1 and 128 characters, must start with a letter or digit, and can only contain letters, digits, periods, underscores, and hyphens.

Validation Rules [#validation-rules]

The following rules are enforced when an `AssistantRef` configuration is deployed:

* The `inquiryIntents` object must include exactly one intent plan with the `unknown` intent type. This plan acts as a fallback for emails that don't match any other intent.
* Each intent type can be used by at most one intent plan.
* Each `taskType` must match a task type defined in the <ApiLink name="WorkManagementRef">WorkManagementRef</ApiLink> configuration for your tenant.

See Also [#see-also]

* <ApiLink name="AssistantRef">
    AssistantRef
  </ApiLink>
* [Socotra Assistant Overview](/ai-guide/assistant/overview)
* [Email Intake Workflow](/ai-guide/assistant/email-intake)
* [Integrations Plugin](/configuration/plugins/integrations)
* [Tasks](/features/work-management/tasks)
* [Workgroups](/features/work-management/workgroups)
* [Configuration Deployment](/configuration/general-topics/deployment)