HTTP Tool are configured at the organization level and then assigned to the assistants that should use them. To keep API keys and OAuth out of the request, set up Secrets and Auth Connections first.
Create a tool
1
Open Tools
On the platform, go to Tools and select New tool. Choose HTTP Request, or start from a template such as Shipment tracking and adjust it.
2
Name and describe the tool
Under Configuration, give the tool a clear Name (for example,
Order status lookup) and a Description of when it should be used. The description tells the assistant when to trigger the tool, so be precise about the situation that should call it.Be as specific as possible — a vague description like “handles shipment tracking” gives the assistant little to work with. Prefer something like “use when the shopper gives an order number and asks for its status.”
3
Define the parameters
Under Parameters, add the inputs the request needs (such as
order_number). Use lowercase snake_case names. For each parameter, set a Data type and a Value type: either a Constant value that stays the same on every call, or a value the assistant fills in from the conversation. For assistant-filled values, you can also describe how it should obtain them.4
Configure the HTTP request
Under HTTP request, set:
- Method —
GET,POST,PUT,PATCH, orDELETE. - URL — the endpoint to call. Use
{parameter_name}placeholders to insert parameters, e.g.https://api.example.com/orders/{order_number}. - JSON body (for
POST,PUT, andPATCH) — a JSON template that can also use{parameter_name}placeholders. - Authentication — attach an Auth connection instead of putting credentials in the request.
- Headers (optional) — additional request headers as name/value pairs.
5
Select response fields (optional)
Under Response fields, choose which fields from the JSON response are passed to the assistant. Without a selection, the assistant receives the entire response.
6
Define response handling (optional)
Under Response handling, describe in plain language how the assistant should deal with this tool’s response. This is useful when the API returns terse or ambiguous values (such as
true/false or status codes) that would otherwise reach the assistant unexplained.For example: “true = in stock, false = sold out. Status 404 = the item does not exist.” The assistant receives this instruction together with the raw response and turns it into a clear answer for the shopper.7
Test the tool
Select Test tool, enter sample parameter values, and run it.
The request returns the status and data you expect. Fix the URL, headers, or parameters until the test response is correct.
8
Assign it to an assistant
Save the tool, then open the assistant that should use it and assign the tool from its Tools. The assistant can now call it during chats whenever the shopper’s question matches the tool’s description.
Security
Never paste secrets directly into a tool’s headers or URL:- Store API keys and other sensitive values as Secrets so they are kept encrypted and never exposed in plain text. See Settings › Secrets.
- Use an Auth connection when the tool needs authentication — Bearer, Basic, a custom header, or OAuth — to act against a third-party service. See Settings › Auth Connections.
Availability
Whether Tools are available, and how many HTTP tools you can create, depends on your plan. When you reach the limit, delete a tool you no longer need or upgrade your plan.Next steps
Secrets
Store API keys your tools reference securely.
Email tool
Let the assistant send emails from a verified sender.