Why it matters
Variables allow you to insert accurate, dynamic data into messages, agent instructions, and automations. Understanding each variable type ensures Whippy pulls the correct data at send time and reduces errors caused by missing fields or incorrect associations.
Key Concepts
Variable: A dynamic placeholder that resolves to real data when a message or instruction is generated.
Core Variable: A built-in variable mapped directly to standard Whippy contact fields, such as name, email, or phone number.
Timestamp Variable: A system-generated variable that inserts the current date and time using a selected timezone.
Custom Data: The actual dataset from an external system such as an integration or API. This data contains real records and exists outside of Whippy’s core contact fields. This is the data itself, eg. employee custom data would actually hold the employee record with the individual’s names, phones etc.
Custom Object: The definition of the structure for custom data, including its fields (properties) and associations. It does not contain actual records. For example, an employee custom object would define that the employee has x y z fields(properties) and a b c associations.
Custom Variable: A single property pulled from custom data and referenced using the custom. prefix.
Association: A defined relationship between a Whippy contact and a custom object, or between one custom object and another custom object.
Repeat Variable: A user-defined variable that applies filters to multiple related records and repeats content based on those conditions. Used for Agents Instructions.
Historic Variable: A variable that references historical data, such as prior conversation context. Used in agent instructions.
Step-by-Step: Variable Types in Whippy
Identify where the data lives (core contact data, custom data, or history).
Select the appropriate variable type.
Insert the variable using the correct syntax.
Verify associations, filters, and limits.
Test to confirm the variable resolves as expected.
Core Variables
Core variables reference standard fields stored directly on a Whippy contact.
Common examples include:
First Name
Last Name
Phone Number (10 digits)
Email
Area Code (3 digits)
Prefix and Line Number (7 digits)
Birth Date
Example
Hi {{first_name}}, we will contact you at {{phone_number}}.Core variables are populated through imports, manual updates, synced integrations, or the API.
Timestamp Variables
Timestamp variables insert the current date and time when the message is generated.
They are system-generated and respect the timezone selected in the variable picker.
Example
This message was sent on {{Current_time_America/Chicago}}.Always select the correct timezone to avoid unexpected timestamps.
Custom Data and Custom Variables
Custom data represents actual records pulled from external systems such as integrations or APIs. A custom object defines the structure of that data, while custom data holds the records themselves.
Custom variables reference individual properties from custom data and always use the custom. prefix.
When a custom variable is associated with a Whippy contact, it must include the associated Whippy resource at the end of the variable.
Example
{{custom.candidate_id.job_title:contact}}In this example:
candidate_idcomes from a custom object definition.job_titleis a property on the custom data record.:contactindicates the data is associated with the Whippy contact.
Custom variables cannot exist without custom data as their source.
Associations
Associations define how records relate to each other.
They can exist:
Between a Whippy contact and a custom object.
Between one custom object and another custom object.
Associations allow Whippy to determine which custom data records belong to a specific contact.
Example
A contact is associated with one employee record (1:1) or multiple job records (1:n). These associations determine which records variables resolve against.
Repeat Variables
Repeat variables allow you to loop over multiple related records that meet defined conditions.
Key characteristics:
Filters are applied to associated custom data.
A limit can be set, up to 10 records.
Commonly used in agent instructions and advanced workflows.
Example
{{@repeat current_jobs}} - {{custom.job_id.title}} {{/repeat}}Within repeat blocks, custom variables omit the :contact suffix. This distinction exists to differentiate repeat-context custom variables from standard custom variables.
Whippy repeats the enclosed content once for each matching record, up to the defined limit.
Historic Variables
Historic variables reference past data instead of current contact fields.
They are primarily used to give agents context during message generation.
Example
{{conversation_history}}This variable inserts previous conversation context from the thread so agents can reference prior interactions.
Tips and Best Practices
Confirm variables match existing fields or custom data properties.
Verify associations before using custom or repeat variables.
Use clear filters and limits on repeat variables to control output.
Select the correct timezone for timestamp variables.
Test messages and agent instructions before enabling them in live workflows.
Troubleshooting
Issue | Possible Cause | Fix |
Variable appears blank | Field has no data | Populate the field on the contact or source data |
Custom variable not resolving | Incorrect or missing association | Verify associations between records |
Repeat variable returns unexpected records | Filters are too broad | Refine filters and adjust limits |
Timestamp shows incorrect time | Wrong timezone selected | Reinsert the variable and select the correct timezone |
Setting up the conditions for the Repeat Variable
When you click “Advanced Filter”
Agent Instructions using a Repeat Variable: example
