Plugin Input Fields

Actions and Triggers in plugins require input fields so users can send data to your API—like creating, updating, or searching for a record. These fields are defined in JSON format and appear in the viaSocket UI when users build their workflows.

What Are Static Input Fields?

Static input fields are fixed fields that do not change based on user choices. They're predefined and useful when you know exactly what inputs are needed.

These help structure and validate the data users enter—improving accuracy and user experience.

Types of Static Input Fields

String

Collects plain text like names, email addresses, or labels.
Example: "Name" with a default like "John Doe"

Number

Accepts numeric values such as price, quantity, or age.
You can apply limits (min/max) to ensure valid input.

Boolean

Captures true/false or yes/no choices using toggles or checkboxes.
Ideal for things like "Subscribe?" or "Agree to Terms"

Static Dropdown

Shows a fixed list of options for users to pick from.
Great for fields like "Country", "Status", or "Priority"

Input Group

Groups multiple related fields under one label (e.g., address block).
Helps organize complex input like "Shipping Info" or "User Details"

Default Value

Sets a pre-filled value to guide users on expected input.
Helps with clarity and improves usability.

Where to Use This

• In plugin Actions: Send user-entered data to external APIs

• In Triggers: Accept filter values or settings for trigger logic

• In forms: Display clean, user-friendly inputs for workflow setup

📘 For Instructions on Adding Fields via JSON:

Click here

When building powerful plugins, sometimes basic input types like text or number aren't enough. That's where Advanced Input Fields come in—they enhance form flexibility, adapt to user choices, and streamline complex data collection.

Why Use Advanced Input Fields?

These fields are especially useful for:

• Multi-select options (like tags or categories)

• Dynamically changing form options

• User-guided input with help text

• Organizing complex or repeated data

Key Types of Advanced Input Fields

Dynamic Dropdown

A dropdown where options are fetched dynamically using JavaScript.

• Users select a single value

• Options load from a script using the source key

• Perfect for API-driven lists (e.g., selecting a contact or channel)

👉 The dropdown auto-renders based on your JavaScript source logic.

Dynamic Multiselect

A multi-select version of the dropdown—also powered by JavaScript.

• Allows selecting multiple items

• Great for choosing tags, categories, or multiple preferences

• Returns an array (comma-separated) in the API request

🚫 Do not ask users to enter comma-separated values manually—this field handles it natively.

Hidden Fields

This smart field controls visibility of other fields.

• Based on the selected value, it hides specified fields dynamically

• Uses a fieldsToHide mapping in JSON

• Ideal for conditional logic in your plugin forms

Help Text

Optional instructional text displayed alongside input fields.

• Explains what data is expected

• Reduces errors and improves clarity

• Ideal for fields with special formatting or complex logic

Dictionary

Used to collect key-value pairs, like JSON objects.

• You define templates for keys and values

• Users can add multiple entries (e.g., {"type": "email", "value": "[email protected]"})

• Ideal for headers, parameters, or field mappings

Dynamic Input Groups

Lets users add/remove groups of related fields.

• Example: multiple phone numbers or social media links

• Flexible and repeatable input structure

• Each group can contain several field types

📘 To Learn How to Add Advanced Input Fields to Your Plugin:

Click here

A Dictionary (also called Map or Key-Value Pair) is a special input type in viaSocket that lets users dynamically define custom pairs of keys and values. This provides high flexibility when the structure of input data is variable or unknown in advance.

What Is a Dictionary?

In programming, a dictionary is a data structure where:

• Each key is unique

• Every key points to a corresponding value

• Keys and values can be text, numbers, booleans, etc.

In viaSocket:

The dictionary field allows users to manually add rows of custom key-value pairs right from the UI.

Example Use Cases:

Benefits of Using Dictionary Fields

• ✅ Highly flexible for unknown or dynamic input structures

• ✅ Enables advanced users to pass complex parameters

