This document specifies everything your engineering team needs to register and operate Skills within the customer engagement platform. A Skill is a client-defined action — described in plain language, backed by your API — that the AI can invoke autonomously when a customer interaction calls for it.
A Skill is the bridge between the AI and your business systems. You define it once — with a plain-language description and an API endpoint — and the platform's Skills Engine decides when to invoke it based on what a customer is asking for.
You do not write any prompts. You do not instruct the AI when to call the Skill. The AI reads the customer's message, matches intent against your registered Skills, and invokes the correct one. Your only responsibility is to provide a well-described Skill and a reliable API endpoint that returns the correct response shape.
Skills only activate when the AI detects action-intent in a message — a customer asking for something to be done, not just answered. Pure information queries (tracking a shipment, asking about a policy) skip the Skills Engine entirely to keep response times fast.
Each Skill is registered via the client dashboard or the Management API. The following fields are required for every Skill.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Required | A short internal identifier. Used in audit logs and dashboards. Not seen by the AI. E.g. issue_reprint |
| description | string | Required | Plain-language description of what this Skill does and when it should be used. This is what the AI reads. Write it from the customer's perspective. Max 300 characters. |
| endpoint | string (URL) | Required | The HTTPS endpoint the platform will call when this Skill is invoked. Must be publicly reachable. IP allowlisting available on request. |
| method | enum | Required | HTTP method. Accepted values: POST GET PATCH. Use POST for all actions with side effects. |
| auth | object | Required | Authentication config. See auth object schema below. |
| payload_schema | object (JSON Schema) | Required | JSON Schema defining the expected request body. The AI uses this to construct the correct payload from conversation context. |
| risk_tier | enum | Required | Determines how invocation is gated. Values: low medium high. See Section 04. |
| timeout_ms | integer | Optional | Maximum wait time in milliseconds before the platform treats the call as failed. Default: 5000. Max: 15000. |
| enabled | boolean | Optional | Toggle the Skill on or off without deleting it. Default: true. |
Supported authentication types:
{
"type": "bearer",
"token": "your-secret-token"
}
{
"type": "api_key",
"header": "X-API-Key",
"value": "your-api-key"
}
{
"type": "hmac",
"secret": "your-signing-secret",
"header": "X-Signature" // platform signs each request body
}
Every Skill must declare a risk tier. This controls whether the platform executes the Skill automatically, pauses for customer confirmation, or holds for a human agent. Assign the tier that reflects the real-world consequence of the action being performed.
Read-only or low-consequence actions. Executed automatically with no confirmation step.
Reversible actions with customer impact. The AI confirms intent with the customer before calling your API.
Irreversible or financially significant actions. Routed to the Human Approval Queue before execution.
When a Skill is invoked, the platform sends a POST request (or your configured method) to your endpoint. The request body contains two top-level keys: the payload constructed from your payload_schema, and a platform-provided context block.
{
"skill_name": "issue_reprint",
"invocation_id": "inv_01j9k2m3n4p5q6r7", // unique per call, use for idempotency
"payload": {
// fields you defined in payload_schema, populated from conversation context
"order_id": "ORD-88291",
"reason": "damaged_in_transit",
"customer_confirmed": true
},
"context": {
"conversation_id": "conv_7f3a9c",
"customer_id": "cust_19283", // your customer identifier if known
"channel": "chat", // chat | email
"timestamp": "2025-04-13T14:22:05Z"
}
}
Define payload_schema as a standard JSON Schema object. The AI uses this schema to extract and validate the required fields from the conversation before calling your endpoint.
{
"type": "object",
"required": ["order_id", "reason"],
"properties": {
"order_id": {
"type": "string",
"description": "The customer's order reference number"
},
"reason": {
"type": "string",
"enum": ["damaged_in_transit", "print_quality", "wrong_item", "other"],
"description": "Reason for the reprint request"
},
"customer_confirmed": {
"type": "boolean",
"description": "Whether the customer confirmed the reprint action"
}
}
}
description on each property to understand what value to extract from the conversation. Write them clearly — "The customer's order reference number" is better than "order_id".Your API must return a response matching the platform's standard envelope. This normalisation is what allows the AI to re-enter its reasoning loop reliably regardless of what your underlying system returns.
{
"status": "success", // "success" | "failure" | "pending"
"data": { // any object — returned to AI for context
"reprint_id": "RPT-44123",
"estimated_dispatch": "2025-04-15"
},
"summary": "Reprint issued successfully. Estimated dispatch 15 April."
// Human-readable sentence the AI can use directly in its response to the customer.
}
| Field | Type | Required | Description |
|---|---|---|---|
| status | enum | Required | success — action completed. failure — action could not be completed. pending — action queued, not yet complete. |
| data | object | Required | Structured result data. Can be an empty object {} if there is nothing to return. The AI uses this to reason about follow-up actions. |
| summary | string | Required | A single plain-English sentence describing the outcome. The AI may use this verbatim in its response to the customer. Write it customer-facing. |
The platform handles Skill failures gracefully — the customer conversation is never abandoned. Below are the failure modes and platform behaviour for each.
| Scenario | Platform behaviour | Your action |
|---|---|---|
| HTTP 4xx | Skill marked failed. AI informs customer the action could not be completed and offers to escalate. | Check your API logs. Common cause: malformed payload from schema mismatch. |
| HTTP 5xx | Platform retries once after 1s. On second failure, routes to human queue with full context. | Check endpoint health. Platform will alert via webhook if 5xx rate exceeds threshold. |
| Timeout | After timeout_ms, platform treats as failure. Routes to human queue. |
Optimise endpoint response time or increase timeout_ms in Skill config (max 15s). |
| status: "pending" | AI informs customer the action is in progress and they will be updated. No escalation. | Send a follow-up via the platform's outbound API when the action completes. |
| status: "failure" | AI reads your summary field and communicates the failure reason to the customer, then offers alternatives. |
Write a clear, customer-facing summary that explains why the action failed. |
| Invalid envelope | Skill fails immediately. Routed to human queue. Logged as schema violation. | Review response envelope spec in Section 06. Use sandbox to validate before go-live. |
Every invocation includes a unique invocation_id in the request body. You should use this as an idempotency key on your side to prevent duplicate actions if the platform retries on a 5xx. Store the invocation_id against the action outcome and return the same response if you receive the same ID twice.
Every client account has an isolated sandbox environment. Skills registered in sandbox are never invoked in production. Use sandbox to validate your endpoint, response envelope, and payload schema before enabling a Skill in production.
Use the dashboard or Management API with environment: "sandbox". Point the endpoint at your staging environment.
Use the Skills Tester in the dashboard to send a synthetic payload to your endpoint. Review the full request and response logged in real time.
The tester validates your response against the required envelope schema and flags any mismatches before they cause production failures.
Submit test customer messages via the sandbox chat widget. Verify that your Skill description triggers the correct match and that the AI constructs the payload correctly from the conversation.
Once all tests pass, toggle environment: "production" in the dashboard. The Skill becomes live immediately.
A complete end-to-end example of a Skill registration, invocation, and response for a reprint request.
{
"name": "issue_reprint",
"description": "Issue a free reprint for a customer whose order arrived damaged, had a print quality problem, or contained the wrong item. Use when a customer reports a problem with a received order and wants it resent.",
"endpoint": "https://api.yourcompany.com/fulfillment/reprint",
"method": "POST",
"auth": {
"type": "bearer",
"token": "sk-live-xxxxxxxxxxxx"
},
"risk_tier": "medium",
"timeout_ms": 6000,
"payload_schema": {
"type": "object",
"required": ["order_id", "reason"],
"properties": {
"order_id": { "type": "string", "description": "Customer order reference" },
"reason": { "type": "string", "enum": ["damaged_in_transit", "print_quality", "wrong_item", "other"] }
}
}
}
{
"skill_name": "issue_reprint",
"invocation_id": "inv_01j9k2m3n4p5q6r7",
"payload": {
"order_id": "ORD-88291",
"reason": "print_quality"
},
"context": {
"conversation_id": "conv_7f3a9c",
"customer_id": "cust_19283",
"channel": "chat",
"timestamp": "2025-04-13T14:22:05Z"
}
}
{
"status": "success",
"data": {
"reprint_id": "RPT-44123",
"estimated_dispatch": "2025-04-15"
},
"summary": "Reprint issued successfully. Estimated dispatch 15 April."
}
Complete all items before enabling a Skill in production.
Describes the customer problem, not the internal function name. Reviewed for clarity against real customer phrasing.
Tested from an external network. Response time consistently under your configured timeout_ms.
Platform Skills Tester confirms status, data, and summary fields present and correctly typed on all response paths (success, failure, pending).
invocation_id stored and checked on your side. Duplicate calls return the same response without re-executing the action.
Tier assignment reviewed by someone with operational authority, not just the engineering team.
At least five real customer message variants tested in sandbox chat. Skill triggers correctly on genuine requests and does not trigger on unrelated messages.
4xx, 5xx, and timeout scenarios tested in sandbox. Confirmed that conversation routes gracefully without customer-facing errors.