Skip to main content

​
What are AI actions?

AI actions bring the power of large language models directly into your HoopAI workflows. Instead of relying solely on static templates and fixed logic, you can insert an AI-powered step that reads contact data, generates intelligent responses, and feeds its output into every subsequent action in your workflow. Whether you need to draft a personalized follow-up email, score a lead based on conversation history, or generate dynamic content for an SMS, AI actions make it possible without writing a single line of code.
AI actions consume AI credits from your HoopAI plan. Monitor your usage in Settings > AI credits to avoid unexpected overages.

​
How AI actions work

At a high level, an AI action is a workflow step that sends a prompt to an AI model and stores the response as a custom value you can reference later. The flow looks like this:
  1. A trigger fires (form submission, tag applied, appointment booked, etc.)
  2. The workflow reaches the AI action step
  3. HoopAI assembles the prompt using your template and any merge fields
  4. The AI model processes the prompt and returns a response
  5. The response is stored and available to all downstream steps
This means you can use AI output in emails, SMS messages, internal notifications, if/else branches, webhooks, and more.

​
Setting up your first AI action

1

Open the workflow editor

Navigate to Automation > Workflows and either create a new workflow or open an existing one. Add a trigger if you haven’t already.
2

Add the AI action step

Click the + button to add a new action. Search for AI in the action list and select GPT-Powered AI Action. Drag it to the desired position in your workflow.
3

Configure the model

In the action settings panel, choose the AI model you want to use. HoopAI supports multiple model options with different speed and quality trade-offs. For most business use cases, the default model provides the best balance.
4

Write your prompt

Enter the instructions the AI should follow. Be specific about the desired output format, tone, and length. Use merge fields (covered below) to inject contact-specific data.
5

Set the response variable

Give the AI response a custom variable name such as ai_response or lead_score. This variable becomes available to every action that follows in the workflow.
6

Test and activate

Use the Test button to preview the AI output with sample contact data. Once you are satisfied with the results, activate the workflow.

​
Passing contact data via merge fields

Merge fields are the bridge between your contact records and the AI prompt. They allow the AI to personalize its output based on real data.

​
Commonly used merge fields

Merge fieldDescription
{{contact.first_name}}Contact’s first name
{{contact.last_name}}Contact’s last name
{{contact.email}}Contact’s email address
{{contact.phone}}Contact’s phone number
{{contact.source}}How the contact was acquired
{{contact.tags}}All tags assigned to the contact
{{contact.notes}}Notes attached to the contact record
{{contact.custom_field.field_name}}Any custom field value

​
Example prompt with merge fields

You are a friendly sales assistant for a home services company.

The following lead just submitted a form:
- Name: {{contact.first_name}} {{contact.last_name}}
- Service requested: {{contact.custom_field.service_type}}
- Budget: {{contact.custom_field.budget_range}}
- Notes: {{contact.notes}}

Write a short, personalized follow-up email (under 150 words) that:
1. Thanks them by first name
2. Acknowledges the specific service they need
3. Suggests a next step (booking a call or site visit)

Use a warm, professional tone. Do not use placeholder text.
The more context you provide in your prompt, the better the AI output will be. Include relevant custom field data, conversation history, and specific formatting instructions. For advanced prompting strategies, see prompt engineering best practices.

​
Using AI output in subsequent steps

Once the AI action runs, its output is stored in the variable you defined. You can reference this variable in any downstream action.

​
In email or SMS actions

Insert the AI response variable directly into your message body: 
Hi {{contact.first_name}},

{{ai_response}}

Best regards,
The Team

​
In if/else conditions

Use the AI output to branch your workflow logic. For example, if the AI returns a numeric lead score, you can route high-scoring leads to your sales team and low-scoring leads to a nurture sequence.

​
In webhook actions

Pass the AI-generated content to external systems via webhook payloads. This is useful for updating CRMs, triggering third-party automations, or logging AI decisions.

​
In update contact actions

Store the AI output directly on the contact record by mapping the response variable to a custom field. This creates a permanent record of the AI’s analysis.

​
Practical examples

Goal: Send a personalized follow-up email within minutes of a form submission.Setup:
  • Trigger: Form submitted
  • Step 1: Wait 5 minutes
  • Step 2: AI action — prompt the AI to draft a follow-up email based on the form responses stored in custom fields
  • Step 3: Send email using the AI response as the body