• ✅ Supports scalable API configurations

• ✅ Works well with headers, query strings, custom payloads

A Dynamic Input Group is a powerful UI component in viaSocket that lets you display or hide multiple input fields based on user interactions or API responses. It allows users to dynamically add or remove grouped sets of fields—making your plugin more flexible and intuitive.

What Is a Dynamic Input Group?

Unlike static fields, dynamic input groups:

• Appear only when needed

• Can be added or removed on the fly

• Are perfect for collecting repeatable or optional data sets

Think of them as repeatable forms that adapt in real-time based on the context.

Use Cases

Behavior and Benefits

• ✅ Real-time addition/removal of grouped fields

• ✅ Supports complex forms with nested inputs

• ✅ Reduces visual clutter in the UI

• ✅ Can be tied to a switch, dropdown, or API response

Tips

• Use with conditional visibility for cleaner UX

• Ideal for multi-object payloads in Actions

• Can be used with API-populated dynamic dropdowns inside the group

Dynamic Dropdowns are input fields that fetch their list of options from an API or based on another field’s input. Unlike static dropdowns, which show a fixed list, dynamic dropdowns update in real-time, offering a flexible and powerful way to present relevant options to users.

Why Use Dynamic Dropdowns?

• Show live data from your external app (e.g., contact lists, categories, status codes)

• Reduce errors by offering only valid, current choices

• Create dependent dropdowns (e.g., country → state → city)

Use Cases

How It Works

1. Define the input field type as "dynamic_dropdown"

2. Specify an API call that fetches the dropdown options

3. viaSocket will:

   • Make the API request (with token/headers if needed)

   • Parse the response

   • Display the returned list as dropdown choices

Features

• 🔁 Refresh on change – fetch data again when another field is updated

• 🔐 Works with OAuth / Basic Auth / No Auth

• 📄 Supports nested API responses (via dataPath)

• 🌐 Multiple dynamic dropdowns in one form
  

Dynamic Help Text provides real-time feedback and contextual assistance to users—based on live conditions inside your plugin's code. It helps users understand what’s happening, especially when something goes wrong.

Rather than showing static instructions, dynamic help adapts to API responses, user inputs, or edge cases—making your plugin easier to debug and more intuitive to use.

Why Use It?

• Guide users when something is misconfigured

• Alert when required data (e.g., column headers) is missing

• Help users resolve issues instantly

• Enhance user experience with real-time suggestions

Example Use Case

Suppose you’re creating an action for Google Sheets to insert a new row. The plugin must know what columns exist—but if the selected sheet has no headers, you should notify the user immediately.

How It Works

You can fetch data using an API call, check a condition, and then return either:

• A valid field structure

• Or a message + empty fields when validation fails

Sample Code

const apiUrl = https://sheets.googleapis.com/v4/spreadsheets/${context.inputData.spreadSheet_id}/values:batchGet?ranges=${context.inputData.sheet_id}!1:1000&valueRenderOption=UNFORMATTED_VALUE;  const headers = {   Authorization: Bearer ${context.authData.accesstokencode.access_token} };  const response = await axios.get(apiUrl, { headers });  let arrToReturn = [];  // ✅ If column headers are found if (response.data?.valueRanges?.[0]?.values?.[0]) {   const headers = response.data.valueRanges[0].values[0];   arrToReturn = headers.map(entry => ({     key: entry,     label: entry,     type: 'string',     required: false,     help: ''   })); }  // ❌ If no headers found else {   arrToReturn = {     children: [],     message: 😕 Didn't see any headers in the provided spreadsheet.  🛠 Did you add headers to the spreadsheet?   If so, refresh this step to pull in the new data.  🔗 [Click here for instructions on setting up your spreadsheet.](https://viasocket.com/faq)   }; }  return arrToReturn; 

How to Use in viaSocket

• Add this code directly in the plugin builder's JavaScript API Call

