Create and test an API tool

An API tool lets the Agent look up an order status or create a callback request in your CRM, for example. To set one up, you need the connected service’s documentation and credentials.

For a complete example with an input schema, tool description and conversation flow, see Service request intake.

1. Define the request

Under Actions → Tools, add HTTP API request. Give it a clear name and execution description, then set the method, URL, timeout and required headers.

Example setting	Value
Name	create_callback_request
Method	POST
URL	https://api.example.com/callbacks
Content type	application/json
Background execution	Off when the caller needs confirmed success

Replace the example URL with your service’s endpoint. Use the method and fields from its API documentation and select the matching credentials. You can start with an integration template if one is available.

2. Describe the inputs

Use the schema editor to define path, query and body inputs. For a callback body:

Field	Type	Required	Description
name	String	Yes	Confirmed caller name
reason	String	Yes	Reason for the callback
phone_number	String	Yes	Confirmed callback number

Mark only the fields your service needs as required. Check their types. The boolean false and the text "false" are different inputs.

{
  "name": "Example Caller",
  "reason": "Question about the service",
  "phone_number": "CONFIRMED_E164_NUMBER"
}

Replace the phone placeholder with a controlled test number before sending. The prompt and tool description should require confirmation before creating the request.

3. Control the response

Choose Original response, Mapped response or JEXL script to determine what the Agent receives. Response mapping can remove irrelevant fields and normalize the result.

For longer requests, enable a progress message so the Agent can let the caller know it is checking the details. It should confirm the result only after the service responds.

4. Test in the editor

Use the tool test panel with form inputs or raw JSON where offered. Check the types, required inputs and request preview. Running the request contacts the real endpoint and can create or change records.

Compare the original API response with the processed response for the Agent. Use sample JSON in the preview to check changes to a mapping or script without sending the request again.

5. Assign and test a call

Assign the saved tool to the intended Agent. Test complete inputs, missing inputs and an API failure. Confirm the downstream record and the Agent's final statement. Keep Run in background off if the conversation must wait for success.

For lookup at call start, use pre-processing. For delivery after the call, use post-processing.