Managing Operations

How to create and configure operations in your SDK project.

What are Operations?

Operations are the actions that users can trigger through natural language in your application. Each operation connects user intent to a specific piece of functionality in your code.

Operation Structure:

{
  "operation_id": "open-contact",
  "description": "Opens the contact form modal",
  "trigger_phrases": [
    "contact support",
    "get in touch", 
    "talk to someone"
  ]
}

Creating Operations

Via Dashboard

Navigate to SDK Projects
- Log into Produck Dashboard (opens in a new tab)
- Select your organization
- Go to SDK Projects
Select Your Project
- Click on your SDK project
- Navigate to the Operations tab
Add Operation
- Click "Add Operation"
- Fill in the form:

Operation Form Fields:

Field	Description	Example
Operation ID	Unique identifier used in code	`open-contact`
Name	Human-readable name	"Open Contact Form"
Description	What this operation does	"Opens the contact modal when user wants to get in touch"
Trigger Phrases	Natural language triggers	"contact us", "get help", "talk to support"

Save
- Click "Save Operation"
- Copy the operation ID for use in your code

Via API

// POST /api/v1/sdk/projects/:projectId/operations
const response = await fetch(`${API_URL}/sdk/projects/${projectId}/operations`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-SDK-Key': 'your-sdk-key',
  },
  body: JSON.stringify({
    operation_id: 'open-contact',
    description: 'Opens the contact form modal',
    trigger_phrases: [
      'contact support',
      'get in touch',
      'talk to someone',
    ],
  }),
});

Naming Conventions

Operation IDs

✅ Good:

open-contact
show-pricing
add-to-cart
start-onboarding
submit-feedback

❌ Bad:

action1 (not descriptive)
doThing (vague)
Open Contact (spaces, capitals)
openContactForm123 (unnecessary suffix)

Best Practices:

Use kebab-case
Be descriptive but concise
Start with verbs (open, show, add, submit)
Match the actual action performed

Descriptions

✅ Good:

"Opens the contact form modal for user inquiries"
"Displays the pricing page and highlights the selected plan"
"Adds the currently viewed product to the shopping cart"

❌ Bad:

"Contact" (too vague)
"Does the thing" (not specific)
"Opens modal" (which modal?)

Best Practices:

Explain what happens
Be specific about which component/feature
Mention user benefit when relevant

Trigger Phrases

Trigger phrases are the natural language patterns that activate your operation.

Writing Effective Triggers

✅ Good Trigger Set:

{
  "operation_id": "show-pricing",
  "trigger_phrases": [
    "show pricing",
    "how much does it cost",
    "what are your prices",
    "pricing plans",
    "see plans",
    "cost information"
  ]
}

Why it's good:

Covers different ways users express intent
Includes questions and commands
Uses synonyms (pricing/plans/cost)
Natural, conversational language

❌ Bad Trigger Set:

{
  "operation_id": "show-pricing",
  "trigger_phrases": [
    "pricing"
  ]
}

Why it's bad:

Only one phrase
Too short (high false-positive risk)
Doesn't cover variations

Trigger Phrase Guidelines

Add 3-10 phrases per operation
- Too few: Users might not match
- Too many: Dilutes matching quality

Cover different phrasings

- "contact support"
- "get in touch"
- "talk to someone"
- "need help"
- "reach out"

Include questions and commands

- "how do I contact you" (question)
- "contact support" (command)
- "I need to get in touch" (statement)

Use synonyms

- "pricing" / "plans" / "cost"
- "contact" / "reach" / "talk"
- "show" / "display" / "see"

Consider user intent, not exact words
- Think about WHY users want this action
- Include problem statements: "I have a question"
- Include goal statements: "want to upgrade"

Common Patterns

For Contact Forms:

"contact support"
"get in touch"
"talk to someone"
"need help"
"have a question"
"speak to a person"

For Pricing:

"show pricing"
"how much does it cost"
"what are the prices"
"pricing plans"
"see pricing"
"cost information"

For Account Actions:

"open my account"
"account settings"
"manage my profile"
"edit account"
"view account details"

For Product Actions:

"add to cart"
"buy this"
"purchase"
"get this product"
"add to basket"

Operation Types

While all operations follow the same structure, they typically fall into these categories:

1. Navigation Operations

Guide users to specific sections or pages.

{
  "operation_id": "show-features",
  "description": "Scrolls to and highlights the features section",
  "trigger_phrases": [
    "show features",
    "what can it do",
    "capabilities",
    "see features"
  ]
}

2. Modal Operations

Open dialogs, modals, or popovers.

{
  "operation_id": "open-contact",
  "description": "Opens the contact form modal",
  "trigger_phrases": [
    "contact us",
    "get in touch",
    "talk to support"
  ]
}

3. Form Operations

Fill forms or start form flows.

{
  "operation_id": "start-signup",
  "description": "Opens the registration flow",
  "trigger_phrases": [
    "sign up",
    "create account",
    "register",
    "get started"
  ]
}

4. State Change Operations

Modify application state.

{
  "operation_id": "toggle-dark-mode",
  "description": "Switches between light and dark themes",
  "trigger_phrases": [
    "dark mode",
    "change theme",
    "switch to dark",
    "toggle theme"
  ]
}

5. Data Operations

Fetch or display specific data.

{
  "operation_id": "show-order-history",
  "description": "Displays user's past orders",
  "trigger_phrases": [
    "my orders",
    "order history",
    "past purchases",
    "previous orders"
  ]
}

Testing Operations

1. Dashboard Test

Use the built-in test feature:

Go to your operation in dashboard
Click "Test"
Enter sample user messages
Check match confidence scores

2. Integration Test

Test in your application:

useProduckAction('test-operation', (payload) => {
  console.log('✅ Operation triggered!', payload);
  alert('Test successful!');
});

Then try various messages in the chat widget.

3. Coverage Test

Ensure all variations match:

const testPhrases = [
  "contact support",
  "get in touch",
  "talk to someone",
  "I need help",
  "how do I reach you",
];
 
for (const phrase of testPhrases) {
  const response = await produck.sendMessage(phrase);
  if (response.action?.actionKey === 'open-contact') {
    console.log(`✅ "${phrase}" matched`);
  } else {
    console.log(`❌ "${phrase}" did not match`);
  }
}

Updating Operations

Operations can be updated without code changes:

Edit in Dashboard
- Modify trigger phrases
- Update description
- Change operation name
Changes Take Effect Immediately
- No redeployment needed
- AI uses latest configuration
- Your code doesn't change
Operation ID is Immutable
- Cannot change operation_id after creation
- To change ID, delete and recreate operation

Deleting Operations

Warning: Deleting an operation will cause its handler to never trigger.

In dashboard, find the operation
Click "Delete"
Confirm deletion
Remove handler code from your app:

// Remove this:
useProduckAction('deleted-operation', handler);

Best Practices

Do's ✅

Start with core actions - Implement most important operations first
Test thoroughly - Try many variations of user input
Be specific - Each operation should do one thing well
Use clear IDs - Make code maintainable with good naming
Document - Keep description field updated
Iterate - Add more trigger phrases based on usage

Don'ts ❌

Overlap operations - Avoid similar trigger phrases across operations
Be too broad - "help" could mean many things
Use long IDs - Keep operation IDs concise
Forget edge cases - Test typos and variations
Overload operations - Don't make one operation do too much

Next Steps

API Reference Overview