Create Engagement

Log calls, emails, meetings, notes, and tasks to HubSpot records - create engagement records programmatically. Common uses:

Log external calls to HubSpot
Create notes from AI analysis
Schedule follow-up tasks
Record meetings from other systems
Track email outreach

Action type: hubspot.v2.create_engagement

What This Does (The Simple Version)

Think of this like adding an entry to someone’s activity log. When your team calls, emails, or meets with someone, HubSpot tracks it as an “engagement”. This action creates those engagement records from your workflows. Real-world example: After an AI analyzes a deal and generates insights, you want to log those insights as a note on the deal. This action creates a note engagement with the AI’s analysis, visible in HubSpot’s timeline.

How It Works

This action creates engagement records (calls, emails, meetings, notes, tasks) in HubSpot. You specify:

Engagement type (call, email, meeting, note, task)
Content (body/description of the engagement)
Who/what it’s about (associated contact, deal, company)
Additional details (title, duration, status, etc.)

The engagement appears in HubSpot on the associated record’s timeline.

Setting It Up

Step 1: Choose Engagement Type

Select which type of engagement to create:

Note - Add notes/comments
Call - Log phone calls
Email - Record email communications
Meeting - Log meetings
Task - Create tasks

Choose from dropdown: Engagement Type

Step 2: Add Content (Required)

In the “Content/Body” field, enter the main content. This is the description/body of the engagement. You can:

Type directly
Click {} to insert variables
Mix text and variables

Examples: For notes:

AI Analysis: [insert deal_insights variable]

For calls:

Discussed [deal name] with [contact first name]. Next steps: [next actions]

For tasks:

Follow up on deal [deal name] - review proposal and schedule demo

Step 3: Add Title/Subject (Optional)

In the “Title/Subject” field, add a title. Different engagement types use this differently:

Note: Note title
Call: Call title
Email: Email subject
Meeting: Meeting title
Task: Task subject

Example:

Discovery Call - [company_name]

Step 4: Add Associations (Required)

In the “Associations” field, specify which records this engagement relates to. Format: One per line: object_type:object_id Example:

contact:[contact_id]
deal:[deal_record.id]
company:[company_id]

Common patterns: Associate with contact from lookup:

contact:[contact_data.id]

Associate with deal from search:

deal:[current_deal.hs_object_id]

Associate with multiple:

contact:[contact_id]
deal:[deal_id]

Step 5: Add Type-Specific Details (Optional)

Depending on engagement type, additional fields appear: For calls:

Duration: Call length in minutes (e.g., 30)
Status: Call outcome (e.g., Connected, No Answer, Left Voicemail)

For meetings:

Duration: Meeting length in minutes (e.g., 60)
Status: Meeting outcome (e.g., Scheduled, Completed, Rescheduled)

For tasks:

Status: Task status (e.g., NOT_STARTED, IN_PROGRESS, COMPLETED)
Priority: Task priority (e.g., HIGH, MEDIUM, LOW)

For emails:

Status: Email status (e.g., SENT, SCHEDULED)

Step 6: Additional Properties (Optional)

In the “Additional Properties” field, add custom engagement properties. Format: Key-value pairs, one per line:

property_name=value
another_property=another_value

Or JSON:

{
  "custom_field": "value",
  "another_field": "[variable]"
}

Step 7: Name Output Variable

In the “Output Variable Name” field, name the created engagement. Good names:

created_note
logged_call
scheduled_task
meeting_record

Default: created_engagement

What You Get Back

The action returns the created engagement record. Example output saved to created_note:

{
  "id": "123456789",
  "engagement_type": "note",
  "properties": {
    "hs_note_body": "AI Analysis: Deal shows strong engagement...",
    "hs_note_title": "Deal Health Analysis",
    "hs_timestamp": "2025-01-15T14:30:00Z",
    "hs_created_at": "2025-01-15T14:30:00Z"
  },
  "createdAt": "2025-01-15T14:30:00Z",
  "updatedAt": "2025-01-15T14:30:00Z"
}