• Or embed it in JSON using the "source" key (make sure to escape the code using EscapeJSON before pasting)

Pro Tip

You can use this method in any plugin scenario—like:

• Checking authentication validity

• Verifying API credentials

• Ensuring resources (e.g., project ID, table columns) exist

• Alerting for unsupported settings

The Hidden Field feature lets you control which fields appear in the UI based on user selections. It’s perfect for creating clean, dynamic forms where users only see what’s relevant.

This is especially useful when you want to show or hide specific fields based on another field’s value—like a dropdown selection.

Why Use Hidden Fields?

• Hide irrelevant fields to reduce clutter

• Show only the fields needed for a specific selection

• Pass hidden data silently without user input

• Maintain flexible form logic with minimal user confusion

Important Notes

• Hidden fields do not support dynamic API calls for children

• You can use them with static dropdown options

• Fields are controlled using the "fieldsToHide" logic

Example Scenario

Let’s say you have a dropdown called File Type with options:

• Image

• PDF

• Text

Sample JSON Setup

[
  {
    "key": "FileType",
    "type": "hidefields",
    "label": "File Type",
    "options": [
      { "label": "attachment", "value": "attachment", "sample": "attachment" },
      { "label": "image", "value": "image", "sample": "image" },
      { "label": "file", "value": "file", "sample": "file" }
    ],
    "fieldsToHide": {
      "file": ["image", "attachment"],
      "image": ["attachment", "file"],
      "attachment": ["image", "file"]
    }
  },
  {
    "key": "image",
    "type": "string",
    "label": "Image URL"
  },
  {
    "key": "file",
    "type": "string",
    "label": "File Path"
  },
  {
    "key": "attachment",
    "type": "string",
    "label": "Attachment Link"
  }
]

🔍 How It Works

• User selects "image" in the dropdown
  → Only the image field is shown.

• If "file" is selected
  → Only the file field is shown.

• If nothing is selected
  → All fields are visible by default

💡 Pro Tips

• Use this pattern to conditionally reveal config sections, upload fields, or advanced settings

• Works best when paired with "type": "hidefields" and clearly defined fieldsToHide

• Helpful in actions like file uploads, media classification, or multi-mode plugins

Show fields based on selected field:

The AI Field in viaSocket Plugin Builder enables you to integrate AI-powered capabilities into your app's triggers and actions. By adding this field type, you can allow your users to leverage AI for complex tasks without requiring manual intervention.

How to Use the AI Field

When building a plugin in viaSocket, you can include an AI Field to enhance your app’s automation capabilities. This field type helps automate decision-making, text generation, data extraction, and other AI-supported functions, making integrations smarter and more efficient.

JSON Configuration for AI Field

To add an AI Field to your plugin, use the following JSON structure:

{
    "key": "XfDxOeon",
    "type": "aifield",
    "label": "Sample Label",
    "help": "Enter help text",
    "required": true,
    "prompt": "Write a prompt to define the AI's behavior, task, or role.",
    "suggestionGenerator": " // Enter JS code as the source from which AI will generate results"
}

Explanation of JSON Fields

• key: A unique identifier for the AI field.

• type: Specifies the field type as aifield.

• label: The display name of the field.

• help: Instructional text to guide users on how to use this field.

• required: Defines whether this field is mandatory.

• prompt: Defines the AI's behavior, task, or role in generating responses.

• suggestionGenerator: Specifies the source of data from which the AI will generate results.

Benefits for SaaS Developers and Plugin Builders

• Enhanced automation: Leverage AI to automate complex tasks within your app integration.

• User-friendly experiences: Reduce the need for manual inputs by providing AI-powered suggestions.

• Customizable AI responses: Define AI behavior through structured prompts and dynamic data inputs.

• Seamless integration: Improve your app's functionality with AI-driven decision-making and processing.

Use Cases and Examples

Below are some direct JSON examples you can copy and paste into your viaSocket plugin:

1. Smart Email Categorization

