Connectors

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 for ticket management, messaging, and help center content. Zendesk connects via OAuth.

• Ticket management — Get ticket details, search tickets, update priority, update status, assign tickets, add tags, and more.
• Replies and notes — Send public replies to customers or add internal notes for your team.
• Messaging — Read and respond to Zendesk messaging (SunCo) conversations.
• Help Center — Search knowledge base articles.

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, Sheets, Drive, and Calendar. Google connects via OAuth.

• Docs — Read and search Google Docs content.
• Sheets — Read data from Google Sheets.
• Drive — List and search files across Google Drive.
• Calendar — View and manage calendar events.

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.