What’s included:

id - Engagement ID
engagement_type - Type you created
properties - Engagement properties
createdAt - When created

Common Workflows

Log AI Insights as Notes

Goal: Create notes with AI analysis results

Lookup HubSpot Object (V2)
- Get deal
- Output Variable: deal_record
Get Timeline Events (V2)
- Get deal history
- Output Variable: deal_timeline
Invoke LLM
- Prompt: “Analyze [deal_record] and [deal_timeline]”
- Output Variable: insights
Create Engagement (V2)
- Engagement Type: Note
- Content/Body: Click {} → insights
- Title/Subject: “AI Deal Analysis”
- Associations: deal:[deal_record.id]
- Output Variable: analysis_note

Log External Calls

Goal: Record calls from external phone system

Webhook receives:
- contact_id
- call_duration
- call_notes
- call_outcome
Create Engagement (V2)
- Engagement Type: Call
- Content/Body: Click {} → call_notes
- Title/Subject: Type “Outbound Sales Call”
- Duration: Click {} → call_duration
- Status: Click {} → call_outcome
- Associations: contact:[contact_id]

Create Follow-Up Tasks

Goal: Create tasks after enrichment

Search HubSpot (V2)
- Find high-priority leads
- Output Variable: priority_leads
For Loop
- Loop through: priority_leads
- Current item: current_lead
Create Engagement (V2) (inside loop)
- Engagement Type: Task
- Content/Body: Type “Review enrichment data and reach out to ” then click {} → current_lead → properties → firstname
- Title/Subject: “Follow-up: High Priority Lead”
- Status: NOT_STARTED
- Priority: HIGH
- Associations: contact:[current_lead.hs_object_id]
End Loop

Real Examples

Post-Analysis Note

Scenario: After AI analyzes deal health, log insights Configuration:

Engagement Type: Note
Content/Body: [deal_health_analysis]
Title/Subject: “Automated Health Check”
Associations: deal:[deal_id]

Result: Note appears on deal timeline with AI insights

External Call Logging

Scenario: Phone system sends webhook after calls Webhook payload:

{
  "contact_id": "123456",
  "duration_minutes": "15",
  "outcome": "Connected",
  "notes": "Discussed pricing, sending proposal"
}

Configuration:

Engagement Type: Call
Content/Body: [notes]
Title/Subject: “Sales Call”
Duration: [duration_minutes]
Status: [outcome]
Associations: contact:[contact_id]

Result: Call logged to contact with all details

Automated Task Creation

Scenario: Create task when deal reaches certain stage Trigger: Webhook when deal stage = “Decision Stage” Configuration:

Engagement Type: Task
Content/Body: “Review decision criteria with [contact_name] and address any concerns”
Title/Subject: “Decision Stage Follow-up”
Status: NOT_STARTED
Priority: HIGH
Associations: deal:[deal_id]\ncontact:[primary_contact_id]

Result: High-priority task created for sales rep

Troubleshooting

Missing Associations Error

“Associations are required” error Possible causes:

Associations field empty
Wrong format
Invalid object ID

How to fix:

Add at least one association: contact:[contact_id]
Use format: object_type:object_id (one per line)
Verify object IDs are valid HubSpot IDs
Check execution log for exact error

Engagement Not Appearing

Created but can’t find in HubSpot Possible causes:

Associated with wrong record
Looking at wrong record type
Timeline filter hiding it

How to fix:

Check associations - verify correct record ID
Check execution log - see which ID was used
In HubSpot timeline, clear filters
Search for engagement by ID in execution log

Duration Not Saving

Duration field ignored Possible causes:

Wrong format (needs minutes)
Non-numeric value
Only applies to calls/meetings

How to fix:

Use number of minutes: 30 not 30 minutes
Ensure numeric value: [duration] must resolve to number
Duration only works for calls and meetings

Status Invalid

