Custom API

Configure a Custom API action to call an API connection, use the response in a conversation, and optionally show an interactive widget.

Custom API lets your agent call your API during a conversation. For example, it can look up an order when a visitor gives an order number, or create a record in your system and use the response in its answer. You can also show an enabled interactive widget after a successful JSON response.

You can add several Custom API actions to one agent, one for each task. The actions list shows each one by its Action name.

To add one, go to Build > Actions, select Create action, and select Custom API. A new action starts turned off. Select an API connection and save the action to turn it on.

How it runs

1. A visitor’s message matches the action’s When to use text. See Trigger Conditions.
2. If a required input field is missing, the agent asks the visitor for it. Their answer completes the action on their next message. The agent never makes up a value.
3. Chatvox sends the request through the selected API connection, filling in any variables. While it waits, the visitor sees your While it runs message, such as “Looking up your order…”.
4. The agent answers using the API response in plain words. It does not mention internal details, such as record types or status codes, unless they help the visitor, like an order number.

Details

• Action name: a short name, such as “Check order status”.

• What it does: a short description of the result the visitor gets, such as “Sends the visitor’s idea to the team”.

• When to use: what the visitor wants, in plain language. Do not list the details the action needs; make them required input fields instead:

  When the visitor wants to know where their order is, or when it will arrive.

• While it runs: a short message visitors see on the web widget and Public Chat while the request runs, such as “Looking up your order…”. Leave it empty to show “Working on it…”. Up to 80 characters. Visitors never see the action’s name.

API connection and request

The Endpoint card combines a saved API connection with the request details:

• API connection: the connection for this agent. It supplies the base URL, authentication, and headers. See API connections to create or manage one.
• Method: GET, POST, PUT, PATCH, or DELETE.
• Path and query: the endpoint path, such as /orders/{{order_number}}. Chatvox adds it to the connection’s base URL. Put query parameters here or add them through Send fields as.
• Send fields as: JSON body or Query params. GET requests always use query parameters.
• Request body (optional): a JSON body for methods other than GET. See Request body.
• Timeout (ms): how long to wait for a reply, from 1,000 to 15,000 milliseconds.

Input fields already used in the path are not sent a second time as request fields. When you set a request body, use placeholders to include input values.

Input fields

Input fields are the values the agent collects from the conversation and sends with the request. Select Add field and fill in:

Variables

Variables put values into Path and query, the selected connection’s header values, and the Request body (optional). Write them in double braces, such as {{order_number}}.

• Built-in values come from the conversation, never from the agent. The agent cannot change {{contact.email}}, for example.
• Values in the path and query are encoded for you, so a value like A/1 does not break the request.
• A variable with no value becomes empty text, or null in the request body.
• Keep variables out of the URL host, such as https://{{site}}.example.com. The API connection sets the host.

Request body

When Send fields as is JSON body, leave Request body (optional) empty to send the input fields as a JSON object, such as {"order_number": "A-1234"}. With Query params, Chatvox sends the fields in the URL. GET requests always use query params. If you enter a request body, Chatvox sends it as JSON as well.

To send your own shape, write it as JSON with variables:

{
  "order": "{{order_number}}",
  "quantity": "{{quantity}}",
  "customer": { "email": "{{contact.email}}" },
  "note": "Sent from {{page.url}}"
}

• A value that is only a variable keeps its type. With a Number field, "{{quantity}}" is sent as 3, not "3".
• Text around a variable is kept, as in "Sent from {{page.url}}".
• When you set a request body, input fields only reach your API through variables.

Authentication and shared headers are configured on the API connection. Use a key with only the permissions this action needs. Chatvox sends the request when a visitor triggers the action.

Response

Tell Chatvox how to read your API’s reply:

• Response format: JSON, or Text for plain-text replies. With Text, the agent sees the first 2,000 characters.
• Success path: where the success flag is, such as success. Leave it empty to use the HTTP status: any 2xx status means success.
• Message path: where a human-readable message is. Leave it empty to use message.
• Data path: where the data is. Leave it empty to use data, or the whole response if there is no data.

Paths use dots for nested values, such as order.status. For example, with this response, the paths are success, message, and data:

{
  "success": true,
  "message": "Order found",
  "data": { "status": "Shipped", "eta": "Friday" }
}

Return only what the agent needs. Smaller responses give more accurate answers.

What the AI can see

For JSON responses, What the AI can see controls which response data the agent receives:

