# Add Assessments to a Template

## Overview

Welkin Health enables you to embed assessments (forms) directly into Message Templates, allowing organizations to send communications to patients that include interactive assessments they can complete. This functionality makes it easy for patients to complete health evaluations, check-ins, and surveys directly from communication channels without requiring them to log into a separate portal.

To add assessments to a Message Template, you'll use Patient Facing Assessment (PFA) Folders as the vehicle for delivery. Assessments are grouped in PFA Folders, which are then embedded as links in Message Templates.

## Key Concepts

* **Message Template** – Communication content (Email or SMS) sent to patients
* **PFA Folder** – Container holding one or more assessments with branding options
* **Assessment/Form** – The actual questionnaire or form patients complete
* **Embedded Link** – Unique URL included in message that takes patient to assessment

## Prerequisites

Before adding assessments to a Message Template, ensure:

1. **Assessment(s) Created** – Forms are already created in Visual Components > Forms
2. **PFA Folder Created** – You've grouped assessments in a PFA Folder with branding
3. **Message Template Access** – You have permissions to create/edit Message Templates
4. **Team Permissions** – Appropriate roles can send messages to patients

For guides on creating these components, see:

* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template.md)
* [Create Patient Facing Assessment (PFA) Folders](/designer/documents-and-assessments/create-pfa-folders.md)

## Step-by-Step: Add Assessments to a Message Template

### Step 1: Create or Access a Message Template

1. Log into Designer
2. Click **Create Draft** to start a new configuration draft
3. Navigate to **Message Template** in the left sidebar
4. Either:
   * Click **+ New** to create a new message template, OR
   * Click on an existing template to edit it

### Step 2: Compose the Message Body

Write the main message content that will be sent to patients:

1. In the message body editor, compose your communication
2. Include context about why they're being asked to complete the assessment
3. Provide any necessary instructions or background

**Example message:**

```
Hello {first_name},

As part of your ongoing care, we'd like to check in on how you're feeling.
Please take 5-10 minutes to complete the following health assessment.
Your responses help us provide you with better care.

Click the link below to get started:
[ASSESSMENT LINK WILL GO HERE]

Thank you,
Your Care Team
```

### Step 3: Insert the Assessment/PFA Link

#### Option 1: Using PFA Variable (Recommended)

1. Position your cursor in the message where the link should appear
2. Click the **Variable** button or **{}** icon (usually above message body)
3. A variables drawer opens on the right
4. Look for **PFA Links** or **Patient Facing Assessments**
5. Select the **PFA Folder** you want to embed
6. The variable is inserted into your message:

   ```
   {{pfa_link_quarterly_assessment}}
   ```

The variable will automatically be replaced with the unique PFA link when the message is sent to each patient.

#### Option 2: Manual PFA Folder Selection (Alternative)

1. Below or near the message body, look for **Assessment Settings** or **Attachments**
2. Click **+ Add Assessment** or **Link Assessment**
3. From the list of available PFA Folders, select the one you want
4. The system may automatically insert a variable or provide you with a link to add

### Step 4: Add Additional Context (Optional)

After inserting the assessment link, you may want to add:

1. **Completion Instructions** – "Please complete by \[date]"
2. **What to Expect** – "You'll be asked \[number] of questions"
3. **Support Info** – "If you have questions, contact us at \[phone/email]"
4. **Reminder** – "This assessment will take approximately \[X] minutes"

**Example enhanced message:**

```
Hello {first_name},

As part of your ongoing care, we'd like to check in on how you're feeling.
Please take 5-10 minutes to complete the following health assessment.
Your responses help us provide you with better care.

Click the link below to get started:
{{pfa_link_quarterly_assessment}}

You'll be asked about your current symptoms and overall health.
Your responses are confidential and will be reviewed by your care team.

Please complete by {date_one_week_from_now}.

Questions? Contact us at (555) 123-4567.

Thank you,
Your Care Team
```

### Step 5: Configure Message Delivery Settings

1. **Delivery Method** – Choose Email or SMS
   * Email: Can include longer text and formatted content
   * SMS: Limited to 160 characters (multiple messages if needed)
2. **Sender** – Determine who the message comes from
   * Your organization name
   * A specific care team member
   * A general clinic inbox
3. **Timing** (if using automation)
   * Immediate send
   * Scheduled for specific date/time
   * Triggered by patient event

### Step 6: Preview the Message

1. Click **Preview** to see how the message appears to patients
2. Verify:
   * Message text is clear and professional
   * Assessment link is visible
   * Formatting looks good (especially if using Email)
   * Link works properly
3. For Email: Preview both desktop and mobile views
4. For SMS: Verify character count and message breaks

### Step 7: Save and Test

1. Click **Save** to save the Message Template
2. If part of automation, configure trigger and conditions
3. **Test before publishing:**
   * Send test message to yourself or team member
   * Click the assessment link in the actual message
   * Verify assessment appears correctly
   * Complete a test assessment to confirm data is captured
   * Check that responses appear in patient profile

### Step 8: Publish

