Skip to main content
An HTTP tool is an HTTP request the assistant can call during a conversation. You define the request — method, URL, headers, and parameters — and the assistant fills in the parameters and calls it when a shopper’s question matches. A common example is looking up an order’s status from your backend and answering with the result.
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 helps the assistant decide when the tool is relevant, so be specific.
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, or DELETE.
  • 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, and PATCH) — 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.
You can also adjust the request timeout (the maximum time to wait for the external API to respond).
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

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.
A test makes the real outbound request to your endpoint. Test against a safe endpoint and avoid running tools that perform unintended writes.
7

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.
Always test a tool before assigning it. An assigned tool can be called automatically during live chats, so make sure the endpoint behaves as expected and never performs unintended writes.

​
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.