Description

n8n-nodes-tela

This is an n8n community node that provides seamless integration with the Tela API. It allows you to interact with Tela projects and canvases in your n8n workflows, enabling dynamic content generation and workflow automation.

!n8n.io – Workflow Automation

TL;DR

Don’t want to read? Import the sample workflow “Tela Canvas Execution with Dynamic Variables” to test this node with real Tela API integration.

What This Node Does

The Tela node enables you to:

• Execute Tela Canvases: Run AI-powered canvases with dynamic variables and get results
• Dynamic Variable Handling: Automatically detect and configure canvas variables
• File Upload Support: Handle file uploads for canvas processing
• Project Management: List and manage Tela projects and their canvases
• Workflow Integration: Seamlessly integrate Tela AI workflows into your n8n automation

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes
2. Select Install
3. Enter @meistrari/n8n-nodes-tela as the package name
4. Agree to the risks of using community nodes
5. Select Install

Manual Installation

For self-hosted n8n instances:

npm install @meistrari/n8n-nodes-tela

For Docker installations, follow the custom nodes guide.

Configuration

1. Create Tela API Credentials

1. Create a new credential of type “Tela API”
2. Enter your Tela API key (find this in your Tela dashboard)
3. Test the connection to verify it works

2. Configure the Node

1. Project: Select the project containing your canvas
2. Canvas: Choose the specific canvas to execute
3. Variables: Configure dynamic fields based on your canvas configuration

Operations

Execute Canvas

The main operation that runs your Tela canvas with the specified variables and returns the AI-generated results.

Parameters:

| Field | Type | Required | Description |
| —————— | ——- | ——– | ————————————————————————— |
| Project | Options | Yes | Select the project containing your canvas |
| Canvas | Options | Yes | Select the canvas to execute |
| Variables | Collection | No | Dynamic fields based on your canvas configuration |
| Async Execution | Boolean | No | When enabled, returns immediately with completion ID instead of waiting |

Use Cases:

• Generate dynamic content for emails
• Create personalized marketing materials
• Process documents with AI assistance
• Generate reports based on input data

Execute Workstation

Create a task in the Tela Workstation dashboard. Tasks are visible in the Tela web interface and can be reviewed, approved, or processed manually.

Parameters:

| Field | Type | Required | Description |
| ————- | ———- | ——– | ————————————————- |
| Project | Options | Yes | Select the project containing your canvas |
| Canvas | Options | Yes | Select the canvas to execute |
| Label | String | No | Optional label for the workstation task |
| Variables | Collection | No | Dynamic fields based on your canvas configuration |

Response:

• Returns the full API response object

Use Cases:

• Create tasks for human review in Tela dashboard
• Queue AI-generated content for approval workflows
• Build hybrid human-AI pipelines with manual checkpoints

Get Completion

Retrieve the result of an async canvas execution. Use this operation to poll for completion status when using async execution.

Parameters:

| Field | Type | Required | Description |
| —————- | —— | ——– | —————————————- |
| Completion ID | String | Yes | The ID returned from async execution |

Response:

• Returns the full API response object with id, status, and outputContent

Use Cases:

• Poll for long-running canvas executions
• Build async workflows with wait loops
• Handle high-latency AI processing without timeouts

Node Reference

Credentials

| Field | Description |
| ———– | ————————————- |
| API Key | Your Tela API key from your dashboard |

Parameters

| Field | Type | Required | Description |
| ————- | ———- | ——– | ————————————————- |
| Project | Options | Yes | Select the project containing your canvas |
| Canvas | Options | Yes | Select the canvas to execute |
| Variables | Collection | No | Dynamic fields based on your canvas configuration |

Usage Examples

Example 1: Basic Canvas Execution

Input Data:

{
  "customerName": "John Doe",
  "productType": "Premium Subscription",
  "monthlyAmount": 99.99
}

Canvas Variables:

• customer_name: John Doe
• product_type: Premium Subscription
• monthly_amount: 99.99

Result: AI-generated personalized content based on your canvas configuration.

Example 2: File Processing

Input Data:

{
  "document": "binaryfiledata",
  "processingType": "summarize"
}

Canvas Variables:

• document: [File upload]
• processing_type: summarize

Result: AI-processed document with summary or analysis.

Example 3: Dynamic Content Generation

Input Data:

{
  "industry": "Technology",
  "companySize": "100-500 employees",
  "challenge": "Digital transformation"
}

Canvas Variables:

• industry: Technology
• company_size: 100-500 employees
• challenge: Digital transformation

Result: Tailored content addressing specific business challenges.

Sample Workflows

Workflow 1: Automated Customer Onboarding

1. Webhook receives new customer signup
2. Tela generates personalized welcome email
3. Send Email delivers the generated content