1. Review all settings one final time
2. Click **Publish** to make the Message Template available
3. Template is now available for:
   * Manual sending by care team members
   * Automated sending via automations
   * Multi-use across multiple patient communications

## Using Assessments in Different Message Types

### Patient Check-in Messages

**Purpose:** Regular health status updates

**Message Template Example:**

```
Hi {patient_first_name},

It's time for your monthly check-in. Please let us know how you've been doing
by completing the assessment below.

{{pfa_link_monthly_check_in}}

Takes about 5 minutes. Thank you!
```

### Post-Visit Assessments

**Purpose:** Follow-up after appointments or encounters

**Message Template Example:**

```
Thank you for your visit on {visit_date}.

To help us provide better care, please complete this brief assessment:

{{pfa_link_post_visit_feedback}}

Your feedback is valuable and helps us improve our services.
```

### Program Enrollment Assessments

**Purpose:** Baseline assessment when enrolling in new care program

**Message Template Example:**

```
Welcome to the {program_name} program!

To get started, we need to gather some baseline information.
Please complete this assessment:

{{pfa_link_program_enrollment}}

This helps us understand your current health status and create a personalized care plan.
```

### Medication Management Assessments

**Purpose:** Monitor medication adherence and side effects

**Message Template Example:**

```
Hi {patient_first_name},

Please help us monitor how your {medication_name} is working by
completing this brief assessment:

{{pfa_link_medication_adherence}}

Your responses help us ensure the medication is helping you and not causing problems.
```

## Automating Assessment Delivery

### Using Message Templates with Automations

To automatically send Message Templates containing assessments:

1. Create an automation (see [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations.md))
2. Set **Trigger Event** (e.g., "Program Enrollment", "Date Milestone Reached", "Assessment Completed")
3. Set **Conditions** (e.g., "Patient in Diabetes Program")
4. Set **Action** to "Send Message"
5. Select your Message Template containing the assessment
6. Configure timing (immediate, delayed, etc.)
7. Publish the automation

**Example Automation:**

```
Trigger: Patient enrolled in Diabetes Management program
Condition: Patient age > 18
Action: Send Message Template "Diabetes Program Welcome"
Timing: Immediately upon enrollment
```

When this automation fires, patients receive the welcome message with the embedded assessment link.

## Best Practices

1. **Clear Instructions** – Explain why the assessment is important and what to expect
2. **Appropriate Timing** – Don't overwhelm patients with too many assessments
   * Space assessments at least 2-4 weeks apart
   * Align with care plan schedule
3. **Mobile-Friendly** – Ensure assessment link works on mobile phones
4. **Character Limits** – For SMS, keep message short; link should be prominent
5. **Branding** – Ensure PFA Folder uses your organization's logos and colors
6. **Completion Reminders** – Consider follow-up messages if patient doesn't complete
7. **Thank You Messages** – Send confirmation after completion
8. **Data Utilization** – Review assessment responses and use them to inform care decisions
9. **Privacy Assurance** – Mention data privacy/confidentiality in message if appropriate
10. **Test Thoroughly** – Always test message and assessment link with actual patients before broader rollout

## Troubleshooting

### PFA Link Not Appearing in Message

**Problem:** PFA variable shows instead of link or link is missing

**Solutions:**

* Verify PFA Folder is published in Designer
* Confirm you selected the correct PFA Folder when inserting variable
* Check that message template is published
* Refresh Designer and try inserting variable again

### Assessment Not Loading When Patient Clicks Link

**Problem:** Patient clicks link but gets error or blank page

**Solutions:**

* Verify PFA Folder is published
* Check that assessments in the folder are published
* Test link in different browser
* Clear browser cache and retry
* Verify patient has permission to access the assessment

### Link Expires Before Patient Completes

**Problem:** Patient tries to access assessment after some time and gets error

**Solutions:**

* Check PFA Folder expiration settings (should be "Never" or "30+ days" for most use cases)
* Resend link if it has expired
* Consider shortening time allowed before completion
* Set reminder automation to send before expiration

### Message Not Being Sent

**Problem:** Automation or manual send doesn't deliver message with assessment

**Solutions:**

* Verify Message Template is published
* Check patient has valid email address (for Email) or phone (for SMS)
* Verify automation trigger conditions are met
* Check system logs for delivery failures
* Confirm user has permission to send messages

## Related Topics

* [How to Create an Assessment or Form Template](/designer/documents-and-assessments/how-to-create-an-assessment-or-form-template.md) – Creating forms
* [Create Patient Facing Assessment (PFA) Folders](/designer/documents-and-assessments/create-pfa-folders.md) – Creating PFA containers
* [Designer: How to Create Automations](/designer/automations/designer-how-to-create-automations.md) – Automating message delivery
* [Filtering With Message Template Variables](/designer/documents-and-assessments/filtering-message-template-variables.md) – Advanced message personalization
* [Automations that Trigger Outbound Communications](/designer/automations/automations-that-trigger-outbound-communications.md) – Message automations


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/designer/documents-and-assessments/how-to-add-assessments-to-a-template.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.