Set up custom tools for Captain

Discover

Custom tools let the assistant call your own systems during a conversation, for example to check an order, a warranty or a booking, instead of handing off.

Plan & access: Business or Enterprise (Pricing & Plans). On Startups, Tools usually shows Upgrade to use tools with Captain. Each assistant has its own list of tools. Administrators create tools, and only administrators can see the saved credentials. Self-hosted: the Super Admin turns on Custom Tools for the account.

Set up & try

Before you start

• An HTTPS endpoint on a public hostname. Chatwoot blocks plain HTTP, IP addresses, localhost, private networks and .local addresses.

• The endpoint must accept the connection within 2 seconds and answer within 20 seconds, with a response of 1 MB or less.

• Its credentials, if it needs any.

Create a tool

1. Go to Captain > Tools and click Create a new tool. First use the assistant switcher at the top to choose the assistant the tool is for. The form opens in a side panel.

   

2. Fill in:

   • Tool Name: short, for example "Order Lookup" (55 characters or fewer).

   • Description: when the assistant should use it, written like a briefing for a new agent. This decides whether the assistant picks the tool.

   • Method: GET to read data; POST, PUT or PATCH to send or change data; DELETE to remove something.

   • Endpoint URL: use {{ parameter_name }} for values the assistant fills in, for example https://api.example.com/orders/``{{ order_id }}.

   • Authentication Type: None, Bearer Token, Basic Auth, or API Key (with Header Name and Header Value). Use this for credentials.

   • Headers: click Add Header for fixed headers your API needs on every call, such as an API version or tenant ID (up to 16). Values are sent exactly as typed. Chatwoot sets Authorization, Host, Content-Length, Content-Type and any header starting with X-Chatwoot itself, so you cannot add those.

   • Parameters: click Add Parameter for each value the assistant should get from the customer. Give a name, type, description, and mark Required if needed.

   • Request Body Template (Optional): for POST, PUT or PATCH. This and the response template are under Templates. The request template is a JSON body. It supports Liquid, for example {{ order_id }} for a parameter.

   • Response Template (Optional): pick out the fields the assistant needs, for example Order {{ response.order_id }} status: {{ response.status }}. Read the API reply through response, for example {{ response.status }}. Leave the template blank to send Captain the raw JSON.

     

   

3. Click Test connection, then Create.

   

Test connection works only for endpoints without templates or a request body. For others, test in the Playground. A green result means your endpoint returned a 2xx status: it is reachable and accepted the credentials.

Test it

Ask a question in the Playground that needs the tool, for example "Where is order 1234?". Check the reply uses real data.

Get value

• Custom tools work best for lookups with clear inputs, such as an order status, a booking or a record by ID.

• Each assistant can have up to 50 tools. Keep the list short anyway: with many tools the assistant is more likely to pick the wrong one.

• Adding, editing, turning off or deleting a tool changes it only for the assistant you are viewing. Tools that existed before tools became per-assistant were copied to every assistant, so check each one.

• Running several assistants? Give each only the tools it needs.

• Turn a tool off with its toggle instead of deleting it. If a scenario uses it, Chatwoot warns you first. See Set Captain's guardrails, guidelines and scenarios.

• Chatwoot sends headers with each call so your system knows the account, conversation, contact email and phone, assistant, and whether the contact is verified. For private data, check the X-Chatwoot-Contact-Inbox-Verified header before answering. Without identity validation, a visitor can type any email into the widget. Tools that return only public data do not need this check. See How to enable identity validation in Chatwoot?.

• If your API returns text written by customers, return only the structured fields you need. Captain reads the reply as-is, so free text can contain instructions it might follow.

Troubleshoot

More causes: Troubleshoot Captain.