Chat actions
Let the agent call your HTTPS API from a conversation (Custom HTTPS).
Chat actions (Custom HTTPS)
On Agents → Actions, you can add a Custom HTTPS action so the agent can call your API during a conversation.
Other action types (Calendly, Cal.com, Slack, OpenAPI import, and similar) may appear as Coming soon — only Custom HTTPS is documented as available here.
What visitors experience
- The agent decides the action fits the conversation (based on your “when to use” description).
- Amplixa can collect configured input fields from the visitor.
- For mutating methods, the visitor confirms before Amplixa sends the request.
- Your API responds; Amplixa shows a success path or your configured failure message.
The embed never receives your API key. Amplixa stores it encrypted and sends it only on the server-side request.
Configure
- Agents → Actions → Add action → Custom HTTPS.
- Basics — name (tool slug), when-to-use, enabled.
- Collect — input fields (required for Amplixa form mode; optional for Custom request). You can map values from Collect leads context such as
contact.email,contact.name,contact.phone. - Request — body mode, URL, API key; Custom request also has method, headers, and body template with
{{var}}placeholders. - Failure — visitor-facing fallback if the call fails (default: “Sorry, we are unable to process this transaction.”).
- Save, then use Send test data to fire one real call with sample values.
Body modes
| Mode | Behavior |
|---|---|
| Amplixa form | Fixed POST envelope after confirm: { action, conversationId, fields, context } |
| Custom request | You choose method (GET/POST/PUT/PATCH/DELETE), URL/header/body templates |
Amplixa form request shape
POST https://your-api.example.com/amplixa/requests
Authorization: Bearer <the-key-you-saved>
Content-Type: application/json
Idempotency-Key: <conversationId:actionId:argsHash>{
"action": "submit_request",
"conversationId": "clx...",
"fields": {
"email": "[email protected]",
"requestType": "repair",
"summary": "Leaking tap in the kitchen"
},
"context": {
"contact.email": "[email protected]",
"contact.name": "Ada Lovelace"
}
}Success: HTTP 2xx with a JSON body your agent can surface (for example { "ok": true, "message": "…" }).
Validation style failures: HTTP 422 with a clear error. Other non-2xx use the configured fallback message with the visitor.
Custom request notes
- URL, headers, and body may include
{{field_key}}and{{contact.email}}(and similar). - Body templates for POST/PUT/PATCH must render to JSON.
- GET runs after required fields are collected (no confirmation gate).
- POST / PUT / PATCH / DELETE always ask the visitor to confirm first.
Security
- Use HTTPS. Amplixa blocks private / link-local / metadata hosts and does not follow redirects.
- Treat the stored key like any production secret; rotate it on your side if leaked.