Status value rejected Possible causes:

Invalid status for engagement type
Custom status not recognized

How to fix:

Use standard values:
- Calls: Connected, No Answer, Left Voicemail, Busy
- Meetings: Scheduled, Completed, Rescheduled, Canceled
- Tasks: NOT_STARTED, IN_PROGRESS, COMPLETED, WAITING, DEFERRED
- Emails: SENT, SCHEDULED, BOUNCED, FAILED
Check HubSpot settings for custom values

Tips & Best Practices

✅ Do:

Always include meaningful content/body
Associate with relevant records (contact, deal, company)
Use descriptive titles/subjects
Include duration for calls and meetings (helps reporting)
Set task priority for action items
Use variables to make content dynamic
Log AI insights as notes for context

❌ Don’t:

Create engagements without associations (required)
Leave content/body empty
Use invalid status values
Forget duration is in minutes (not seconds/hours)
Create duplicate engagements (check if exists first)
Log sensitive information in engagements

Performance tips:

Creating engagement takes ~1-2 seconds
No limit on engagements created
Bulk creation: use loops with rate limiting

Engagement type selection:

Notes: AI insights, analysis results, internal comments
Calls: Phone conversations (manual or from phone system)
Emails: Email outreach (if not using HubSpot email)
Meetings: Meeting records from external calendars
Tasks: Follow-up actions, reminders, to-dos

Before creating engagement:

Lookup HubSpot Object (V2) - Get record to associate
Search HubSpot (V2) - Find records to log engagements on

After creating engagement:

Get Engagements (V2) - Retrieve engagements later
Update HubSpot Object (V2) - Update associated record

Related actions:

Create Timeline Event (V2) - Custom timeline events (different from engagements)
For Loop - Create multiple engagements

Related workflows:

HubSpot Customer Onboarding - Uses engagements for context

Last Updated: 2025-10-01

Using Agent.ai

For Builders

Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Engagement Type

Step 2: Add Content (Required)

Step 3: Add Title/Subject (Optional)

Step 4: Add Associations (Required)

Step 5: Add Type-Specific Details (Optional)

Step 6: Additional Properties (Optional)

Step 7: Name Output Variable

What You Get Back

Common Workflows

Log AI Insights as Notes

Log External Calls

Create Follow-Up Tasks

Real Examples

Post-Analysis Note

External Call Logging

Automated Task Creation

Troubleshooting

Missing Associations Error

Engagement Not Appearing

Duration Not Saving

Status Invalid

Tips & Best Practices

Using Agent.ai

For Builders

Actions

​What This Does (The Simple Version)

​How It Works

​Setting It Up

​Step 1: Choose Engagement Type

​Step 2: Add Content (Required)

​Step 3: Add Title/Subject (Optional)

​Step 4: Add Associations (Required)

​Step 5: Add Type-Specific Details (Optional)

​Step 6: Additional Properties (Optional)

​Step 7: Name Output Variable

​What You Get Back

​Common Workflows

​Log AI Insights as Notes

​Log External Calls

​Create Follow-Up Tasks

​Real Examples

​Post-Analysis Note

​External Call Logging

​Automated Task Creation

​Troubleshooting

​Missing Associations Error

​Engagement Not Appearing

​Duration Not Saving

​Status Invalid

​Tips & Best Practices

​Related Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Engagement Type

Step 2: Add Content (Required)

Step 3: Add Title/Subject (Optional)

Step 4: Add Associations (Required)

Step 5: Add Type-Specific Details (Optional)

Step 6: Additional Properties (Optional)

Step 7: Name Output Variable

What You Get Back

Common Workflows

Log AI Insights as Notes

Log External Calls

Create Follow-Up Tasks

Real Examples

Post-Analysis Note

External Call Logging

Automated Task Creation

Troubleshooting

Missing Associations Error

Engagement Not Appearing

Duration Not Saving

Status Invalid

Tips & Best Practices

Related Actions