> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting custom values in workflows

> Fix custom values that are not populating correctly in HoopAI platform workflow messages, including merge field syntax, missing data, fallback values, and formatting.

Custom values (merge fields) let you personalize workflow messages with contact-specific data. When they fail to populate, contacts receive messages with blank spaces or raw placeholder text. This guide helps you fix the most common issues.

***

## Incorrect merge field syntax

The most frequent cause of custom values not rendering is a syntax error in the merge field tag.

| Issue           | Incorrect                  | Correct                  |
| --------------- | -------------------------- | ------------------------ |
| Missing braces  | `{contact.first_name}`     | `{{contact.first_name}}` |
| Extra spaces    | `{{ contact.first_name }}` | `{{contact.first_name}}` |
| Wrong field key | `{{contact.firstname}}`    | `{{contact.first_name}}` |
| Typo in object  | `{{contct.first_name}}`    | `{{contact.first_name}}` |

<Tip>
  Always insert custom values using the **Custom Values** button in the message editor rather than typing them manually. This ensures the correct syntax and field key are used every time.
</Tip>

***

## Missing contact data

If the syntax is correct but the value still appears blank, the contact record may not have data in the referenced field.

<Steps>
  <Step title="Check the contact record">
    Open the contact in **Contacts** and verify the field you are referencing has a value. For example, if your message uses `{{contact.company_name}}`, confirm the Company Name field is populated.
  </Step>

  <Step title="Review the data source">
    If leads come from a form or integration, confirm the form field is mapped to the correct CRM field. An unmapped field will leave the contact record empty.
  </Step>

  <Step title="Check for timing issues">
    If your workflow updates a field in one step and references it in the next step, add a short wait (30 seconds to 1 minute) between the steps. The field update may not complete before the message is sent.
  </Step>
</Steps>

***

## Setting fallback values

Fallback values ensure your messages still read naturally when a custom value is empty.

You can configure a fallback value by using the format:

```
{{contact.first_name,fallback=there}}
```

This renders as the contact's first name if available, or "there" if the field is empty. For example, "Hi `{{contact.first_name,fallback=there}}`" becomes "Hi Sarah" or "Hi there."

<Warning>
  Not all custom value fields support the fallback syntax. Test your fallback values by sending a test message to a contact with the field intentionally left blank.
</Warning>

***

## Date and time formatting

Date and time custom values can produce unexpected results if the format does not match your audience's expectations.

* **Default format**: Dates render in the format configured under **Settings > Business Info > Date Format**
* **Timezone**: Appointment times render in the timezone set for the account, not the contact's local timezone
* **Relative dates**: Custom values like `{{appointment.start_date}}` return the absolute date, not relative phrasing like "tomorrow"

<Note>
  If appointment times appear off by several hours, check that your account timezone under **Settings > Business Info** matches the timezone where your appointments occur.
</Note>

***

## Nested and complex custom values

Some custom values reference nested objects or related records. These require specific formatting.

| Custom value type | Example syntax                   |
| ----------------- | -------------------------------- |
| Contact field     | `{{contact.email}}`              |
| Appointment field | `{{appointment.start_date}}`     |
| Opportunity field | `{{opportunity.monetary_value}}` |
| Custom field      | `{{contact.custom_field_key}}`   |
| Trigger data      | `{{trigger.form_name}}`          |

<Steps>
  <Step title="Find the correct field key">
    Open the **Custom Values** picker in the workflow message editor. Hover over a value to see its full key. Use this exact key in your message.
  </Step>

  <Step title="Verify the data exists in context">
    Nested values like `{{appointment.start_date}}` only work in workflows triggered by appointment-related events. Using an appointment custom value in a form submission workflow will return blank.
  </Step>
</Steps>

***

## Testing custom value output

Always test your messages before activating a workflow to catch custom value issues early.

<Steps>
  <Step title="Use the test action feature">
    In the workflow builder, click the **Test** button on the message step. Select a contact with complete data to see how the message will render.
  </Step>

  <Step title="Send a test to yourself">
    Create a test contact with your own email and phone number. Enroll the test contact in the workflow and verify the message arrives with all values populated.
  </Step>

  <Step title="Test with missing data">
    Repeat the test with a contact that has missing fields. Confirm that fallback values render correctly and the message does not contain blank spaces or broken syntax.
  </Step>
</Steps>

***

## FAQs

<AccordionGroup>
  <Accordion title="Why does my custom value show the raw placeholder text like {{contact.first_name}}?">
    This typically means the merge field syntax is incorrect or the field key does not exist. Delete the placeholder and re-insert it using the Custom Values picker in the message editor.
  </Accordion>

  <Accordion title="Can I use custom values in email subject lines?">
    Yes. Custom values work in email subject lines, preview text, and body content. The same syntax and fallback rules apply.
  </Accordion>

  <Accordion title="Do custom values work in SMS and MMS messages?">
    Yes. Custom values are supported in SMS and MMS workflow messages. Keep in mind that long custom value output (such as full addresses) can push your message over the SMS character limit, causing it to split into multiple segments.
  </Accordion>
</AccordionGroup>