Connecting Your Tools and Integrations

Connectors, Tools & Triggers Explained

What Are Connectors

Connectors are integrations that give your agents access to external tools and services. When you connect an integration like Zendesk, Freshdesk, or Shopify, Macha creates a set of tools that agents can use to read data, perform actions, and interact with those services on your behalf.

Each connector exposes a specific set of tools. You control which tools each agent has access to, so you can give a support agent full Zendesk access while restricting a reporting agent to read-only tools.

Read Tools vs Write Tools

Connectors Explained — Read Tools vs Write Tools

Every tool a connector exposes is either a read tool or a write tool. The distinction matters because it changes how safe a tool is to hand to an agent — especially one running autonomously.

Read Tools

Read tools fetch information without changing anything in your connected app. Examples:

• Shopify — search products, search orders, get a customer record, look up an order
• Zendesk — get ticket, search tickets, read attachments, search help center articles
• Google Workspace — read a Doc, read a Sheet

These are safe. The agent can use them freely without needing to ask you for anything.

Write Tools

Write tools make changes in your connected app — adding a public reply, updating a ticket status, posting an internal note, editing a custom field, creating a refund. These actually mutate data on the third-party tool.

In interactive chat, the agent always pauses and asks for confirmation before running a write tool. You see the proposed action, review it, and click confirm.

In autonomous mode (when the agent is running off a trigger), there is no human in the loop. Write actions execute immediately, with no confirmation step. This is by design — but it means you need to be deliberate about which write tools an autonomous agent can access.

Available Integrations

Zendesk

Full-featured integration with 17 tools for ticket management, image reading, custom fields, messaging, and help center content. Zendesk connects via OAuth or API key.

• Ticket management — Get ticket details, search tickets, update status, priority, type, subject, tags, and custom fields.
• Custom fields — Read all custom field values on a ticket with labels resolved from the field schema. Cached per connector.
• Replies and notes — Send public replies to customers or add internal notes for your team.
• Image vision — Read image attachments (JPEG, PNG, GIF, WebP) using AI vision. The agent downloads the image, encodes it, and sends it to a vision-capable model. Works with GPT-5, GPT-5.4, GPT-5.4 Mini, and Claude Sonnet.
• Attachments — Extract text from PDF, DOCX, XLSX, CSV, and TXT attachments.
• Messaging — Read and respond to Zendesk messaging (SunCo) conversations.
• Help Center — Search knowledge base articles with live webhook sync.
• Users and groups — Search Zendesk users by name, email, or role; list groups to route tickets to the right queue. Assign tickets to a specific agent, a group, or both.

Freshdesk

Comprehensive support platform integration with 15 tools. Freshdesk connects via API key and subdomain.

• Tickets — Get ticket details (including conversations and attachments), search tickets with filter-based query syntax.
• Contacts — Search and look up customer contact information.
• Knowledge Base — Search help center articles.
• Actions — Add public replies, add internal notes, update priority, status, tags, and custom fields, assign tickets.
• Team — List agents and groups for assignment workflows.
• Attachments — Read attachment contents (supports PDF, DOCX, XLSX, CSV, and TXT text extraction).

Shopify

E-commerce integration for products, orders, customers, and more. Shopify connects via OAuth through the Macha AI app.

• Products — Search your product catalog with variants, pricing, and inventory data.
• Orders — Get order details, search orders by various criteria, and view order history for specific customers.
• Customers — Look up customer profiles and their order history.
• Discounts — View active discount codes and promotions.
• Refunds — Create refunds (requires human confirmation before executing).

Slack

Messaging integration for team communication. Slack connects via OAuth.

• Messaging — Send messages to channels and respond to conversations.
• App mentions — Agents can respond when mentioned in Slack channels.
• Direct messages — Handle direct messages sent to the Macha Slack app.

Stripe

Payment and billing integration. Stripe connects via API key.

• Customers — Search and look up customer records.
• Payments — View payment history, charges, and payment methods.
• Invoices — Retrieve invoice details and payment status.
• Subscriptions — View subscription details and status.

Google Workspace

Integration with Google Docs and Sheets. Google connects via OAuth. Documents are selected using Google Picker — you choose which files your agents can access.

• Read Google Doc — Read the full content of a Google Doc.
• Read Google Sheet — Read data from a Google Sheet, all sheets or a specific range.

Confluence

Integration with Atlassian Confluence for searching and managing documentation. Confluence connects via API token.

