> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z360.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Z360 with External Tools Using Custom/API Integrations

Custom Integrations let your Z360 AI agent call any external service that has a REST API. Your agent can fetch live data, send notifications, create records, and trigger workflows in other tools automatically, as part of an ability.

## What is a Custom Integration?

A Custom Integration is a configured API call that your Z360 agent makes during a conversation. When your agent runs an ability, it can use Custom Integrations as Act steps.

Each Custom Integration defines:

* **The API endpoint** — the URL the agent calls
* **The HTTP method** — GET, POST, PUT, PATCH, or DELETE
* **Arguments** — the inputs the agent passes to the API
* **Headers** — any authentication or content-type headers the API requires

## How to Create a Custom Integration

**Step 1 — Open Integrations**

Go to **AI Studio** in your Z360 sidebar, then click **Integrations**.

**Step 2 — Add a New Integration**

Click **Add Integration**. A configuration form will open.

**Step 3 — Name and Describe the Integration**

Enter a clear name and a description. The agent reads the description to decide when to use it, so be specific.

**Step 4 — Set the Endpoint and Method**

Paste the full API URL into the **Endpoint** field and select GET, POST, PUT, PATCH, or DELETE.

**Step 5 — Add Arguments**

Click **New Argument** to add the inputs your integration needs. Enter a name, description, and toggle Required on if needed.

**Step 6 — Add Headers**

Click **+ Add Header** and enter the key and value for any authentication the API requires.

**Step 7 — Test**

Click **Test** to send a pre-flight request and confirm the API responds correctly.

**Step 8 — Save**

Click **Create Integration**. Your integration is now available inside any ability as an Act node.

## Using a Custom Integration Inside an Ability

Open any ability in **AI Studio → Abilities** and add an **Act** node. Select your integration and map your ability variables to the integration's arguments.

