Custom HTTP Action
Custom HTTP Actions allow your assistant to interact with external REST APIs during a call. This enables powerful integrations like looking up a customer in your CRM, checking live inventory, or pushing lead data to your backend.
Configuration Flow
Setting up a custom action involves a 6-step wizard to ensure your API connection is secure and functional.
Connect to the API
Define how the assistant should talk to your server.
- Endpoint Method: Select from
GET,POST,PUT,PATCH, orDELETE. - Endpoint URL: Enter the full destination URL (e.g.,
https://api.yourcrm.com/v1/leads). - Headers: Add necessary HTTP headers like
Content-Type: application/json. - Timeout: Set how long (in ms) the assistant should wait for a response before failing.
Authentication
If your API is protected, toggle Authorization needed. You can provide credentials, tokens, or keys and specify if they should be sent via headers or query parameters.
Configure Variables
Map conversation data to your API request.
- Query Parameters: Add key-value pairs to the URL.
- Variables: Define default variables. You can reference call-time data by wrapping variable names in curly braces, like
<user_name>.
General Settings
Give your action a clear Name and Description.
Tip: Use a descriptive name like "Check Order Status" so the AI knows exactly what this action is for when deciding to trigger it.
Messages
Control what the assistant says while processing the request.
- Let the Assistant Speak Naturally: Toggle this on to let the AI handle the transition.
- Start Message: What the AI says right before calling the API.
- Delay Message: Spoken if the API takes longer than the "Delay threshold" (e.g., "One moment while I check that for you...").
- Failure Message: What the AI says if the API returns an error or times out.
Action Results
Initialize the action to see a live sample response. You can then select specific fields from the JSON response to use as variables later in the conversation.
Supported Methods
| Method | Badge | Typical Use Case |
|---|---|---|
| GET | GET | Fetching user data or verifying a status. |
| POST | POST | Creating a new lead or submitting a support ticket. |
| PUT/PATCH | PUT/PATCH | Updating an existing record or changing a status. |
| DELETE | DELETE | Canceling a booking or removing a record. |
Best Practices
- JSON Payloads: For
POSTandPATCHrequests, ensure your backend is configured to parse JSON bodies. - Variables: Use the Information Extractor before this action if you need to pass specific data (like a "Case Number") into the API URL or Body.
- Timeout Settings: Most voice interactions feel sluggish if the API takes more than 2-3 seconds. Keep your backend responses fast or use a "Delay Message."
Once an action is initialized in the Action Results step, the fields returned by your API become available as dynamic variables for other actions like Send SMS.
Ensure your API endpoint is publicly accessible. If you are testing locally, use a tool like ngrok to create a public tunnel to your local environment.