• Search Pages — Search Confluence pages by keyword across spaces.
• Get Page — Read the full content of a Confluence page.
• List Spaces — List available Confluence spaces.
• Get Page Children — Navigate page hierarchies.
• Create Page — Create a new page in a space (with confirmation).
• Update Page — Update an existing page (with confirmation).
• Add Comment — Add a comment to a page (with confirmation).

Note: Confluence API tokens expire. When connecting, enter the expiry date you chose in Atlassian. Macha will notify you 30 days before it expires so you can regenerate it.

Notion

Knowledge management integration. Notion connects via OAuth.

• Pages — Read Notion page content.
• Search — Search across your Notion workspace.

Airtable

Database and spreadsheet integration. Airtable connects via API key or OAuth.

• Records — Read, search, and manage records in Airtable bases.
• Tables — Access table structure and metadata.

OAuth vs. API Key Setup

Connectors use one of two authentication methods:

OAuth (Authorization Flow)

Used by: Zendesk, Shopify, Slack, Google Workspace, Notion.

With OAuth, you click an "Authorize" button that redirects you to the external service. You log in there (if not already), review the permissions Macha is requesting, and click "Allow" or "Approve." You are then redirected back to Macha with the connection established. No API keys or credentials to copy.

API Key / Credentials

Used by: Freshdesk, Stripe, Airtable.

With API key authentication, you enter credentials directly in Macha. Each connector's setup form includes step-by-step instructions on where to find the required keys in the external service. For example, Freshdesk requires your API key (found in Profile Settings) and your subdomain.

Multi-Instance Connectors

Connect Multiple Accounts of the Same App

Your organization can connect multiple instances of the same connector type. For example, you might run two Google Workspace accounts — one for the main company and one for a separate team — or two Zendesk accounts (production and sandbox), or separate accounts for different product lines. You can connect both and let your agents use either one.

How It Works

• Each connector instance has a unique name within your organization (e.g., "Production Zendesk" and "Sandbox Zendesk", or "Google Main Company" and "Google Europe Team").
• When you assign multiple instances of the same connector type to an agent, Macha automatically disambiguates the tool names. A tool like zendesk_get_ticket becomes zendesk_get_ticket__production and zendesk_get_ticket__sandbox. Similarly, a single read_google_doc becomes two distinct tools — one per connected Google account.
• Tool descriptions are also prepended with the account name (e.g., "[Account: Production]") so the AI model knows which instance to use.

This disambiguation is automatic — you do not need to configure anything beyond giving each connector instance a distinct name.

Name Your Connectors Clearly

The clearer your connector names are, the more reliably your agent picks the right one. Avoid generic names like "Google Workspace 1" and "Google Workspace 2" — instead use meaningful names that describe what the account is for ("Google Main Company", "Google Europe Team", "Production Zendesk", "Sandbox Zendesk").

You can also reference these names directly in your agent's instructions. For example: "Always use Google Main Company for internal documents and Google Europe Team for anything related to that team. If unsure, search both."

Built-In Connectors

Some connectors are always available without any setup or authentication.

File Tools

The File Tools connector is built into Macha and requires no connection. It gives agents the ability to generate files on demand:

• Create Spreadsheet — Generates an Excel (.xlsx) file.
• Create CSV — Generates a CSV file.
• Create PDF — Generates a PDF document.
• Create Document — Generates a Word (.docx) document.

Each tool creates the file and returns a download URL. You will see the File Tools connector on your Connectors page with a purple "Installed" badge instead of a "Connect" button.

Connector Setup Guides

Every connector in Macha includes a built-in setup guide visible in the connection modal. Here is a brief overview of what each connector requires:

• Zendesk — OAuth authorization. Click "Connect" and authorize through your Zendesk admin account.
• Freshdesk — API key (found in your Freshdesk profile under "Your API Key") and your subdomain (e.g., yourcompany from yourcompany.freshdesk.com).
• Shopify — OAuth authorization via the Macha AI app. You will need to enter your store domain first (e.g., your-store.myshopify.com), then authorize through Shopify.
• Slack — OAuth authorization. Click "Connect" and authorize through your Slack workspace.
• Stripe — Restricted API key. Create one in your Stripe Dashboard under Developers > API Keys with read-only permissions for the resources you need.
• Google Workspace — OAuth authorization. Click "Connect" and authorize with your Google account. Grant access to the services you want (Docs, Sheets, Drive, Calendar).
• Notion — OAuth authorization. Click "Connect" and select which Notion pages and databases to share with Macha.
• Airtable — Personal access token. Create one at airtable.com/account with access to the bases you need.