> For the complete documentation index, see [llms.txt](https://docs.zigiwave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zigiwave.com/available-systems/zammad.md).

# Zammad

Connect Zammad to ZigiOps. Supported versions, prerequisites, API token permissions, connected system configuration, supported entities and fields.

### What is Zammad integration in ZigiOps?

Zammad is a web-based helpdesk and customer support ticketing system used to manage customer requests across channels such as email, phone, and chat.

ZigiOps enables secure, agentless, no-code integration between Zammad and ITSM, DevOps, monitoring, and CRM systems. ZigiOps connects to Zammad through the **Zammad REST API v1** and authenticates with an **API token**.

Zammad has a single Ticket object. A ticket’s “type” is an ordinary select field, not a separate object class, so ZigiOps exposes **one** `ticket` collection instead of one collection per ticket type. Admin-defined custom ticket fields are discovered automatically and added to that collection. Custom field values are read and written as plain top-level ticket keys, so they need no special handling.

With ZigiOps, you can:

* Sync Zammad tickets with another system, covering all core ticket fields plus discovered custom fields
* Poll for new or changed tickets by `created_at`, `updated_at`, `pending_time`, `close_at` or `escalation_at` (`>`, `<`, `>=`, `<=`, `=`)
* Search tickets by field value using `=` or `contains` (prefix match) on `title`, `number`, `state_name`, `priority_name`, `group_name`, `state_id` and other indexed fields
* Get a single ticket by ID
* Read customer, owner, created-by and updated-by as name, email and login, not only as IDs
* Create tickets, optionally with the first article (comment) in the same call
* Update any ticket field, including tags and custom fields
* Set the customer or owner by name, login or email (ZigiOps resolves the value to the Zammad user ID)
* Read a ticket’s articles, filtered by created time, and add new articles (note, email, phone, …; internal or public) to an existing ticket
* Read every attachment on a ticket, including the binary content, either directly on the ticket or per article, and add files to a ticket
* Look up users, organizations, groups, ticket states, and ticket priorities

### Which Zammad versions are supported?

Using a supported version is mandatory.

| Product | Supported Deployment Types | Supported Versions | API Used                         |
| ------- | -------------------------- | ------------------ | -------------------------------- |
| Zammad  | All                        | All                | Zammad REST API v1 (`/api/v1/…`) |

### Are there any environmental prerequisites for Zammad?

Confirm the prerequisites of the corresponding integration template before continuing further, as some templates may not require all environmental prerequisites.

See the **Related Templates** section at the end of this page.

ZigiOps authenticates to Zammad with an API token. Create the token before you add Zammad as a connected system.

#### How do I create a Zammad API token?

{% stepper %}
{% step %}
**Log in to Zammad**

Log in to your **Zammad** instance with the user that ZigiOps will use for the integration.
{% endstep %}

{% step %}
**Create a token**

Navigate to **Profile > Token Access** and create a new token.
{% endstep %}

{% step %}
**Grant permissions**

Grant the token the permissions listed in the table below.
{% endstep %}

{% step %}
**Store the token securely**

Copy the token and store it securely. You will need it when you configure the connected system in ZigiOps.
{% endstep %}
{% endstepper %}

#### Which permissions does the Zammad API token need?

| Permission         | Needed for                                                                                                   | Required?                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `ticket.agent`     | Reading and writing tickets, articles and attachments                                                        | Yes                                 |
| `user_preferences` | Test connection (`GET /api/v1/users/me`)                                                                     | Yes                                 |
| `admin.object`     | Custom ticket field discovery. Without it, discovery finds no custom fields, but everything else still works | Optional (needed for custom fields) |

{% hint style="warning" %}
ZigiOps sends the token in the header `Authorization: Token token=<token>`. The header value must be exactly `Token token=`; a bare `Token` or `Bearer` prefix is rejected with 401. The token is static, so a 401 or 403 response means the token is wrong or lacks a permission. The connector does not retry.
{% endhint %}

### How do I connect Zammad to ZigiOps?

#### Zammad - Connected System Configuration

Follow the steps below to add Zammad as a connected system in ZigiOps.

{% stepper %}
{% step %}
**Log in to ZigiOps**

Log in to your **ZigiOps** instance.
{% endstep %}

{% step %}
**Add Zammad as a connected system**

Navigate to **Connected Systems > Add New System > Zammad**.
{% endstep %}

{% step %}
**Configure the connection**

Configure the following parameters:

**URL** (required)

Input the URL of your Zammad instance. Use the bare instance root; ZigiOps appends `/api/v1/...` automatically.

Example: `https://yourcompany.zammad.com`

**API Token** (required)

Input your Zammad API token. The value is stored as a secure password field.

**Proxy Settings** (optional)

Enable this option and input the proxy address and proxy port if a proxy server is required for outbound communication.
{% endstep %}

{% step %}
**Verify the connection**

Review the configuration and click **Verify instance URL and API token** to test the connection.

The test calls `GET /api/v1/users/me`, which works with even a narrowly scoped token.
{% endstep %}

{% step %}
**Save the connected system**

Click **Save** to store the connected system.

Once saved, Zammad becomes available for use in ZigiOps integration templates.
{% endstep %}
{% endstepper %}

### Which Zammad entities and fields does ZigiOps support?

#### Ticket (static fields and discovered custom fields)

| Field                                                                                                                                                                                                                    | Label                                      | Type                       | Query | Create | Update | Notes                                                          |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | -------------------------- | ----- | ------ | ------ | -------------------------------------------------------------- |
| `id`                                                                                                                                                                                                                     | ID                                         | number                     | Yes   | No     | No     |                                                                |
| `number`                                                                                                                                                                                                                 | Number                                     | string                     | Yes   | No     | No     | Ticket number shown in the UI                                  |
| `title`                                                                                                                                                                                                                  | Title                                      | string                     | Yes   | Yes    | Yes    | Required on create                                             |
| `group_id`                                                                                                                                                                                                               | Group ID                                   | number                     | Yes   | Yes    | Yes    | Required on create                                             |
| `group_name`                                                                                                                                                                                                             | Group                                      | string                     | Yes   | No     | No     | Resolved from `group_id`                                       |
| `state_id`                                                                                                                                                                                                               | State ID                                   | number                     | Yes   | Yes    | Yes    |                                                                |
| `state_name`                                                                                                                                                                                                             | State                                      | string                     | Yes   | No     | No     | Resolved from `state_id`                                       |
| `priority_id`                                                                                                                                                                                                            | Priority ID                                | number                     | Yes   | Yes    | Yes    |                                                                |
| `priority_name`                                                                                                                                                                                                          | Priority                                   | string                     | Yes   | No     | No     | Resolved from `priority_id`                                    |
| `customer_id`                                                                                                                                                                                                            | Customer ID                                | number                     | Yes   | Yes    | Yes    | Required on create (or provide one of the `customer_*` fields) |
| `customer_name` / `customer_email` / `customer_login`                                                                                                                                                                    | Customer / Customer Email / Customer Login | string                     | Yes   | Yes    | Yes    | Writing any of these sets `customer_id`                        |
| `owner_id`                                                                                                                                                                                                               | Owner ID                                   | number                     | Yes   | Yes    | Yes    |                                                                |
| `owner_name` / `owner_email` / `owner_login`                                                                                                                                                                             | Owner / Owner Email / Owner Login          | string                     | Yes   | Yes    | Yes    | Writing any of these sets `owner_id`                           |
| `organization_id`                                                                                                                                                                                                        | Organization ID                            | number                     | Yes   | Yes    | Yes    |                                                                |
| `type`                                                                                                                                                                                                                   | Type                                       | string                     | Yes   | Yes    | Yes    |                                                                |
| `note`                                                                                                                                                                                                                   | Note                                       | string                     | Yes   | Yes    | Yes    |                                                                |
| `tags`                                                                                                                                                                                                                   | Tags                                       | string                     | Yes   | Yes    | Yes    | Updated through the tag add/remove endpoints (see Limitations) |
| `pending_time`                                                                                                                                                                                                           | Pending Till                               | timestamp                  | Yes   | Yes    | Yes    |                                                                |
| `article_count`                                                                                                                                                                                                          | Article Count                              | number                     | Yes   | No     | No     |                                                                |
| `created_at` / `updated_at`                                                                                                                                                                                              | Created At / Updated At                    | timestamp                  | Yes   | No     | No     |                                                                |
| `created_by_id` / `updated_by_id`                                                                                                                                                                                        | Created By ID / Updated By ID              | number                     | Yes   | No     | No     |                                                                |
| `created_by_name` / `_email` / `_login`                                                                                                                                                                                  | Created By …                               | string                     | Yes   | No     | No     | Set by Zammad from the token user                              |
| `updated_by_name` / `_email` / `_login`                                                                                                                                                                                  | Updated By …                               | string                     | Yes   | No     | No     | Set by Zammad from the token user                              |
| `escalation_at`, `first_response_at`, `first_response_escalation_at`, `close_at`, `close_escalation_at`, `last_close_at`, `last_contact_at`, `last_contact_agent_at`, `last_contact_customer_at`, `last_owner_update_at` | -                                          | timestamp                  | Yes   | No     | No     | SLA and activity timestamps                                    |
| `articles`                                                                                                                                                                                                               | Articles                                   | reference → article \[]    | Yes   | Yes    | Yes    |                                                                |
| `attachments`                                                                                                                                                                                                            | Attachments                                | reference → attachment \[] | Yes   | Yes    | Yes    | All attachments across all articles of the ticket              |

### What are the most common Zammad integration use cases?

#### Use case 1: Synchronizing Zammad tickets with ITSM and DevOps platforms

ZigiOps syncs Zammad tickets, including all core fields and discovered custom fields, with another system. Teams can create and update tickets in both directions, so support and operations work from the same data without manual copying.

#### Use case 2: Polling for new and changed tickets

ZigiOps polls Zammad for new or changed tickets using time-based filters on `created_at`, `updated_at`, `pending_time`, `close_at` or `escalation_at`. This keeps the connected system up to date with ticket changes, including SLA and escalation timestamps.

#### Use case 3: Keeping conversations and files in sync

ZigiOps reads a ticket’s articles (comments) and attachments, including binary content, and adds new articles and files to existing tickets. Internal and public notes, emails, and phone entries stay visible to both teams.

#### Use case 4: Assigning customers and owners by name, login, or email

ZigiOps can set the ticket customer or owner by name, login, or email and resolves the value to the Zammad user ID. User fields are also returned in a readable form (name, email, and login), not only as IDs.

### What integration templates are available for Zammad?

ZigiOps supports Zammad integrations with prebuilt and custom integration templates, depending on the target system and use case.

#### Related Templates

For detailed information about available templates for Zammad integrations, please contact:

**Email:** <support@zigiwave.com>

### Zammad integration FAQ

<details>

<summary>How does ZigiOps authenticate to Zammad?</summary>

ZigiOps uses a Zammad API token, sent as `Authorization: Token token=<token>`. The token needs `ticket.agent` and `user_preferences`, plus `admin.object` for custom field discovery.

</details>

<details>

<summary>Does ZigiOps support Zammad custom fields?</summary>

Yes. ZigiOps automatically discovers active, non-internal custom ticket attributes and adds them to the `ticket` collection, as long as the token has the `admin.object` permission.

</details>

<details>

<summary>Can ZigiOps sync Zammad comments and attachments?</summary>

Yes. ZigiOps reads and creates ticket articles (comments) and attachments, including binary file content. Every attachment added to a ticket is carried by an article.

</details>

<details>

<summary>Why does a Zammad date filter return a record on the boundary?</summary>

Ticket search uses Lucene ranges, which have no exclusive form. Strict comparisons (`>` / `<`) therefore behave as inclusive.

</details>

### Summary

The Zammad integration in ZigiOps provides:

* Secure, agentless, no-code integration with Zammad through the Zammad REST API v1
* API token authentication with clearly defined permissions
* A single `ticket` collection with automatic custom field discovery
* Read and write support for tickets, articles, and attachments, including binary content
* Lookups for users, organizations, groups, ticket states, and ticket priorities
* Flexible proxy support


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zigiwave.com/available-systems/zammad.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
