AI Skills Architecture — Persistence, Open Standards, and Why This Isn't Just a REST Wrapper

Use this guide when a customer or prospect asks:

• "How is this different from calling the API yourself?"
• "Is this just MCP?"
• "How does the bot remember who the customer is?"
• "What open standards does Velaro use?"
• "Why can't I just use HTTP nodes or a Zapier webhook?"

---

The one-paragraph answer

Velaro's AI Skills are named, pre-authenticated operations that a language model selects and calls based on conversation intent. The key architectural properties that separate them from every other approach — REST wrappers, HTTP nodes, MCP servers, Zapier steps — are: the LLM selects which operation to call (no routing logic authored), visitor identity captured at session start flows automatically into every operation as the implicit lookup key (no re-identification), and credentials are stored once encrypted and signed server-side on every call (no credential management in workflows). The REST API call is the last 5%. Everything above it is what skills provide.

---

What "persistence" means in this context

There are two things that persist across a conversation and one thing that is deliberately stateless:

What persists — conversation identity attributes

When a visitor starts a chat and fills in the prechat survey (name, email, phone), those values are written to ConversationAttributes — a table keyed to the conversation ID. They stay there for the lifetime of the conversation.

Every skill call can read these attributes. When the AI calls netsuite_search_orders, it passes the visitor's email from ConversationAttributes as the customer lookup key. The AI never has to ask "what's your email?" in chat. The session is the identity.

This is the implicit identity threading property. It's the biggest experience difference customers notice: the bot already knows who they are.

What persists — integration credentials

OAuth credentials are stored encrypted (AES-256) in an integration config record scoped to the site. Entered once by the admin. Used on every API call for that site. Never touched again unless the customer rotates their NetSuite tokens.

Credentials never appear in:

• Workflow definitions
• AI system prompts
• Conversation logs
• API responses

What is stateless — the API calls themselves

Each skill execution is a fresh signed HTTP request to the ERP. No long-lived session is held open to NetSuite between conversation turns. The conversation itself is the session. The ERP sees a series of individual REST calls, each signed with the stored credentials.

This is intentional. Stateless API calls are simpler, more resilient, and scale without connection pooling concerns.

---

Velaro OAuth signing — stricter than the spec

Velaro signs NetSuite API requests with HMAC-SHA256, not HMAC-SHA1.

The OAuth 1.0a specification (RFC 5849, Section 3.4.2) defines HMAC-SHA1 as the standard signature method. Velaro's implementation uses HMAC-SHA256 — a stronger hash that is not vulnerable to the known collision attacks against SHA1. This is a deliberate choice, not a deviation.

Every outbound call to NetSuite includes:

Authorization: OAuth oauth_signature_method="HMAC-SHA256", ...

The signing logic lives in velaro-messaging/Services/OAuth1Service.cs:

var hash = new HMACSHA256(Encoding.ASCII.GetBytes(
    $"{UrlEncode(consumerSecret)}&{UrlEncode(tokenSecret)}"));
var bytes = hash.ComputeHash(Encoding.ASCII.GetBytes(message));
return Convert.ToBase64String(bytes);

What this means in practice:

• NetSuite's REST API accepts HMAC-SHA256 — it is listed as a supported method alongside HMAC-SHA1
• Any tool or auditor checking Velaro's OAuth implementation will see a stronger signing algorithm than the spec requires
• If a customer or security reviewer asks "does Velaro use secure OAuth signing?" the answer is: yes, HMAC-SHA256, stricter than RFC 5849 requires

Where this is verified: velaro-messaging/Services/OAuth1Service.cs (signing), velaro-messaging/Services/CRM/NetSuite/NetSuiteApi.cs (header construction, GetAuthHeaderValue() method).

---

Open standards Velaro uses

Every native integration is built on well-established open standards — not proprietary protocols or vendor lock-in:

