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.

Available Integrations

Zendesk

Full-featured integration with 16 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, subject, tags, and custom fields, assign tickets.
• 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 Mini, 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 — Search Zendesk users by name, email, or role.

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

Your organization can connect multiple instances of the same connector type. For example, you might have two Zendesk accounts — one for your production environment and one for your sandbox, or separate accounts for different product lines.

How It Works

• Each connector instance has a unique name within your organization (e.g., "Production Zendesk" and "Sandbox Zendesk").
• 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.
• 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.

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.