Connect AI agent to external systems with custom actions
Custom actions let your AI agent send HTTP requests to external systems during conversations. The AI can also read
response data from those requests and use it in follow-up messages. Connect to Zapier, n8n, Google Sheets, or any
service with an API.
When to use custom actions
Use custom actions when you need the AI agent to interact with systems outside Commslayer and Shopify.
Examples:
- 🏭 Check inventory levels in a warehouse system
- 📦 Create return labels and share the tracking link with customers
- 🔄 Update order status in a 3PL system
- 📊 Log customer interactions to Google Sheets or your CRM
- 🔔 Send notifications to Slack when specific issues arise
- 🔗 Submit warranty claims and give customers their reference number
Custom actions work with any system that accepts HTTP requests, including Zapier webhooks and n8n workflows.
Creating a custom action
1. Go to AI agent → Actions
2. Click the Custom actions tab
3. Click + Custom action
4. Fill in the action details (see below)
5. Click Save
Action settings
Action name
A short name for the action. The AI agent sees this when deciding what actions are available.
Examples: "Check warehouse inventory", "Create return label", "Add loyalty points"
When to use this action
Describe when the AI should execute this action. Be specific about the conditions and triggers.
The AI uses this description to decide whether to execute the action based on the conversation context.
Good examples:
- "When customer asks to update their shipping address after order is fulfilled"
- "After order is cancelled and customer needs a refund confirmation sent to their CRM"
- "When customer asks about their loyalty points balance"
Bad examples:
- "For customer requests" (too vague)
- "When needed" (AI can't determine when)
API configuration
Method
The HTTP method for the request: GET, POST, PUT, PATCH, or DELETE.
Most integrations use POST for creating or triggering actions.
URL
The endpoint URL where the request will be sent.
Example formats (replace with your actual URLs):
- Zapier webhook: https://hooks.zapier.com/hooks/catch/123456/abcdef/
- n8n webhook: https://your-n8n.app.n8n.cloud/webhook/xyz
- Custom API: https://api.example.com/v1/orders
Headers
Key-value pairs sent with the request. Common uses:
- Authorization: Bearer your-api-key (replace with your actual API key)
- Content-Type: application/json (usually set automatically)
- X-API-Key: your-key (replace with your actual key)
Parameters
Parameters define what data gets sent with each request. You specify parameter names and descriptions, and the AI
extracts the values from the conversation.
Each parameter has:
- Name — The key sent in the request (e.g., order_id, issue_type)
- Type — Data type: string, number, boolean, or json
- Description — Helps the AI understand what value to extract
- Required — Whether the AI must provide this value
Example parameters:
- order_number (string) — "The Shopify order number being discussed"
- issue_type (string) — "Category of the issue: shipping_delay, damaged_item, wrong_item, etc."
- summary (string) — "Brief summary of the customer's problem"
- refund_amount (number) — "The refund amount requested"
The AI reads your descriptions and extracts the appropriate values from the conversation context. You can add any
parameters your integration needs.
Auto-populated data
Some data is automatically available without defining parameters:
- Customer info: email, name, phone
- Conversation info: ID, status, channel
Triggering custom actions reliably
The "When to use this action" field helps the AI decide when to run an action, but for consistent triggering, pair your
custom action with a guidance rule.
In your guidance rule's Agent instructions, tell the AI to use the action:
[Your instructions for handling this type of request]
After replying, use "Your action name" to log the details.
This ensures the action runs every time the guidance rule triggers, rather than relying on the AI to decide on its own.
Testing custom actions
After creating a custom action:
1. Click Test in the Actions page header
2. The AI Playground opens
3. Simulate a conversation that would trigger your action
4. Check your receiving system (Zapier, n8n, etc.) to verify the request arrived
Test with real data in the playground before enabling for live conversations.
Using webhook response data
Your AI agent reads responses from custom action webhooks and can reference that data in follow-up messages or actions.
When your webhook returns JSON, the AI picks up the response automatically.
This makes custom actions two-way. The AI sends data to your system, gets something back, and acts on it.
What your webhook should return
Return a JSON response with the data you want the AI to reference. The AI extracts fields like:
- id — A reference number (return request ID, claim number, ticket ID)
- url — A link to share with the customer (return label, tracking page, portal link)
- status — The result of the operation ("approved", "created", "pending")
Any other fields in the response are also available. The AI reads the full response body.
Example webhook response:
{
"id": "RET-12345",
"status": "approved",
"label_url": "https://labels.example.com/return/RET-12345"
}
Pair with guidance rules
The AI will try to use response data on its own, but for consistent results, add a guidance rule that tells the AI
exactly what to do with the response.
Example guidance rule instruction:
After creating the return label, share the label URL from the response with the customer. Include the return ID for their reference.
This removes guesswork. The AI knows to pull specific fields from the response and include them in its reply.
Example: Return labels with response data
Scenario: Customer requests a return. The AI creates a return label via your automation platform, gets back a label URL
and tracking number, and shares them in the conversation.
Step 1: Set up a webhook in your automation tool
Create a webhook in Make, n8n, or Zapier that:
1. Receives the order number and return reason
2. Calls your shipping provider (EasyPost, ShipStation, etc.) to create a return label
3. Returns the label URL and tracking info in the JSON response
Your webhook response should look like:
{
"return_id": "RET-78901",
"label_url": "https://labels.easypost.com/abc123.pdf",
"tracking_number": "1Z999AA10123456784",
"status": "created"
}
Step 2: Create the custom action
- Action name: Create return shipping label
- When to use this action: When a customer needs to return an item and the return has been approved
- Method: POST
- URL: Your automation webhook URL
- Parameters:
- order_number (string) — "The order number for the return"
- reason (string) — "The customer's reason for returning the item"
Step 3: Add a guidance rule
Create a guidance rule for return requests with this instruction:
After creating the return label, share the label URL and tracking number from the response with the customer. Include the return ID for their reference.
Result: The AI sends the customer a message with their return label link, tracking number, and reference ID, all pulled
directly from the webhook response.
Example: Log to Google Sheets
Log conversation data to a Google Sheet using Google Apps Script. Great for tracking shipping issues, refund requests,
feature requests, or any data you want to collect from conversations.
⚠️ Note: Google Workspace accounts have restrictions on POST requests to Apps Script. If you're using a company Google
account, use the GET method instead.
For a complete step-by-step guide, see Build a shipping issues tracker with custom actions.
Example: Zapier webhook for address updates
Scenario: Send a notification to Zapier when a customer updates their shipping address after an order ships.
Step 1: Create a Zap in Zapier
1. Go to Zapier and create a new Zap
2. Choose Webhooks by Zapier as the trigger
3. Select Catch Hook
4. Copy the webhook URL Zapier gives you
5. Add your desired action (send email, update spreadsheet, notify Slack, etc.)
Learn more about Zapier webhooks →
Step 2: Create the custom action in Commslayer
- Action name: Notify address change post-fulfillment
- When to use this action: When customer asks to update their shipping address and the order is already fulfilled or
shipped
- Method: POST
- URL: Paste your Zapier webhook URL here
- Headers: (none needed for Zapier)
- Parameters:
- order_number (string) — "The order being updated"
- new_address (string) — "The new shipping address the customer provided"
- event (string) — "Always 'address_change_post_fulfillment'"
Example: n8n workflow for loyalty points
Scenario: Add loyalty points in your rewards program when a customer leaves a product review.
Learn more about n8n webhooks →
Configuration:
- Action name: Add review loyalty points
- When to use this action: After customer confirms they've left a product review or provides their review rating
- Method: POST
- URL: Paste your n8n webhook URL here
- Headers:
- Authorization: Bearer your-api-key (replace with your actual key)
- Parameters:
- points (number) — "Points to award, e.g. 100"
- reason (string) — "Always 'product_review'"
Limitations
Custom actions are designed for simple HTTP integrations. Not supported:
- OAuth authentication — Use API keys or basic auth instead
- GraphQL or SOAP — REST APIs only
- Incoming webhooks — Only outbound requests from Commslayer
- Multi-step workflows — Use Zapier or n8n for complex logic
- File attachments — Text/JSON payloads only
For complex integrations, send a webhook to Zapier or n8n and build your workflow there.
Troubleshooting
Action not triggering?
- Check the "When to use this action" description — is it specific enough?
- Add a guidance rule that explicitly tells the AI to use the action
- Test in the AI Playground to see if the AI recognizes the trigger
- Verify the action is enabled (toggle is on)
Request failing?
- Check the URL is correct and accessible from the internet
- Verify authentication headers are correct
- Look at your receiving system's logs for error details
- If the URL points to a local or internal network address, it will be blocked for security reasons
Request timing out?
- The default timeout is 10 seconds — if your endpoint takes longer, it will fail
- Check if your receiving system is responding slowly
- For slow endpoints, consider using a webhook service like Zapier that responds immediately and processes in the
background
Action auto-paused?
- Actions that fail repeatedly get automatically paused to prevent spam
- Check the execution logs to see what's failing
- Fix the underlying issue, then re-enable the action
Missing data in request?
- Write clear parameter descriptions so the AI knows what to extract
- If you need order details, the customer needs to provide an order number first
- Check the execution logs to see what data was actually sent
AI not using response data?
- Make sure your webhook returns a JSON response with a 200 status code
- Add a guidance rule that tells the AI specifically what to do with the response
- Check that the response body contains the fields you expect (test with the playground)