Workflow 2: Document Processing Pipeline

1. File Upload receives document
2. Tela processes and analyzes document
3. Database stores processed results
4. Notification sends completion alert

Workflow 3: Marketing Campaign Generator

1. CRM provides customer segments
2. Tela generates personalized campaigns
3. Marketing Platform deploys campaigns
4. Analytics tracks performance

Advanced Features

Dynamic Variable Detection

The node automatically detects canvas variables and their types:

• Text variables: Standard string inputs
• File variables: Automatic file upload handling
• Required fields: Clearly marked in the interface

Smart File Handling

• Supports multiple file formats
• Automatic MIME type detection
• Secure file upload to Tela servers
• Binary data processing from n8n workflows

Load Options

• Projects: Dynamically loads available projects
• Canvases: Loads canvases based on selected project
• Variables: Auto-populates variable fields based on canvas

Compatibility

• n8n Version: 0.174.0 or later
• Node.js: 18.0.0 or later
• npm: 8.0.0 or later
• Platforms: n8n Cloud, Self-hosted instances

Troubleshooting

Common Issues

1. API Key Invalid

– Verify your Tela API key is correct
– Check if the key has expired
– Ensure proper permissions

2. Project Not Loading

– Verify API key has access to projects
– Check Tela API status
– Refresh credentials

3. Canvas Execution Fails
– Verify all required variables are set
– Check canvas configuration in Tela
– Review API response for error details

Error Messages

• Failed to load projects: Check API key and permissions
• Failed to load canvases: Verify project ID and access
• Failed to execute canvas: Review variable configuration

Resources

• n8n Community Nodes Documentation
• Tela API Documentation
• n8n Workflow Automation
• Community Support

Support

Getting Help

• GitHub Issues: Report bugs and request features
• n8n Community: Ask questions in the community
• Documentation: Check the comprehensive docs

Development

Local Development

Clone the repository
git clone https://github.com/meistrari/n8n-nodes-tela.git
cd n8n-nodes-tela
Install dependencies
npm install
Build the project
npm run build
Link locally for testing
npm link

Testing

Run tests
npm test
Build and test
npm run build && npm test

Changelog

Version 1.5.0

Improved Binary File Handling

#### Improvements

• Uses n8n’s official helper: Now uses helpers.getBinaryDataBuffer() instead of directly accessing binary data, which works correctly in all n8n storage modes (memory, filesystem, S3)
• Any variable can receive files: Removed type validation – binary files can now be sent to any canvas variable, not just file type variables. Tela will automatically parse text content from files when needed
• Simplified binary detection: Cleaner logic with 3 clear cases:

1. String with binary field name (e.g., "data")
2. Binary object passed directly (e.g., {{ $binary.data }})
3. Fallback to first available binary when value is empty

• Removed unnecessary API call: No longer fetches canvas variable definitions just to check types

#### Migration Guide

No breaking changes – all existing workflows continue to work. The only difference is:

• Variables with type: text can now receive binary files (previously only type: file variables could)

Version 1.4.0

BREAKING CHANGE: Simplified API Response Handling

All operations now return the raw API response directly instead of formatted/transformed data.

#### Breaking Changes

• Execute Canvas: Now returns the full CompletionResponse object from the API

– Before: data.choices[0].message?.content (sync) or { id, status } (async)
– After: Full API response object

• Execute Workstation: Now returns the full API response

– Before: { status: "created" }
– After: Full CompletionResponse object from the API

• Get Completion: Now returns the full API response

– Before: { status, ...outputContent } (succeeded) or { status } (pending)
– After: Full GetCompletionResponse object with id, status, and outputContent

#### Migration Guide

If your workflows depend on the previous response format, you’ll need to update your expressions:

Execute Canvas (sync) - accessing content
Before: {{ $json.fieldName }}
After:  {{ $json.choices[0].message.content.fieldName }}
Execute Canvas (async) - accessing id/status
Before: {{ $json.id }}
After:  {{ $json.id }}  (no change needed)
Get Completion - accessing output content
Before: {{ $json.fieldName }}
After:  {{ $json.outputContent.content.fieldName }}

#### Why This Change?

• Provides full API response data for advanced use cases
• Eliminates data loss from response transformation
• Gives users complete control over how to process the response
• Simplifies codebase maintenance

Version 1.2.0

New Features: Async Execution, Completion Polling & Workstation Integration

#### New Operations

• Execute Workstation: Create tasks in the Tela Workstation dashboard

– Tasks are visible in the Tela web interface for review and approval
– Supports optional label field for task identification
– Automatically fetches application_id from the canvas
– Returns { status: "created" } on success

• Get Completion: Retrieve the result of an async canvas execution