• All fields: the agent receives all mapped data and the mapped message.
• Only selected fields: select Add field path under Fields the AI can see and enter each path. The agent receives only those paths from the data selected by Data path, along with the request status and success result. It does not receive the mapped message.

For example, if Data path is data and the response is:

{
  "data": {
    "order": {
      "status": "Shipped",
      "tracking_url": "https://example.com/track/A-1234"
    }
  }
}

Enter order.status to give the agent only the status from that data. The widget uses its own declared fields. It can still show order.tracking_url if it declares that field. This setting does not restrict the widget.

Widget

In the Widget card, select a widget belonging to this agent, or select No widget to leave the reply without a card.

Select Edit widget to change the selected widget, or Create widget to build one. Both open a new tab. The widget list refreshes when you return to the action tab. See Building widgets and the product search example.

The enabled widget appears under the reply after a successful JSON response. It does not appear after a failed request or a Text response. Send test request does not show the widget. Test the complete reply in the Playground. You can also set a widget’s When to show condition to show it on its own; see Trigger Conditions.

Map fields

When you select a widget, the Map fields section appears under the widget selector. It controls where each widget field comes from in the API response.

Empty rows use the response key with the same name. If your API response keys do not match your widget fields, map each field to its path in the response data (relative to Data path). Dot paths map whole values; transforming individual items inside a list is not supported.

To fill mappings with AI, select Suggest mapping. Suggest mapping requires sending a test request first so sample response data is available. It uses AI once, consumes a few credits, and suggests paths for your widget fields. Suggested paths show a Suggested badge until edited. If credits are insufficient, an error appears: Not enough credits to suggest a mapping. If the request fails, the action shows Couldn’t suggest a mapping. Try again. Changes to mappings are saved when you save the action.

Example mapping table for an order lookup action:

Widget data combines the default example, action inputs, and mapped API response, in that order. Later values override earlier values. Visitors receive only the fields declared by the widget. See Widgets.

Test it

Use the Test card:

1. Fill in sample values for the input fields.
2. Select Send test request.
3. Check the result the agent receives. It includes the success result, HTTP status, and data. With All fields, it also includes the mapped message. With Only selected fields, check that the data contains only your selected paths.

The test uses your unsaved changes, so you can fix the URL or paths and test again before saving. Built-in variables, such as {{contact.email}}, are empty in a test.

Then try it in a conversation. The Playground runs actions as your web widget would, or you can use your live web widget or Public Chat. Start with a message that leaves out the details, such as “Where is my order?”, and check that the agent asks for them.

Limits

• The API connection’s base URL and the request must use HTTPS and reach a public internet address. Local and private addresses, such as localhost or 192.168.x.x, are blocked.
• Redirects are not followed.
• Responses can be up to 1 MB.
• Requests time out after the Timeout (ms) you set, up to 15 seconds.

Examples

Check an order’s status

Look up an order in your store’s API.

Visitor: Where is my order?

Agent: I can check that. What is your order number?

Visitor: A-1234

Agent: Order A-1234 has shipped and should arrive on Friday.

Send an idea to your team

Save visitor ideas as drafts in WordPress, with the details your team needs to follow up. This uses the WordPress REST API with an application password.

Request body (optional):

{
  "title": "{{title}}",
  "status": "draft",
  "content": "{{details}}\n\nFrom: {{contact.email}}\nConversation: {{conversation.id}}\nPage: {{page.url}}\nCampaign: {{utm.campaign}}"
}

Visitor: Hi, I have an idea for the team.

Agent: What is your idea?

Visitor: A Mailchimp integration, so captured leads sync to our newsletter list.

Agent: Thank you. I have sent your idea to the team as “Mailchimp integration for captured leads.”

The draft includes the page the visitor was on and the campaign that brought them, so your team has the context.

Request a callback

Create a callback request in your CRM, and keep the conversation and campaign with it.

Request body (optional):

{
  "phone": "{{phone}}",
  "best_time": "{{best_time}}",
  "conversation_id": "{{conversation.id}}",
  "source": "{{utm.source}}",
  "campaign": "{{utm.campaign}}"
}

Troubleshooting

Start by sending the same message in the Playground and reading the reply’s action steps: they show whether the action ran, what it sent and received, and why it did not run.

Channels

Select where the action runs: Web widget, Public Chat, WhatsApp, and API (conversations started through the REST API). All four are on by default. The API request can run on each enabled channel, but an enabled widget appears only in the web widget, Public Chat, and Playground. Custom API and MCP Server are the only actions that can run in API conversations. See Where actions run.