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

Go to AI agent → Actions
Click the Custom actions tab
Click + Custom action
Fill in the action details (see below)
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

Values in the URL

If the API needs an ID in the address, put a parameter name in double curly braces in the path or the query of API endpoint URL, for example https://api.example.com/orders/{{order_id}} or https://api.example.com/returns?order={{order_number}}. The AI agent fills it in on every run.

Add a parameter with the same name and a clear description so the AI agent knows which value to use. A value in the URL is always required.
{{conversation.id}} and {{conversation.display_id}} work in the URL too.
Variables only work after the domain. A URL like https://{{shop}}.example.com can't be saved.
Spaces and special characters in the value are encoded, so they don't break the URL.
A parameter used in the URL isn't sent again in the request body or query.

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

You can also pass conversation details as parameters using these values:

conversation.url — The direct link to the conversation in Commslayer
conversation.display_id — The human-readable conversation number (e.g., #1234)
conversation.id — The internal conversation ID

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:

Click Test in the Actions page header
The AI Playground opens
Simulate a conversation that would trigger your action
Check your receiving system (Zapier, n8n, etc.) to verify the request arrived

Test with real data in the playground before enabling for live conversations.

Logs

Every run of a custom action is logged with the request that was sent and the response that came back.

Go to AI agent → Actions and open the Custom actions tab.
Click Logs on the action's card. The top of the log shows the number of runs, the success rate and how many runs succeeded, failed, timed out or are pending.
Filter by Success, Failed, Timeout or Pending, and pick a time range from Last hour to Last 30 days. The list opens on Last 24 hours.
Click a run to open Execution details. Request shows the endpoint, headers and payload. Response shows the status code, the error and the body. The Conversation column tells you which conversation the run belongs to.

Good to know:

Secrets are hidden. Header and payload values such as API keys and tokens show as "[REDACTED]".
Very long response bodies are cut off.
Inside a conversation, click the AI agent's summary line (for example Ran 3 actions) and open the step to see the values the AI agent sent and the HTTP status code. The full request and response are only in Logs.
A run that failed and then went through on an automatic retry shows success with "Succeeded on retry 1" (or 2, 3) next to it. The error from the failed attempt is under Earlier attempt.
If the URL uses variables, Request shows the URL that was called, with the values filled in. Secrets stay hidden.

When a request fails

Commslayer retries a failed request automatically. The AI agent mentions the queued retry in a private note.
If the action only keeps a record for your team, such as a log entry or a Google Sheet row, the AI agent doesn't mention the failure to the customer and doesn't hand over because of it. If the request won't be retried, it leaves a private note so a teammate can redo it.
If an action the customer is waiting on fails, such as a refund, the AI agent follows your guidance for failed actions or hands the conversation to your team.
The same request with the same details isn't sent twice within 30 seconds. The AI agent uses the result of the first one.

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:

Receives the order number and return reason
Calls your shipping provider (EasyPost, ShipStation, etc.) to create a return label
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

Go to Zapier and create a new Zap
Choose Webhooks by Zapier as the trigger
Select Catch Hook
Copy the webhook URL Zapier gives you
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
If the URL uses a variable such as {{order_id}} and the AI agent had no value for it, the run fails and isn't retried. Make the parameter's description clearer, or add guidance that tells the AI agent to get the value first, for example by asking the customer for the order number.

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?

A custom action that fails several times within a few minutes is paused for a short time and then resumes by itself. Its toggle stays on, so there is nothing to re-enable.
Click Logs on the action's card to see what is failing, then fix the URL, the headers or your receiving system.

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
Click Logs on the action's card and open the run to see the payload that was sent. See "Logs" above.

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)

Connect AI agent to external systems with custom actions

When to use custom actions#

Creating a custom action#

Action settings#

Action name#

When to use this action#

API configuration#

Method#

URL#

Headers#

Parameters#

Triggering custom actions reliably#

Testing custom actions#

Logs#

When a request fails#

Using webhook response data#

Example: Return labels with response data#

Example: Log to Google Sheets#

Example: Zapier webhook for address updates#

Example: n8n workflow for loyalty points#

Limitations#

Troubleshooting#

Related articles