Merge tags let you insert dynamic, personalized content into your messages and templates. By using merge tags, you can automatically include names, dates, case details, and other record-specific information so every recipient receives a relevant, customized message.

### Overview

Merge tags are placeholder tokens (such as `[ClientName]` or `[EventDate]`) that eCourtDate replaces with actual data when a message is sent. They work across all messaging features, including one-off messages, bulk actions, auto messages, flows, agency phone/email auto-responses, and portal templates. Merge tags support multilingual content and eliminate the need to manually personalize each message.

You can use merge tags in the following areas:

- **One-off messages**: Merge tags pull data from the record where the message is created (for example, sending from the Event screen uses that event's data)
- **Bulk Action** messages
- **Auto messages**
- **Flow** messages
- **Agency Phones** inbound auto-response text and calls
- **Agency Emails** inbound auto-response
- **Portals** multilingual content and add-to-calendar templates

### How-To Steps

#### Insert a Merge Tag into a Message

1. Open the message template or compose window where you want to add a merge tag.
2. Place your cursor at the position where you want the dynamic content to appear.
3. Enter the merge tag using the bracket syntax, for example: `[ClientFirstName]`.
4. Save or send the message. eCourtDate will replace the merge tag with the actual value at delivery time.

#### Use Conditional Text with Merge Tags

To include text only when a merge tag has a value, use the `%%` syntax:

- `[%Case ID% CaseNumber]` outputs "Case ID 12345" only if a case number exists
- `[%Attorney Name% AttorneyName]` outputs "Attorney Name Jane Smith" only if an attorney is assigned
- `[%Website% AgencyWebsite]` outputs "Website example.com" only if the agency website is configured

If the merge tag has no value, the entire block (including the label text) is removed from the message.

#### What Happens When a Merge Tag Has No Value

When there is no data for a merge tag, eCourtDate removes the merge tag from the message entirely. For example, if you use `[AgencyWebsite]` but your agency does not have the **Agency Website** setting configured in **Admin** > **Settings**, the tag is removed from the output.

### Merge Tag Reference

#### Agency Merge Tags

Configure these values in **Admin** > **Settings**.

| Merge Tag | Description |
|-----------|-------------|
| `[AgencyName]` | Your agency name |
| `[AgencyReference]` | Your agency reference ID |
| `[AgencyPhone]` | Your agency phone number |
| `[AgencyEmail]` | Your agency email address |
| `[AgencyWebsite]` | Your agency website URL |
| `[AgencyAddress]` | Your agency physical address |
| `[TimeZone]` | Your agency time zone |
| `[BusinessHours]` | Formatted business hours |
| `[BusinessFromTime]` | Business hours start time |
| `[BusinessToTime]` | Business hours end time |
| `[BusinessDays]` | Days your agency is open |
| `[NextBusinessDay]` | The next business day |

#### Date Merge Tags

These merge tags are based on when the message is created.

| Merge Tag | Description |
|-----------|-------------|
| `[DateToday]` | Today's date |
| `[DateTomorrow]` | Tomorrow's date |
| `[DateYesterday]` | Yesterday's date |
| `[Date12Hours]` | Date and time 12 hours from now |
| `[DateNextWeek]` | Date one week from today |
| `[DateNow]` | Current date and time |
| `[TimeNow]` | Current time |

For example, if you send a one-off message with a 5-minute delay at 9:00 AM, `[TimeNow]` will output "09:00 AM" (the time the message was created), not "09:05 AM."

#### Random Merge Tags

Use these to generate random strings and numbers.

| Merge Tag | Description |
|-----------|-------------|
| `[RandomTag]` | Up to 10 alphanumeric characters |
| `[RandomNumbers]` | Up to 10 random numbers |

**Pro tip**: The duplication prevention feature auto-blocks duplicate messages with the same content within a 30-minute window. To intentionally send duplicate messages (such as when testing), add `[RandomTag]` at the beginning of the message template.

#### Schedule Merge Tags

Use these to output current and upcoming schedule information.

| Merge Tag | Description |
|-----------|-------------|
| `[CurrentSchedule]` | The current schedule |
| `[CurrentSchedules]` | All current schedules |
| `[UpcomingSchedules]` | Upcoming schedules |

#### Client Merge Tags

Use these with any associated client records.

| Merge Tag | Description |
|-----------|-------------|
| `[ClientName]` | Client display name |
| `[ClientFullName]` | Client full name |
| `[ClientFirstName]` | Client first name |
| `[ClientMiddleName]` | Client middle name |
| `[ClientLastName]` | Client last name |
| `[ClientInitials]` | Client initials |
| `[ClientReference]` | Client reference ID |
| `[ClientGroup]` | Client group |
| `[ClientType]` | Client type |
| `[ClientStatus]` | Client status |
| `[ClientLanguage]` | Client preferred language |
| `[ClientAge]` | Client age |
| `[ClientDOB]` | Client date of birth |

#### Assigned User Merge Tags

Use these when a client is assigned to a specific staff member.

| Merge Tag | Description |
|-----------|-------------|
| `[AssignedUserName]` | Assigned staff member's name |
| `[AssignedUserPhone]` | Assigned staff member's phone |
| `[AssignedUserEmail]` | Assigned staff member's email |

#### Contact Merge Tags

Use these with any associated contact records.

| Merge Tag | Description |
|-----------|-------------|
| `[ContactName]` | Contact name (uses client name if not different) |
| `[ContactValue]` | Formatted phone number or email address |
| `[ContactChannel]` | Channel type: email, text, or voice |
| `[ContactType]` | Contact type |

#### Event Merge Tags

Use these with any associated event records.

| Merge Tag | Description |
|-----------|-------------|
| `[EventDate]` | Event date |
| `[EventTime]` | Event time |
| `[EventDateTime]` | Event date and time |
| `[EventReference]` | Event reference ID |
| `[EventDescription]` | Event description |
| `[EventStatus]` | Event status |
| `[EventType]` | Event type |
| `[EventURL]` | Event URL (do not use to link to Portals) |
| `[LocationNotes]` | Event location notes (event-level field, does not require linking to a location) |
| `[EventsCount]` | Number of non-archived, non-trashed future events |

#### Next Event Merge Tags

Use these for a client with multiple events. The system uses the first upcoming event unless you link a specific event.

| Merge Tag | Description |
|-----------|-------------|
| `[NextEventDateTime]` | Next event date and time |
| `[NextEventDate]` | Next event date |
| `[NextEventTime]` | Next event time |
| `[NextEventLocation]` | Next event location |
| `[NextEventLocationName]` | Next event location name |
| `[NextEventLocationFullAddress]` | Next event location full address |
| `[NextEventLocationPhone]` | Next event location phone number |
| `[NextEventLocationWebsite]` | Next event location website |
| `[NextEventCaseNumber]` | Next event case number |
| `[NextEventAttorney]` | Next event attorney name |

#### Case Merge Tags

Use these with any associated case records.

| Merge Tag | Description |
|-----------|-------------|
| `[CaseNumber]` | Case number |
| `[CaseStatus]` | Case status |
| `[CaseCodes]` | Case codes |
| `[CaseDescription]` | Case description |
| `[CaseConditions]` | Case conditions |
| `[OffenseDate]` | Offense date |
| `[OffenseDescription]` | Offense description |
| `[OffenseNumber]` | Offense number |
| `[FileDate]` | File date |
| `[ArrestDate]` | Arrest date |
| `[JudgmentDate]` | Judgment date |
| `[ArrestTracking]` | Arrest tracking number |
| `[ArrestingAgency]` | Arresting agency name |
| `[VictimName]` | Victim name |
| `[OffenderName]` | Offender name |
| `[WarrantStatus]` | Warrant status |

#### Attorney Merge Tags

Use these when an attorney is assigned to a case.

| Merge Tag | Description |
|-----------|-------------|
| `[AttorneyName]` | Attorney name |
| `[AttorneyPhone]` | Attorney phone number |
| `[AttorneyEmail]` | Attorney email address |
| `[AttorneyBarNumber]` | Attorney bar number |

#### Location Merge Tags

Use these when a location is linked to an event or payment.

| Merge Tag | Description |
|-----------|-------------|
| `[Location]` | Location display name |
| `[LocationName]` | Location name |
| `[LocationFullAddress]` | Full formatted address |
| `[LocationAddress]` | Street address line 1 |
| `[LocationAddress2]` | Street address line 2 |
| `[LocationCity]` | City |
| `[LocationCounty]` | County |
| `[LocationState]` | State |
| `[LocationZip]` | ZIP code |
| `[LocationLink]` | Location link (map URL) |
| `[LocationPhone]` | Location phone number |
| `[LocationEmail]` | Location email address |
| `[LocationWebsite]` | Location website |
| `[LocationDescription]` | Location description |
| `[LocationLat]` | Latitude |
| `[LocationLng]` | Longitude |
| `[LocationPlaceId]` | Google Place ID |

#### Payment Merge Tags

Use these for any payment-related messages.

| Merge Tag | Description |
|-----------|-------------|
| `[PaymentAmount]` | Payment amount |
| `[PaymentDueDate]` | Payment due date |
| `[PaymentIssueDate]` | Payment issue date |
| `[PaymentNotes]` | Payment notes |
| `[PaymentDescription]` | Payment description |
| `[PaymentStatus]` | Payment status |
| `[PaymentType]` | Payment type |
| `[PaymentReference]` | Payment reference ID |
| `[PaymentLink]` | Payment link URL |
| `[PaymentCitation]` | Payment citation |

#### Transaction Merge Tags

Use these for payment transaction messages.

| Merge Tag | Description |
|-----------|-------------|
| `[TransactionDateTime]` | Transaction date and time |
| `[TransactionReference]` | Transaction reference ID |
| `[TransactionAmount]` | Transaction amount |
| `[TransactionStatus]` | Transaction status |

### Best Practices

- Test your merge tags by sending a preview message to yourself before sending to recipients. This confirms that all tags resolve correctly.
- Use the conditional `%%` syntax to avoid awkward blank spaces when a merge tag has no value (for example, `[%Case ID:% CaseNumber]`).
- Include only the merge tags that are relevant to your message type. Using event merge tags in a payment message will result in empty values.
- Keep your agency settings (name, phone, email, website) up to date in **Admin** > **Settings** so agency merge tags always display current information.
- Document which merge tags your templates use so your team can ensure the required data fields are populated in uploads and records.

### Frequently Asked Questions

**Q: What happens if a merge tag has no matching data?**
A: The merge tag is removed from the message entirely. The recipient will not see the bracket text or any placeholder. Use the `%%` conditional syntax to also remove surrounding label text when a value is missing.

**Q: Can I use merge tags in email subject lines?**
A: Yes. Merge tags work in both the subject line and body of email messages. For example, you can use `[ClientFirstName], your upcoming hearing` as an email subject.

**Q: Do merge tags work with multilingual templates?**
A: Yes. Merge tags resolve to the same data values regardless of the template language. The dynamic values (names, dates, case numbers) are inserted into whichever language version of the template is sent to the recipient.

**Q: Can I create custom merge tags?**
A: No. Merge tags are predefined by eCourtDate and correspond to specific data fields in the system. You cannot create custom merge tags, but you can use the available tags in combination to achieve the messaging you need.

**Q: Why is my merge tag showing the bracket text instead of the actual value?**
A: This usually means the merge tag is misspelled or the associated record does not have data for that field. Double-check the exact tag name (including capitalization) against the reference tables above. Also verify that the record (client, event, case) has the relevant data populated.

### Troubleshooting

**Issue:** Merge tags appear as plain text in sent messages.
**Symptoms:** Recipients see `[ClientName]` or `[EventDate]` literally in the message instead of the actual values.
**Solution:** Verify the merge tag spelling matches the reference table exactly, including capitalization. Ensure brackets are standard square brackets `[ ]` and not special characters copied from a word processor.

**Issue:** Conditional text blocks are not being removed when the value is empty.
**Symptoms:** You see labels like "Case ID" or "Attorney Name" in the message even when there is no corresponding data.
**Solution:** Confirm you are using the correct `%%` syntax: `[%Label Text% MergeTagName]`. The percent signs must wrap only the label text, and the merge tag name must follow after a space.

### Related Articles

- [How to Create an Auto Message](/how-to-create-an-auto-message)
- [How to Upload a Flat File](/how-to-upload-a-flat-file)
- [How to Manage Clients](/how-to-manage-clients)