Why it works: Every lead receives a message that feels hand-written and addresses their specific needs, even at 2 AM on a Sunday.
Goal: Automatically score incoming leads so your sales team focuses on the best opportunities.Setup:
  • Trigger: Contact created
  • Step 1: AI action — provide the AI with the contact’s source, form responses, and any available conversation history; instruct it to return a score from 1 to 10 with a brief justification
  • Step 2: Update contact — store the score in a custom field
  • Step 3: If/else — if score is 7 or above, notify sales team; otherwise, add to nurture sequence
Why it works: The AI considers multiple data points simultaneously and provides consistent, explainable scoring that would take a human minutes per lead.
Goal: Customize marketing messages based on the contact’s industry, role, and past interactions.Setup:
  • Trigger: Tag applied (e.g., “interested_in_demo”)
  • Step 1: AI action — prompt the AI to generate a demo invitation message tailored to the contact’s industry and company size
  • Step 2: Send SMS or email with the AI-generated content
Why it works: Instead of one-size-fits-all templates, each contact receives messaging that speaks directly to their context. A restaurant owner gets different messaging than a dental practice.
Goal: Give your sales team a pre-call brief generated by AI before each appointment.Setup:
  • Trigger: Appointment booked
  • Step 1: AI action — compile all known data about the contact (source, conversations, form responses, tags) and ask the AI to generate a brief summary with suggested talking points
  • Step 2: Internal notification — send the AI brief to the assigned team member
Why it works: Your team walks into every call prepared, with relevant context and suggested approaches based on everything HoopAI knows about the contact.

​
Prompt writing tips for workflow AI

Writing effective prompts for workflow AI actions differs from conversational AI. Here are key guidelines:

​
Be explicit about format

Tell the AI exactly what format you need. If you want a numeric score, say “Return only a number from 1 to 10.” If you want an email, specify “Write a complete email with subject line and body.”

​
Set length constraints

Workflow outputs often feed into SMS (160 characters) or email snippets. Always specify maximum length: “Keep your response under 100 words” or “Write exactly 2 sentences.”

​
Define the persona

Tell the AI who it is: “You are a professional customer service representative for a plumbing company.” This ensures consistent tone across all automated messages.

​
Handle edge cases

Consider what happens when merge fields are empty. Add instructions like: “If the service type is not provided, ask about their general needs instead.”

​
Use system-level instructions

When available, separate your system instructions (role, rules, constraints) from the user-level content (contact data, specific request). This produces more reliable outputs.
Always review AI-generated content before enabling a workflow for production use. Test with diverse contact data to ensure the AI handles edge cases gracefully. Inappropriate or inaccurate AI responses can damage customer relationships.

​
Monitoring and optimization

After your AI-powered workflow is live, keep an eye on these metrics:
  • AI credit usage — track consumption in Settings to manage costs
  • Response quality — periodically review AI outputs by checking contact records or internal notifications
  • Workflow completion rate — ensure the AI step isn’t causing errors or timeouts
  • Conversion metrics — compare AI-personalized messaging against your previous static templates

​
Troubleshooting common issues

IssueSolution
AI response is too longAdd explicit length constraints to your prompt
Output contains placeholder textAdd “Do not use placeholder or example text” to your prompt
Merge fields show as raw textVerify the merge field syntax and that the contact has data in those fields
Workflow times outSimplify your prompt or switch to a faster model
Inconsistent toneAdd a detailed persona description and example phrases to your prompt

​
Combining AI actions with other workflow features

AI actions become even more powerful when combined with other HoopAI workflow capabilities:
  • Wait actions — add delays between AI steps to avoid overwhelming contacts
  • If/else branches — route contacts based on AI analysis results
  • Webhooks — send AI outputs to external tools and dashboards
  • Math operations — combine AI scores with other numeric values
  • Loops — process multiple data points through AI iteratively
For more on combining AI with decision-making logic, see the AI Decision Maker action.

​
Next steps

AI Decision Maker

Route contacts intelligently using natural language conditions.

AI agents + workflows

Connect AI agents to workflows for end-to-end automation.

Workflow examples

Ready-to-use recipes combining AI with automation.

Prompt engineering

Master the art of writing effective AI prompts.
Last modified on March 5, 2026