{
    "key": "email_category",
    "type": "aifield",
    "label": "Email Category",
    "help": "Classify the email content into Sales, Support, or Feedback.",
    "required": true,
    "prompt": "Classify this email into one of the following categories: Sales, Support, or Feedback.",
    "suggestionGenerator": "return input.email_content;"
}

2. Automated Social Media Caption Generator

{
    "key": "social_caption",
    "type": "aifield",
    "label": "Generate Social Media Caption",
    "help": "Create an engaging caption for social media posts.",
    "required": true,
    "prompt": "Generate a creative Instagram caption for a new product launch.",
    "suggestionGenerator": "return input.product_name + ' ' + input.product_description;"
}

3. Customer Sentiment Analysis

{
    "key": "sentiment_analysis",
    "type": "aifield",
    "label": "Customer Sentiment",
    "help": "Analyze the sentiment of customer feedback.",
    "required": true,
    "prompt": "Analyze the sentiment of this customer review and provide a one-word summary.",
    "suggestionGenerator": "return input.customer_review;"
}

4. Resume Screening in HR Applications

{
    "key": "resume_score",
    "type": "aifield",
    "label": "Resume Screening Score",
    "help": "Evaluate resumes and suggest suitability for a role.",
    "required": true,
    "prompt": "Assess this resume and provide a suitability score (0-100) for the position of Software Engineer.",
    "suggestionGenerator": "return input.resume_text;"
}

5. Automated Data Enrichment

{
    "key": "data_enrichment",
    "type": "aifield",
    "label": "Enrich Lead Data",
    "help": "Fill missing company details based on partial contact information.",
    "required": true,
    "prompt": "Find and fill missing company details (industry, size, location) for this contact.",
    "suggestionGenerator": "return input.company_name;"
}

By integrating the AI Field in your viaSocket plugin, you can enhance your app’s automation capabilities, providing smarter and more powerful workflows for your users.

The Final Perform API is the core engine behind any action you define in your plugin. Once users fill out the required inputs and trigger the action, this API handles the actual communication with the external app or service.

What It Does

It executes the primary business logic—such as:

• Creating new records (e.g., contacts, leads, entries)

• Updating existing records

• Fetching specific data from an API

• Deleting a resource

When Does It Run?

After the user sets up the action inside a flow and clicks “Run” or triggers the automation, the Final Perform API is called using the values from the input fields.

API Call Responsibilities

• Connect to the external service using the correct method (GET/POST/PUT/DELETE)

• Send data from user-configured input fields

• Handle authentication (OAuth, API key, etc.)

• Map the API response to viaSocket’s internal structure

Example Usage in Code

const payload = {
  name: context.inputData.name,
  email: context.inputData.email
};

const response = await axios.post('https://api.example.com/createUser', payload, { headers });

return response.data;

Security & Validation

• You can validate inputs before sending them

• Use headers securely—don’t hardcode tokens

• Consider error handling with try/catch to manage API failures

Tip

If your API requires a dynamic URL (e.g., user ID in the path), you can build it using:

const userId = context.inputData.userId;
const url = `https://api.example.com/users/${userId}`;

Every Action or Trigger in a viaSocket plugin requires an input form. These forms collect user data and pass it to your app’s API to create, update, find, or delete records.

You can create input forms using either:

• GUI (Form Editor) – drag-and-drop input field builder

• JSON Configuration – manually define field structure and behavior

Why JSON?

JSON (JavaScript Object Notation) is the foundation for defining the input field behavior and structure in your plugin. It allows for flexible configuration, dynamic rendering, and consistent data processing.

In the Form Editor, define the following field attributes:

Example Use Case

If you're creating a trigger for a CRM plugin to “Find Deals by Stage,” your form might include:

• A dropdown for “Deal Stage” (fetched via API)

• A text field for “Minimum Deal Size”

• A boolean checkbox for “Include Archived Deals?”