– Accepts a completionId parameter
– Returns { status, ...content } when succeeded
– Returns { status } when still processing (for polling workflows)

#### Execute Canvas Enhancements

• Async Execution: New toggle to execute canvases asynchronously

– When enabled, returns immediately with { id, status } instead of waiting for completion
– Ideal for long-running AI tasks that may exceed timeout limits
– Enables building polling workflows with Wait + If nodes

#### Use Case: Async Workflow Pattern

1. [Tela: Execute Canvas] (Async: ON) → { id: "abc-123", status: "pending" }
2. [Wait] → 5 seconds
3. [Tela: Get Completion] (ID: {{ $json.id }}) → { status: "pending" } or { status: "succeeded", ...content }
4. [If] status !== "succeeded" → Loop back to step 2
5. [Continue] → Process the completed result

#### Use Case: Workstation Task Creation

1. [Webhook] → Receive data from external system
2. [Tela: Execute Workstation] → Create task with label "{{ $json.customer }} - {{ $json.orderId }}"
3. [Task appears in Tela dashboard for human review]

#### Technical Details

• Added async parameter to completion request body
• Added status field to completion response types
• New GetCompletionResponse type for get completion endpoint
• New PromptApplication and WorkstationRequest types
• New /prompt-application endpoint integration
• Graceful error handling for polling requests

Version 1.1.2

UX Pattern compliance for n8n verification:

#### n8n Verification Requirements

• Implemented Resources and Operations pattern: Added standard n8n UX pattern with Resource and Operation dropdowns

– Resource: Canvas (single option, extensible for future resources)
– Operation: Execute (executes a canvas with variables)
– All existing functionality preserved and unchanged
– No breaking changes – workflows continue to work seamlessly

#### User Experience Improvements

• Better discoverability: Users can now see available resources and operations in dropdown menus
• Consistent with n8n ecosystem: Follows the same UX pattern as official n8n nodes
• Future-proof architecture: Easy to extend with additional operations (Get Details, List, etc.)

#### Technical Details

• Added resource property with ‘canvas’ option
• Added operation property with ‘execute’ action
• Updated all existing properties with displayOptions to show conditionally
• Maintains backwards compatibility with existing workflows

#### Breaking Changes

• None – all changes are backwards compatible

Version 1.1.0

Major improvements for n8n Cloud verification compliance:

#### Critical Fixes

• Removed dependency overrides: Eliminated overrides section from package.json to prevent masking security vulnerabilities
• Replaced native fetch() with n8n HTTP helpers: All API requests now use n8n’s httpRequest helper for proper proxy support, retry logic, and request logging
• Added pairedItem linking: Implemented proper data flow tracking with pairedItem metadata on all outputs

#### High Priority Improvements

• Enhanced error logging: Replaced console.error with n8n’s logger service for better debugging in production
• Added continueOnFail support: Workflows can now handle errors gracefully and continue processing remaining items
• Multi-item processing: Refactored execute() method to properly process multiple input items in batch

#### Quality Improvements

• Converted icon to SVG format: Replaced PNG icon with SVG for better scalability and 70% smaller file size

– Updated both node and credential files to use tela.svg
– Removed legacy PNG icon from build output
– Consistent icon format across entire package

• Improved error handling: Added NodeOperationError with detailed metadata including itemIndex
• Better type safety: Enhanced TypeScript types for HTTP request methods

#### Breaking Changes

• None – all changes are backwards compatible

#### Developer Experience

• Enhanced logging visibility in n8n execution logs
• Better error messages with actionable descriptions
• Improved workflow debugging with proper data flow tracking

Version 1.0.16

• Replace get prompts call (includeLastVersion=true) for /promoted-version endpoint (the old one was deprecated internally)

Version 1.0.15

• Fixed critical security vulnerabilities in transitive dependencies
• Updated axios from vulnerable version to 1.12.2 (fixes CVE-2025-58754)
• Updated form-data from vulnerable version to 4.0.4 (fixes CVE-2025-7783)
• Added npm overrides to ensure secure dependency versions across all packages
• Zero vulnerabilities reported by npm audit

Version 1.0.14

• Added credential test method to fix n8n verification pre-checks
• Fixed n8n verification pre-checks by restructuring project to match n8n-nodes-starter template
• Moved credentials and nodes to proper directories as required by n8n
• Enhanced README documentation for n8n verification compliance
• Added comprehensive usage examples and sample workflows
• Improved installation and configuration instructions
• Added troubleshooting guide and development documentation

Version 1.0.1

• Enhanced error handling
• Improved file upload support
• Better variable validation

Version 1.0.0

• Initial release
• Basic Tela API integration
• Dynamic variable support

License

MIT