How Do You Connect a Custom Tool (Any API) to Your Zendesk AI Agent?

To connect a custom tool to a Zendesk AI agent in Macha, open Custom Tools, click Create Custom Tool (or Build with AI), give it a label, a description, an HTTP method and URL, and an auth type, test it against the live endpoint, then toggle it on in the agent's Tools section. Any HTTP API works: GET, POST, PUT, PATCH or DELETE, with Bearer, API Key, Basic or no authentication.

What is a custom tool, and how is it different from a connector?

A connector is a pre-built integration Macha maintains. A custom tool is one you define: a single HTTP endpoint, wrapped so an agent can call it exactly like a built-in tool. Once it's saved, any agent you allow can use it — to look up a record, kick off a job, send a message, whatever the endpoint does.

An agent can only use tools that have been explicitly assigned to it, so creating a tool doesn't hand it to every agent automatically.

It's an org-level resource: you build it once, then assign it to as many agents as you like.

Is there a video walkthrough?

What are the two ways to build a custom tool?

From the Custom Tools tab you have two options, both top-right:

• Create Custom Tool — configure it manually (full control).
• Build with AI — the AI Tool Builder (powered by Sidekick) walks you through it conversationally and tests it for you.

We'll cover the manual way in detail, then the AI way.

How do you build a custom tool manually?

Click Create Custom Tool and you get a single form with everything the endpoint needs — Label, Description, Method and URL, Read vs. Write, Authentication, Static Headers, Response Mapping, and Parameters:

Fill in the pieces:

1. Label. The name the AI sees (e.g., get_shipping_status). Keep it clear and action-oriented.

2. Description. What the tool does — "Look up the shipping status and tracking link for an order by order number." This matters more than it looks: the agent reads the description to decide when to use the tool, so a vague description means the agent uses it at the wrong time (or not at all). Be specific about what it does and what it needs.

3. Read or Write. Mark tools that only fetch data as Read. Mark anything that creates, updates or deletes as Write: Write tools ask for user confirmation before they run in chat.

4. Method + URL. Choose the HTTP method (GET, POST, PUT, PATCH or DELETE) and enter the endpoint URL. You can drop {{placeholders}} into the URL for values the agent fills in at call time — e.g. https://api.yourco.com/orders/{{order_id}}/shipping.

5. Authentication. Pick the auth type — Bearer, API Key, Basic, or None — and enter the details (for an API key, the header name and the key). Credentials are encrypted at rest and never exposed to the AI model.

6. Parameters and body. Define each parameter the agent supplies (name, type, description, required or not). For POST, PUT and PATCH, add a JSON body template, again with {{placeholders}} for the values the agent supplies.

7. Response mapping. Use a dot path (for example data.results) to tell Macha which part of the response to hand back, so the agent gets clean data instead of a raw blob.

8. Group (optional). Give the tool a group with a name, icon and color. Groups also show up as custom connectors on the Connectors page.

9. Test it. Use the Test button to enter sample values, fire a real call and confirm it works before an agent ever uses it. Get the test passing, then save.

That's the whole manual flow: label and describe it, point it at the endpoint, add auth, map the response, test, save.

How does the AI Tool Builder set up a tool for you?

If wiring auth headers and response mappings by hand isn't your idea of fun, let Sidekick do it. Build with AI is Sidekick — clicking it opens the Sidekick panel scoped to building a tool, with starters like "Connect Postmark for transactional email" or "Hook up a custom internal API."

Describe the API in plain language — "Connect our Postmark account so agents can send email" — and the AI Tool Builder walks through the method, URL, auth, parameters, and body, tests it against the live API, and saves the tool. It works best when you paste the API documentation URL or a few example endpoints. Because it captures the working configuration from a successful test, you skip the trial-and-error of getting headers and mappings exactly right. (The AI Tool Builder is on every plan; see Sidekick.)

How do you add the tool to your Zendesk agent?

A custom tool isn't doing anything until an agent can use it. Open the agent you want to give it to, go to its Tools section, and toggle on the new custom tool — it appears right alongside the built-in Zendesk, Shopify, and other tools. Now, when the agent decides it needs that capability (based on the description you wrote), it can call your endpoint as part of resolving a ticket.

For example: add get_shipping_status to your support agent, and a "where's my order?" ticket can now be answered with live data from your shipping system — not just the connectors Macha ships with.

What can a custom tool do for a support team?

• Internal systems — your order, billing, or account API, so agents answer with first-party data.
• Tools without a built-in connector — anything with a REST endpoint becomes available.
• Trigger jobs — POST to an internal endpoint to kick off a refund, a re-ship, or a provisioning task.
• Enrichment — call a data provider to add context before the agent replies.

What does a worked example look like?

Say you have an internal endpoint GET https://api.yourco.com/orders/{{order_id}}/shipping that returns an order's status and tracking link. To let your support agent use it:

1. Custom Tools → Create Custom Tool.
2. Label: get_shipping_status. Description: "Get the shipping status and tracking link for an order by its order number. Use this for 'where is my order' questions."
3. Method / URL: GET, https://api.yourco.com/orders/{{order_id}}/shipping.
4. Auth: API Key — header Authorization, your key.
5. Response mapping: return status and tracking_url.
6. Test with a real order ID, confirm it returns the right data, and Save.
7. Open your support agent → Tools → toggle on get_shipping_status.

Now a "where's my order?" ticket gets answered with live data from your own system: the agent reads the order number from the ticket, calls your endpoint, and replies with the status and tracking link — fully autonomously if you've set a trigger.

Which Macha plan includes custom tools?

Macha has one plan, priced by ticket volume from $299 a month for up to 750 tickets, and custom API tools are included in it. There's no higher tier to buy for them. Agents and seats are unlimited too, so you can hand the same tool to as many agents as you like. The trial is $50 of free usage, no credit card required.

What are the best practices for custom tools?

• Write the description for the AI. It's how the agent decides when to call the tool — be specific.
• Test before you ship. Use the built-in test endpoint and confirm a real call works.
• Scope auth tightly. Use a key with only the permissions the tool needs; credentials are encrypted, but least-privilege still matters.
• Be deliberate with write actions. A tool that changes something (a refund, a cancellation) should be marked Write so it asks for confirmation in chat, and kept on agents that confirm before acting.
• Group your tools so the list stays manageable as you add more.

Frequently asked questions

What's the difference between a connector and a custom tool? A connector is a pre-built integration Macha maintains (Zendesk, Shopify, etc.). A custom tool is one you define from any API endpoint.

What do I need to connect a custom tool? An API endpoint, its method and URL, and the authentication details. That's it.

Do I have to configure it by hand? No — the AI Tool Builder (Build with AI) walks through it conversationally and tests it for you.

How does the agent know when to use the tool? From the description you write. A clear, specific description is the single most important field.

Can the same tool be used by multiple agents? Yes — it's an org-level resource; assign it to any agent via the Tools toggle.

Which HTTP methods and auth types are supported? GET, POST, PUT, PATCH and DELETE, with Bearer, API Key, Basic or no authentication. Credentials are encrypted at rest and never shown to the AI model.

Is it worth building a custom tool?

Yes, if an agent keeps escalating tickets because it can't see data in one of your systems. Custom tools mean your agents aren't limited to the apps in Macha's catalog. If it has an API, your agent can use it Build it by hand for full control, or by chat with the AI Tool Builder. Describe it well, test it, add it to your agent, and a Zendesk ticket can now reach straight into your own systems.

Give your agent a new capability: connect a custom tool from any API in minutes. $50 of free usage, no credit card required. Start free.