Related article: [Building Abilities in Z360](https://docs.z360.biz/Build-abilities-in-z360)

## Popular Tools You Can Connect

<AccordionGroup>
  <Accordion title="OpenWeatherMap — Live Weather Data">
    **What your agent can do:** Answer questions like "What's the weather in Austin right now?" automatically, without the customer leaving the conversation.

    **Free tier:** 1,000 API calls per day. No credit card required.

    **Setting up OpenWeatherMap**

    1. Go to [openweathermap.org/api](https://openweathermap.org/api) and create a free account.
    2. Open the **API Keys** tab in your account dashboard.
    3. Copy the default API key. Note that new keys take up to 2 hours to activate.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Get Current Weather
    * **Description:** Fetches the current weather for a given city. Use this when a customer asks about the weather.
    * **Method:** GET
    * **Endpoint:** `https://api.openweathermap.org/data/2.5/weather?units=imperial&appid=YOUR_API_KEY`

    Add one argument — **Name:** `q`, **Description:** The city name the customer is asking about, **Required:** Yes.

    Click **Test**, confirm you see a weather response, then click **Create Integration**.

    **Using it in an ability**

    Add an **Ask** node to collect the city name, then an **Act** node selecting "Get Current Weather" with `q` mapped to that variable. Add a **Speak** node to relay the result back to the customer.
  </Accordion>

  <Accordion title="Slack — Team Notifications via Webhook">
    **What your agent can do:** Automatically notify your team in Slack when a new lead is captured, a ticket is submitted, or a customer requests a callback.

    **Free tier:** Available on all Slack plans including free. No credit card required.

    **Setting up Slack**

    1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**.
    2. Choose **From scratch**, name it "Z360 Notifications", and select your workspace.
    3. Click **Incoming Webhooks** in the sidebar and toggle it to On.
    4. Click **Add New Webhook to Workspace**, select the channel you want Z360 to post to, and click **Allow**.
    5. Copy the **Webhook URL** that appears.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Send Slack Notification
    * **Description:** Posts a message to the team Slack channel when a new lead is collected or a customer needs urgent help.
    * **Method:** POST
    * **Endpoint:** Paste your Slack webhook URL here

    No headers needed. Add one argument — **Name:** `text`, **Description:** The message to post including the customer's name, request, and contact info, **Required:** Yes.

    Click **Test**, check your Slack channel for the test message, then click **Create Integration**.

    **Using it in an ability**

    After collecting the customer's information via Ask nodes, add an **Act** node selecting "Send Slack Notification." Set the `text` argument to a message combining the customer's details.
  </Accordion>

  <Accordion title="Airtable — Database Records">
    **What your agent can do:** Add new leads, appointment requests, or form submissions directly to an Airtable base with no manual data entry.

    **Free tier:** Up to 1,000 records per base. No credit card required.

    **Setting up Airtable**

    1. Go to [airtable.com](https://airtable.com) and create a free account.
    2. Create a new **Base** and add columns for the data your agent will collect — for example: Name, Email, Phone, Message.
    3. Note your **Base ID** from the URL. It looks like `appXXXXXXXXXXXXXX`.
    4. Note the exact **Table Name** as it appears.
    5. Go to [airtable.com/create/tokens](https://airtable.com/create/tokens), create a token, add the `data.records:write` scope, and select your base. Copy the token immediately.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Add Airtable Record
    * **Description:** Creates a new record in the Airtable leads base with the customer's contact information.
    * **Method:** POST
    * **Endpoint:** `https://api.airtable.com/v0/YOUR_BASE_ID/YOUR_TABLE_NAME`

    Add two headers: `Authorization` with value `Bearer YOUR_AIRTABLE_TOKEN` and `Content-Type` with value `application/json`.

    Add one argument per field — for example: Name, Email, Phone, Message.

    Click **Test**, check your Airtable base for the new record, then click **Create Integration**.

    **Using it in an ability**

    Use Ask nodes to collect each piece of information, then add an **Act** node selecting "Add Airtable Record." Map each argument to the corresponding variable.
  </Accordion>

  <Accordion title="Brevo — Transactional Email">
    **What your agent can do:** Automatically send confirmation emails, follow-ups, or appointment reminders directly from a conversation.

    **Free tier:** 300 emails per day forever. No credit card required.

    **Setting up Brevo**

    1. Go to [brevo.com](https://www.brevo.com) and create a free account.
    2. Click your name in the top-right and go to **SMTP & API → API Keys**. Generate a new key and copy it.
    3. Go to **Senders & IP → Senders** and add the email address you want to send from. Verify it. This step is required before any emails will send.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Send Confirmation Email
    * **Description:** Sends a confirmation email to the customer after they submit a request or book an appointment.
    * **Method:** POST
    * **Endpoint:** `https://api.brevo.com/v3/smtp/email`

    Add two headers: `api-key` with your Brevo API key and `Content-Type` with `application/json`.

    Add four arguments: `to_email`, `to_name`, `subject`, and `content`.

    Click **Test**, check your test inbox, then click **Create Integration**.

    **Using it in an ability**

    After collecting the customer's details, add an **Act** node selecting "Send Confirmation Email." Map `to_email` and `to_name` to the collected variables and set `subject` and `content` to your message.
  </Accordion>

  <Accordion title="Cal.com — Appointment Booking">
    **What your agent can do:** Let customers book appointments through a conversation, with the booking written directly to your Cal.com calendar.

    **Free tier:** Fully functional free plan. No credit card required.

    **Setting up Cal.com**

    1. Go to [cal.com](https://cal.com) and create a free account.
    2. Set up your availability and create an **Event Type** — for example, "30-Minute Consultation."
    3. Note the **Event Type ID** from the URL when editing it.
    4. Go to **Settings → Developer → API Keys**, click **Add**, and copy your API key.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Book Appointment
    * **Description:** Creates a new appointment booking in Cal.com with the customer's name, email, and preferred time.
    * **Method:** POST
    * **Endpoint:** `https://api.cal.com/v1/bookings?apiKey=YOUR_CAL_API_KEY`

    Add five arguments: `eventTypeId`, `name`, `email`, `start` (ISO 8601 format), and `timeZone`.

    Click **Test**, check your Cal.com dashboard, then click **Create Integration**.

    **Using it in an ability**

    Build an ability that asks for the customer's name, email, preferred date and time, and time zone. Add an **Act** node calling "Book Appointment" with each argument mapped. Follow with a **Speak** node to confirm the booking.
  </Accordion>

  <Accordion title="GitHub — Issue and Bug Reporting">
    **What your agent can do:** Let customers report bugs through chat and automatically open a GitHub issue with all their details, routed directly to your dev team.

    **Free tier:** Fully free for public and private repositories.

    **Setting up GitHub**

    1. Log into GitHub and go to **Settings → Developer settings → Personal access tokens → Tokens (classic)**.
    2. Click **Generate new token (classic)**, name it, and set an expiration.
    3. Check `repo` under **Scopes** for private repos, or `public_repo` for public only.
    4. Click **Generate token** and copy it immediately. GitHub only shows it once.
    5. Note your **username** and **repository name** where issues should be created.

    **Setting up in Z360**

    Go to **AI Studio → Integrations → Add Integration** and fill in:

    * **Name:** Create GitHub Issue
    * **Description:** Opens a new GitHub issue with the customer's bug report or feature request, including their description and contact details.
    * **Method:** POST
    * **Endpoint:** `https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO/issues`

    Add three headers: `Authorization` with `Bearer YOUR_GITHUB_TOKEN`, `Content-Type` with `application/json`, and `Accept` with `application/vnd.github+json`.

    Add two arguments: `title` and `body`.

    Click **Test**, check your repository's Issues tab, then click **Create Integration**.

    **Using it in an ability**

    Build an ability that asks the customer to describe the problem. Add an **Act** node calling "Create GitHub Issue" and map `title` and `body` to the collected variables. Add a **Speak** node confirming the report was submitted.
  </Accordion>
</AccordionGroup>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What is the difference between a Custom Integration and a built-in action?">
    Built-in actions come pre-loaded in Z360 — like Create Contact, Create Ticket, and Update Lead Stage. Custom Integrations are ones you configure yourself by connecting any REST API. Both are used the same way inside ability workflows as Act nodes.
  </Accordion>

  <Accordion title="Do I need to know how to code?">
    No. You fill in a form with the endpoint URL, method, arguments, and headers. As long as you have the API documentation for the service, you can set it up without writing any code.
  </Accordion>

  <Accordion title="Can one ability use multiple Custom Integrations?">
    Yes. You can add as many Act nodes as needed in a single ability. For example, your agent could fetch availability via a GET integration, create a booking via POST, and send a Slack notification via another POST — all in one workflow.
  </Accordion>

  <Accordion title="How does the agent know when to use a specific integration?">
    The agent uses the name and description you provide. Write the description clearly and specifically. The more specific it is, the more reliably the agent will trigger it at the right moment.
  </Accordion>

  <Accordion title="Can I use the same integration in multiple abilities?">
    Yes. Once created, a Custom Integration is available to any ability in your workspace.
  </Accordion>

  <Accordion title="What if the API requires no authentication?">
    Leave the headers section empty. Some public APIs such as Slack webhooks do not need an Authorization header.
  </Accordion>

  <Accordion title="Where do I find my API key for a third-party service?">
    Every service is different, but you generally find it under Settings, Developer Settings, or the API section after signing up. The service's own documentation will point you to the exact location.
  </Accordion>

  <Accordion title="What happens if a required argument is missing when the integration runs?">
    The integration will fail. Make sure your ability's Ask nodes collect all required arguments before the workflow reaches the Act node that uses them.
  </Accordion>

  <Accordion title="What does the Test button do?">
    It sends a real request to the API using the configuration you have entered, so you can confirm the connection works before saving and using it in live conversations.
  </Accordion>

  <Accordion title="Can I update a Custom Integration after saving it?">
    Yes. Go to **AI Studio → Integrations**, find the integration, and click **Edit**. You can update any field at any time.
  </Accordion>
</AccordionGroup>

## Troubleshooting Guide

<AccordionGroup>
  <Accordion title="The integration fails with a 401 Unauthorized error">
    Authentication is failing. Check that your API key has not expired, the header key matches exactly what the API expects, the token format is correct (for example `Bearer YOUR_TOKEN` with a space after "Bearer"), and there are no extra spaces in the header value.
  </Accordion>

  <Accordion title="The integration fails with a 404 Not Found error">
    The endpoint URL is incorrect. Check that the base URL has no typos, any IDs in the URL such as a base ID or table name are accurate, and the resource exists in the third-party service.
  </Accordion>

  <Accordion title="The integration fails with a 400 Bad Request error">
    Something in the arguments was wrong. Check that your argument names match what the API expects exactly and that required fields are not empty.
  </Accordion>

  <Accordion title="The test passes but the integration does not fire inside an ability">
    Check that the Act node is correctly connected and not bypassed by a condition branch, all required arguments are being passed from Ask nodes, and the ability was saved after adding the Act node.
  </Accordion>

  <Accordion title="The integration runs but the data posted to the third-party tool is wrong or empty">
    Arguments are not being mapped correctly. Check that the argument names in your integration match what the ability is passing and that Ask nodes are storing responses into the correct variable names.
  </Accordion>

  <Accordion title="The API key worked before but now the integration is failing">
    API keys can expire or be revoked. Log into the third-party service, generate a new key, and update the header value in your integration. Also confirm the key has the correct permissions for the action being performed.
  </Accordion>

  <Accordion title="I cannot find the API documentation for the service I want to connect">
    Search for "\[Service Name] REST API docs" or "\[Service Name] developer documentation." If the service does not have a public REST API, check whether an MCP server is available for it instead.
  </Accordion>
</AccordionGroup>

Related help center articles:

* [Add and Configure Actions](https://docs.z360.biz/Configure-actions-in-z360)
* [Building Abilities in Z360](https://docs.z360.biz/Build-abilities-in-z360)
* [Create and Edit Abilities](https://docs.z360.biz/Create-and-manage-abilities-in-z360)
* [Connect Z360 with MCP Servers](https://docs.z360.biz/connect-z360-with-mcp-servers)