Layer	Standard	Details
Authentication	OAuth 1.0a (RFC 5849)	HMAC-SHA256 signing. Nonce + timestamp per request. Token-Based Authentication for NetSuite, OAuth 2.0 for HubSpot/Salesforce/Dynamics
Transport	HTTPS / REST	Standard HTTP verbs (GET, POST, PATCH, DELETE) to vendor REST APIs
Data format	JSON	All request and response bodies
AI tool calling	MCP (Model Context Protocol)	Anthropic open standard — how the LLM calls skill implementations
Conversation protocol	WebSocket (RFC 6455)	Used for real-time IVR relay and live agent push notifications

On OAuth specifically: Velaro implements OAuth 1.0a with HMAC-SHA256 (stricter than the spec's HMAC-SHA1 default). The signing service (OAuth1Service) constructs the signature base string, URL-encodes parameters per RFC 3986, and adds the Authorization: OAuth ... header to every outbound call. Customers never see this — it happens inside the execution engine.

---

Why this is not just a REST API wrapper

A REST wrapper translates your request format to the vendor's request format. That's it. You still have to:

1. Decide which endpoint to call — the wrapper doesn't know what the customer said

2. Pass the customer's identity explicitly — the wrapper doesn't have the conversation context

3. Author routing logic — what to call in what scenario

4. Handle multi-step operations — chaining separate calls in sequence

5. Map response fields back into the conversation

Velaro's Skills add all five of those layers above the REST call:

Layer	REST wrapper	Velaro AI Skill
Which operation to call	You decide (workflow branch)	LLM decides from conversation
Customer identity	You pass it explicitly	Session attribute, threaded automatically
Multi-step composition	You wire nodes in sequence	LLM composes from conversation context
Field validation	You know the field names or it fails	Velaro validates against live vendor schema
Credential management	In the wrapper / workflow	Encrypted server-side, signed per-call

The REST call is a delivery mechanism. The skill is the reasoning, routing, identity threading, and execution layer above it.

---

Why this is not just MCP

MCP (Model Context Protocol) is the transport layer that connects an LLM to tool implementations — like HTTP is the transport layer for websites. MCP itself does nothing. You still need:

1. A tool server to host and run your tools

2. Tool definitions (name, description, parameter schema for each operation)

3. OAuth/auth implementation in the server

4. Field validation logic

5. Error handling

6. Hosting and infrastructure

Velaro's native skills ARE the application layer above MCP. They run over MCP, but MCP is not what makes them work. What makes them work is that Velaro has already built, tested, and maintains the tool server, tool definitions, auth signing, field validation, and error handling for each supported platform.

When to use Velaro's native skills: Your platform is HubSpot, Shopify, BigCommerce, WooCommerce, Magento, Dynamics 365, NetSuite, Salesforce, Zoho, Pipedrive, QuickBooks, Square, Klaviyo, Mindbody, Guesty, Uplisting, Cloudbeds, Accela, or any other natively supported integration. Native skills include automatic OAuth, transcript push, sidebar contact display, and data mapping — none of which raw MCP gives you.

When to use MCP: You have a custom internal system Velaro doesn't natively support — your own order database, a proprietary CRM, an internal tool. In that case, you build the MCP server and Velaro's AI calls your tools the same way it calls native skills.

See [→ MCP Guide](/copilot-kb/mcp-guide) for how to connect a custom MCP server.

---

Why this is not just Zapier / Make / Power Automate

Automation platforms like Zapier connect events to actions via explicit trigger → action chains. They have no conversation context. They can't:

• Select which action to run based on what a customer said
• Thread conversation identity into downstream steps
• Chain steps dynamically based on conversation outcome
• Surface results back in the chat in real time

Zapier fires when something happens. Skills fire because the LLM determined it was the right action for what the customer just said. These are fundamentally different models.

Velaro does integrate with Zapier, Make, and Power Automate for post-conversation automations (e.g., "when a conversation closes with a lead tag, create a HubSpot deal"). That's the right use case for those tools. In-conversation ERP and CRM operations belong in native skills.

---

How implicit identity threading works — step by step

This is the property most customers don't expect and most appreciate once they see it.

Step 1 — Session start

Visitor opens the chat widget and fills in the prechat survey:

Name: John Smith
Email: jsmith@acme.com
Phone: 555-1234

These are written to ConversationAttributes:

name=velaro_prechat_email    value=jsmith@acme.com
name=velaro_prechat_name     value=John Smith
name=velaro_prechat_phone    value=555-1234

Step 2 — Skill call

Visitor says: "What's the status of my last order?"

The AI decides to call netsuite_search_orders. It reads ConversationAttributes, finds velaro_prechat_email = jsmith@acme.com, and passes it as the customer lookup parameter. No explicit variable mapping. No "what's your email?" prompt.

Step 3 — Response

NetSuite returns the order records for jsmith@acme.com. The AI reads them and responds: "Your most recent order (#SO-4821) shipped Tuesday via FedEx. Tracking: 123456."

Step 4 — Multi-step chain

Visitor: "I want to return the second item."

The AI calls netsuite_get_order to get line items, then netsuite_create_rma with the item details. Both calls use jsmith@acme.com as the implicit key. The visitor never re-identifies. The entire chain was generated by the conversation — no workflow branch for "return flow" exists in the workflow editor.

---

NetSuite-specific: credentials and permissions

Credentials you need (entered once in Velaro → Integrations → NetSuite):

Credential	What it is	Where to get it
Account ID	Your NS account number (e.g., 1234567 or TSTDRV123456)	Setup → Company → Company Information → Account ID
Consumer Key	Identifies the Velaro app to NetSuite — like a Client ID	Setup → Integration → Manage Integrations → New (enable Token-Based Auth)
Consumer Secret	Proves the Consumer Key is genuine — like a Client Secret	Same Integration Record screen — shown once at save
Token ID	Which NetSuite user/role this connection acts as	Setup → Users/Roles → Access Tokens → New
Token Secret	Proves the Token ID is legitimate	Same Access Token screen — shown once at save

Minimum role permissions for the access token:

Category	Permission	Level needed
Setup	REST Web Services	Full
Setup	Token-Based Authentication	Full
Lists	Customers	View (+ Edit for write-back operations)
Transactions	Sales Orders	View
Transactions	Invoices	View
Transactions	Return Authorization	View, Create
Transactions	Opportunities	View, Create
Transactions	Estimates / Quotes	View, Create
Lists	Items	View
Support	Cases	View, Create, Edit
Lists	Lead / Prospect	Create (for lead capture skill)

If Test Connection shows red on a skill category, the role is missing that category's permission. Add it and re-test.

---

Integrations with native AI Skills (use Skills, not MCP)

All platforms below have 15–35 pre-built, pre-authenticated AI tools. Setup = connect credentials, pick tools in workflow.

Platform	Skills	Auth type	Key use cases
HubSpot	29	OAuth 2.0	Contacts, deals, tickets, sequences, quotes
Shopify	35	OAuth 2.0	Orders, returns, refunds, products, discounts
BigCommerce	33	API key	Orders, carts, B2B quotes, customer intelligence
WooCommerce	28	API key	Orders, refunds, products, customers
Magento	29	OAuth 2.0	Orders, invoices, refunds, B2B quotes
Dynamics 365	28	OAuth 2.0	Contacts, accounts, cases, opportunities
NetSuite	29	OAuth 1.0a HMAC-SHA256	Orders, invoices, cases, RMA, leads, inventory
Salesforce	Native	OAuth 2.0	Contacts, cases, opportunities, leads
Zoho CRM	Native	OAuth 2.0	Contacts, deals, tickets
Pipedrive	Native	API key	Contacts, deals, activities
QuickBooks	Native	OAuth 2.0	Invoices, customers, payments
Klaviyo	6	API key	Profiles, flows, events
Accela Civic	30	OAuth 2.0	Permits, inspections, 311 requests
Clover POS	16	OAuth 2.0	Menu, orders, customer lookup
Jobber	16	OAuth 2.0	Jobs, quotes, invoices, scheduling
Guesty	20	API key	Reservations, guests, pricing
Uplisting	18	API key	Reservations, availability, guests
Cloudbeds	20	OAuth 2.0	Reservations, billing, availability

For any platform not in this list, use MCP with a custom tool server.