Skip to main content

​
Overview

Tuco AI lets you send highly personalized messages at scale by combining:
  • Static templates you design.
  • Dynamic data from leads and external systems.
This page focuses on recommended patterns for:
  • Template structure and variable usage.
  • Personalization safety.
  • Testing and operational practices.
It does not depend on any internal APIs—only on behavior visible via the app and documented endpoints.

​
Template Concepts

Think of a Tuco message as:
  • A base template:
    • Static text and optional placeholders (variables).
  • Data bindings:
    • Lead fields (first name, company, role, etc.).
    • Custom fields from your systems.
The lead placeholders Tuco resolves for you:
  • {firstName}
  • {lastName}
  • {companyName}
  • {email}
  • {phone}
  • {jobTitle}
  • {notes} — the free-text notes saved on the lead
Anything extra your CSV or CRM brought in is stored as a custom field, and goes in by its column name:
You do not have to type these from memory. In the message editor, click Insert variable to see every custom field in your workspace — both the ones synced from HubSpot or LeadConnector and the ones your CSV imports created. Picking one inserts the exact token, which matters when a column name has odd spacing or capitalisation.
Custom-field names are matched case-insensitively and surrounding whitespace is ignored, so {cf:Industry}, {cf:industry} and {CF:Industry} all resolve against a column named Industry. Give every one a fallback anyway:
A placeholder Tuco does not recognise is replaced with nothing, not left in the message. If you invent {role}, the send goes out with a gap where you expected a word. Preview a template before you launch it.

​
Variable Replacement Behavior (Conceptual)

When a message is generated for a particular lead:
  1. Tuco reads the template text.
  2. For each placeholder:
    • Looks up the corresponding value on the lead or context object.
  3. If a value is:
    • Present: it replaces the placeholder.
    • Missing: it may produce an empty string or a fallback value, depending on your pattern.
To avoid awkward messages:
  • Always design templates with optional content in mind.
  • Use patterns that still read well if some fields are missing.

​
Safe Template Patterns

​
1. Optional Fields with Natural Defaults

Instead of:
“Hi {firstName} {lastName}, I saw you work at {companyName} in {cf:Franchise Region}.”
Prefer:
“Hi {firstName}, I saw you work at {companyName}.”
Where:
  • {firstName} is likely to be present (or you fall back to a neutral greeting).
  • {companyName} is often available and safe to include.
  • {cf:Franchise Region} may be omitted entirely to avoid:
    • “in ” with nothing after it.

​
2. Guarding Optional Sections Upstream

If your application generates templates programmatically:
  • Only inject optional phrases if the underlying data exists.
For example (pseudo-code in your own system):
This ensures that if companyName is missing, the resulting message still reads naturally.

​
Personalization Sources

​
Lead Fields

Base personalization can use:
  • Lead’s:
    • First name / last name.
    • Company name.
    • Email and phone.
    • Job title.
    • Notes — free text your team keeps on the lead.
    • Custom fields you define.
These fields are available in Tuco once you:
  • Import leads via CSV/CRM.
  • Create them via the Leads API.

​
External Systems

If you integrate Tuco with external systems (e.g. CRM, CDP):
  • Your backend can:
    • Fetch additional context per lead.
    • Build final message bodies incorporating that data before calling Tuco.
In this model:
  • Tuco receives the fully rendered message.
  • Tuco still handles delivery, limits, and tracking.

​
Template Testing Best Practices

​
Static Testing

Before using a template in production:
  • Test it with:
    • Complete data.
    • Missing optional fields.
    • Edge cases (short names, unusual characters).
Have reviewers read:
  • Actual example messages generated from real or realistic test contacts.

​
In-App Previews

If the Tuco UI or your custom UI supports it:
  • Use preview features to see:
    • How a template renders for a specific lead.
    • How segments of leads might see different variations.

​
Staging Templates

Use non-production workspaces:
  • Run small test sends against test contacts.
  • Confirm:
    • Messages look correct on actual devices.
    • Personalization behaves as expected.

​
Compliance & Content Quality

While message content is up to you, for best results:
  • Clarity and brevity:
    • Keep messages focused and concise.
    • Avoid overloading templates with too many dynamic inserts.
  • Tone:
    • Ensure tone aligns with your brand and use case.
    • Avoid language that could be misinterpreted when partial data is missing.
  • Consent:
    • Only message recipients who have given appropriate consent.
    • For more on consent and opt-outs, see /features/compliance-and-optouts.

​
Operational Considerations

​
Versioning Templates

In your own systems:
  • Keep track of:
    • Template versions.
    • Which sends or workflows used which versions.
This helps when:
  • Comparing performance across iterations.
  • Investigating issues tied to specific content changes.

​
Rollbacks

Have a plan for:
  • Rolling back to a previous template version quickly if:
    • A personalization bug is discovered.
    • A compliance issue is identified.
Use:
  • Feature flags or config toggles to switch templates without redeploying code.

​
Summary

By treating message templates as:
  • Carefully designed base texts, and
  • Composed with safe personalization patterns,
you can:
  • Deliver highly relevant outreach at scale.
  • Avoid awkward, malformed messages.
  • Maintain enterprise-grade standards for testing, governance, and compliance—all while leveraging Tuco AI’s delivery, limits, and tracking capabilities.