Building a Custom Skill

Creating a Custom Skill

1. Go to Integrations → Custom Skills
2. Click Add Skill
3. Fill in the configuration:

Basic Configuration

• Name — what the agent calls this skill (e.g., "Check Appointment Availability")
• Description — what the skill does (helps the agent decide when to use it)
• Action Type — look_up (read data) or take_action (write/modify data)

HTTP Configuration

• Method — GET, POST, PUT, PATCH, or DELETE
• URL — the API endpoint. Use {parameter_name} for dynamic values (e.g., https://api.example.com/appointments/{date})

Parameters

Add each parameter the agent needs to collect:

• Name — parameter identifier
• Type — string, number, date, boolean
• Source — query parameter, path parameter, or request body
• Description — helps the agent understand what to ask for
• Required — whether the agent must collect this before calling the API

Authentication

• None — for public APIs
• API Key — specify the header name and key value
• Bearer Token — token passed in Authorization header
• Auth Source — use a shared credential set (configured once, reused across skills)

Response Mapping

Define how to extract useful information from the API response:

• Response path — JSON path to the relevant data (e.g., data.appointments)
• Display fields — which fields to show the agent (e.g., time, provider_name, available)

Context Burden

Choose how the agent uses this skill:

• Ambient — uses automatically, no mention to caller
• Conversational — uses naturally ("Let me check that for you")
• Requested — only when caller asks
• Confirmed — asks caller for confirmation before using
• Verified — requires identity verification first

Testing Your Skill

1. Click Test on the skill
2. Enter sample parameter values
3. Review the request (method, URL, headers, body) and response
4. Verify the response mapping extracts the right data

Always test before going live. A broken skill means the agent can't complete the action and has to tell the caller it failed.

Common Patterns

Calendar/scheduling system: GET availability by date range, POST to book, PATCH to reschedule, DELETE to cancel.

CRM/customer database: GET customer by phone or email, POST to create new record, PATCH to update.

Notification webhook: POST with call data to trigger external workflows (SMS, Slack, email).

Inventory/availability check: GET product or service availability, return results to caller.