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

# Teamwork Desk

Integration with Teamwork Desk for managing support tickets, customers, and inboxes, and for reacting to ticket and message webhooks.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector     | Authentication |
| ------------- | -------------- |
| Teamwork Desk | API Key        |

### Teamwork Desk

Connect to Teamwork Desk with an API key to manage support tickets, customers, and inboxes.

#### Set up in Teamwork Desk

1. Prepare the Teamwork Desk account or service that the workflow will access. Grant access to the required resources and operations.
2. **Site:** Your Teamwork site subdomain from <https://.teamwork.com>, including the region label if your site has one (e.g. 'acme.eu' for <https://acme.eu.teamwork.com>).
3. **API Key:** Create an API key from your profile icon > View Profile > API Keys tab > Create an API key.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Teamwork Desk**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                 |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Site          | Yes      | Your Teamwork site subdomain from https\://\<site>.teamwork.com, including the region label if your site has one (e.g. 'acme.eu' for <https://acme.eu.teamwork.com>).         |
| API Key       | Yes      | Create an API key from your profile icon > View Profile > API Keys tab > Create an API key. [Provider instructions](https://apidocs.teamwork.com/guides/desk/authentication). |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Teamwork Desk** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Find Tickets

Find support tickets by keywords or by inbox, status, priority, assigned agent, customer, or date range.

#### Inputs

| Field          | Type            | Required | Description                                                                                                                                       |
| -------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search text    | string          | No       | Words to look for in the ticket subject, messages, or customer name/email.                                                                        |
| Inbox          | select (string) | No       | Only tickets in this inbox. Options load from the selected connection.                                                                            |
| Status         | select (string) | No       | Only tickets with this status (Active, Waiting on Customer, Closed, ...). Options load from the selected connection.                              |
| Priority       | select (string) | No       | Only tickets with this priority. Options load from the selected connection.                                                                       |
| Assigned agent | select (string) | No       | Only tickets assigned to this agent. Options load from the selected connection.                                                                   |
| Customer email | string          | No       | Only tickets raised by the customer with this email address.                                                                                      |
| Tag            | select (string) | No       | Only tickets carrying this tag. Options load from the selected connection.                                                                        |
| Updated after  | datetime        | No       | Only tickets updated at or after this time.                                                                                                       |
| Updated before | datetime        | No       | Only tickets updated before this time.                                                                                                            |
| Sort           | select (string) | No       | Order of the results. Available values: Recently updated first, Least recently updated first, Newest first, Oldest first. Default: updated\_desc. |
| Max results    | integer         | No       | How many tickets to return at most (1-200). Minimum: 1. Maximum: 200. Default: 50.                                                                |
| Page           | integer         | No       | Continue from a previous result's next page number.                                                                                               |

#### Outputs

| Field       | Type          | Description                                                                                                          |
| ----------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
| Tickets     | object\_array | Matching tickets with id, subject, status, priority, inbox, agent, customer, preview, created/updated times and URL. |
| Total count | integer       | Total tickets matching the filters, when the API reports it.                                                         |
| Next page   | integer       | Page number to pass back to continue; empty when there are no more results.                                          |

### Get Ticket

Fetch one ticket with its details and the most recent 100 messages of its conversation; older messages are available page by page.

#### Inputs

| Field            | Type    | Required | Description                                                                                                                                 |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Ticket ID        | integer | Yes      | The numeric ticket id (shown in the ticket URL).                                                                                            |
| Include messages | boolean | No       | Also load the conversation messages (replies and notes).                                                                                    |
| Messages page    | integer | No       | Which 100-message window of the conversation to return, newest first: 1 is the most recent 100 messages, 2 the 100 before those, and so on. |

#### Outputs

| Field               | Type          | Description                                                                                                                                               |
| ------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ticket              | object        | Ticket details: subject, status, priority, type, inbox, agent, customer, tags, timestamps, URL.                                                           |
| Messages            | object\_array | Conversation messages in chronological order for the selected window (the newest 100 by default), each with author, kind (reply or note), text, and time. |
| Total messages      | integer       | How many messages the whole conversation has, when Desk reports it.                                                                                       |
| Older messages page | integer       | Value to pass as Messages page to load the next-older window; empty when the returned messages reach the start of the conversation.                       |

### Create Ticket

Open a new support ticket in an inbox on behalf of a customer.

#### Inputs

| Field           | Type            | Required | Description                                                                                          |
| --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| Inbox           | select (string) | Yes      | The inbox the ticket is created in. Options load from the selected connection.                       |
| Customer email  | string          | Yes      | Email address of the customer this ticket is for.                                                    |
| Subject         | string          | Yes      | Ticket subject line.                                                                                 |
| Message         | textarea        | Yes      | The first message of the ticket.                                                                     |
| Message format  | select (string) | No       | Whether the message is written as HTML or Markdown. Available values: HTML, Markdown. Default: html. |
| Priority        | select (string) | No       | Priority for the new ticket. Options load from the selected connection.                              |
| Status          | select (string) | No       | Initial status; defaults to the inbox's default status. Options load from the selected connection.   |
| Type            | select (string) | No       | Ticket type (Question, Problem, ...). Options load from the selected connection.                     |
| Assign to agent | select (string) | No       | Agent to assign the ticket to. Options load from the selected connection.                            |
| Tags            | string          | No       | Comma-separated tag names to apply; unknown tags are reported, not created.                          |
| CC              | string          | No       | Comma-separated emails to copy on the first message.                                                 |
| BCC             | string          | No       | Comma-separated emails to blind-copy on the first message.                                           |
| Notify customer | boolean         | No       | Email the customer that the ticket was created for them. Default: false.                             |

#### Outputs

| Field          | Type    | Description                                    |
| -------------- | ------- | ---------------------------------------------- |
| Ticket ID      | integer | Id of the created ticket.                      |
| Ticket URL     | string  | Link to the ticket in Teamwork Desk.           |
| Customer ID    | integer | Id of the customer the ticket belongs to.      |
| Unmatched tags | string  | Tag names that did not exist and were skipped. |

### Reply to Ticket

Send a reply to the customer or add an internal note on a ticket, optionally changing its status.

#### Inputs

| Field          | Type            | Required | Description                                                                                                                        |
| -------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Ticket ID      | integer         | Yes      | The ticket to reply on.                                                                                                            |
| Message        | textarea        | Yes      | The reply or note text.                                                                                                            |
| Message type   | select (string) | No       | Reply goes to the customer; Note stays internal. Available values: Reply (customer-visible), Note (internal only). Default: reply. |
| Message format | select (string) | No       | Whether the message is written as HTML or Markdown. Available values: HTML, Markdown. Default: html.                               |
| Set status     | select (string) | No       | Status to move the ticket to after posting. Options load from the selected connection.                                             |
| CC             | string          | No       | Comma-separated emails to copy on this reply.                                                                                      |
| BCC            | string          | No       | Comma-separated emails to blind-copy on this reply.                                                                                |

#### Outputs

| Field      | Type    | Description                          |
| ---------- | ------- | ------------------------------------ |
| Message ID | integer | Id of the posted message.            |
| Ticket ID  | integer | The ticket the message was added to. |
| Status     | string  | Ticket status after the call.        |

### Update Ticket

Change a ticket's status, priority, type, assigned agent, inbox or subject, or add tags.

#### Inputs

| Field           | Type            | Required | Description                                                                                                      |
| --------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| Ticket ID       | integer         | Yes      | The ticket to update.                                                                                            |
| Status          | select (string) | No       | New status. Options load from the selected connection.                                                           |
| Priority        | select (string) | No       | New priority. Options load from the selected connection.                                                         |
| Assign to agent | select (string) | No       | Agent to assign the ticket to. Options load from the selected connection.                                        |
| Type            | select (string) | No       | New ticket type. Options load from the selected connection.                                                      |
| Move to inbox   | select (string) | No       | Move the ticket to another inbox. Options load from the selected connection.                                     |
| Subject         | string          | No       | New subject line.                                                                                                |
| Add tags        | string          | No       | Comma-separated tag names to add. Tags can only be added: the Desk API has no way to remove a tag from a ticket. |

#### Outputs

| Field          | Type   | Description                                    |
| -------------- | ------ | ---------------------------------------------- |
| Ticket         | object | The updated ticket summary.                    |
| Unmatched tags | string | Tag names that did not exist and were skipped. |

### Find Customers

Look up customers by name or email.

#### Inputs

| Field       | Type    | Required | Description                                                                          |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| Search text | string  | No       | Part of a name or email to look for; leave empty to list everyone.                   |
| Max results | integer | No       | How many customers to return at most (1-200). Minimum: 1. Maximum: 200. Default: 50. |
| Page        | integer | No       | Continue from a previous result's next page number.                                  |

#### Outputs

| Field     | Type          | Description                               |
| --------- | ------------- | ----------------------------------------- |
| Customers | object\_array | Matching customers.                       |
| Next page | integer       | Page number to continue; empty when done. |

### Create Customer

Add a customer contact, or return the existing one if the email is already known.

#### Inputs

| Field      | Type            | Required | Description                                                                 |
| ---------- | --------------- | -------- | --------------------------------------------------------------------------- |
| Email      | string          | Yes      | Customer email address (unique per customer).                               |
| First name | string          | No       | Customer first name.                                                        |
| Last name  | string          | No       | Customer last name.                                                         |
| Company    | select (string) | No       | Company to link the customer to. Options load from the selected connection. |
| Phone      | string          | No       | Phone number.                                                               |
| Job title  | string          | No       | Job title.                                                                  |
| Notes      | textarea        | No       | Internal notes about the customer.                                          |

#### Outputs

| Field       | Type    | Description                                                                    |
| ----------- | ------- | ------------------------------------------------------------------------------ |
| Customer ID | integer | Id of the created or existing customer.                                        |
| Created     | boolean | True when a new customer was created; false when an existing one was returned. |
| Customer    | object  | The customer record.                                                           |

### Update Customer

Edit a customer's name, company, phone, job title or notes.

#### Inputs

| Field       | Type            | Required | Description                                                                 |
| ----------- | --------------- | -------- | --------------------------------------------------------------------------- |
| Customer ID | integer         | Yes      | The customer to update.                                                     |
| First name  | string          | No       | New first name.                                                             |
| Last name   | string          | No       | New last name.                                                              |
| Company     | select (string) | No       | Company to link the customer to. Options load from the selected connection. |
| Phone       | string          | No       | Phone number.                                                               |
| Job title   | string          | No       | Job title.                                                                  |
| Notes       | textarea        | No       | Internal notes.                                                             |

#### Outputs

| Field    | Type   | Description                  |
| -------- | ------ | ---------------------------- |
| Customer | object | The updated customer record. |

### List Inboxes

List the support inboxes in the account.

#### Inputs

No input fields are required in this catalog entry.

#### Outputs

| Field   | Type          | Description                            |
| ------- | ------------- | -------------------------------------- |
| Inboxes | object\_array | Inboxes with id, name, email and type. |

### List Agents

List the support agents in the account.

#### Inputs

No input fields are required in this catalog entry.

#### Outputs

| Field  | Type          | Description                           |
| ------ | ------------- | ------------------------------------- |
| Agents | object\_array | Agents with id, name, email and role. |

## Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

### New Ticket

Fires when a new ticket is created in Teamwork Desk, optionally only in one inbox.

StackAI registers a Teamwork Desk webhook endpoint for you automatically when you enable this trigger; there is nothing to paste into Desk. Optionally choose an inbox above to only fire for tickets created there; leave it empty to fire for every inbox. IMPORTANT: Teamwork Desk retries a failed delivery at 1, 5 and 10 minutes, then disables the endpoint after the third failure. If tickets stop triggering the workflow, re-enable this trigger to re-register the endpoint.

#### Configuration

| Field | Type            | Required | Description                                                                                                  |
| ----- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| Inbox | select (string) | No       | Only fire for tickets in this inbox; leave empty for all inboxes. Options load from the selected connection. |

#### Event inputs

| Field         | Type     | Required | Description                  |
| ------------- | -------- | -------- | ---------------------------- |
| Ticket ID     | integer  | Yes      | Id of the new ticket.        |
| Subject       | string   | Yes      | Ticket subject.              |
| First message | string   | No       | Text of the opening message. |
| Customer      | object   | No       | Customer id, name and email. |
| Inbox         | object   | No       | Inbox id and name.           |
| Status        | string   | No       | Status name.                 |
| Priority      | string   | No       | Priority name.               |
| Agent         | object   | No       | Assigned agent, if any.      |
| Tags          | array    | No       | Tag names. Default: \[].     |
| Created at    | datetime | Yes      | When the ticket was created. |
| Ticket URL    | string   | Yes      | Link to the ticket.          |

#### Outputs

| Field         | Type          | Description                  |
| ------------- | ------------- | ---------------------------- |
| Ticket ID     | integer       | Id of the new ticket.        |
| Subject       | string        | Ticket subject.              |
| First message | string        | Text of the opening message. |
| Customer      | object        | Customer id, name and email. |
| Inbox         | object        | Inbox id and name.           |
| Status        | string        | Status name.                 |
| Priority      | string        | Priority name.               |
| Agent         | object        | Assigned agent, if any.      |
| Tags          | string\_array | Tag names.                   |
| Created at    | datetime      | When the ticket was created. |
| Ticket URL    | string        | Link to the ticket.          |

### New Ticket Message

Fires when a customer replies, an agent replies, or a note is added on a ticket.

StackAI registers a Teamwork Desk webhook endpoint for you automatically when you enable this trigger; there is nothing to paste into Desk. Choose which messages fire the trigger above: customer replies only (default), customer and agent replies, or every message including internal notes. IMPORTANT: Teamwork Desk retries a failed delivery at 1, 5 and 10 minutes, then disables the endpoint after the third failure. If messages stop triggering the workflow, re-enable this trigger to re-register the endpoint.

#### Configuration

| Field         | Type            | Required | Description                                                                                                                                                                                                                                                   |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Message kinds | select (string) | No       | Which messages fire the trigger: customer replies only (default), customer and agent replies, or everything including internal notes. Available values: Customer replies, Customer and agent replies, All messages (incl. notes). Default: customer\_replies. |

#### Event inputs

| Field          | Type     | Required | Description                             |
| -------------- | -------- | -------- | --------------------------------------- |
| Message ID     | integer  | Yes      | Id of the message.                      |
| Ticket ID      | integer  | Yes      | Ticket the message belongs to.          |
| Kind           | string   | Yes      | customer\_reply, agent\_reply, or note. |
| Body           | string   | Yes      | Message text.                           |
| Author         | object   | No       | Customer or agent who wrote it.         |
| Ticket subject | string   | No       | Subject of the ticket.                  |
| Created at     | datetime | Yes      | When the message was posted.            |
| Ticket URL     | string   | Yes      | Link to the ticket.                     |

#### Outputs

| Field          | Type     | Description                             |
| -------------- | -------- | --------------------------------------- |
| Message ID     | integer  | Id of the message.                      |
| Ticket ID      | integer  | Ticket the message belongs to.          |
| Kind           | string   | customer\_reply, agent\_reply, or note. |
| Body           | string   | Message text.                           |
| Author         | object   | Customer or agent who wrote it.         |
| Ticket subject | string   | Subject of the ticket.                  |
| Created at     | datetime | When the message was posted.            |
| Ticket URL     | string   | Link to the ticket.                     |

### Ticket Status Changed

Fires when a ticket's status changes, optionally only when it reaches a chosen status.

StackAI registers a Teamwork Desk webhook endpoint for you automatically when you enable this trigger; there is nothing to paste into Desk. Optionally choose a status above to only fire when a ticket reaches that status; leave it empty to fire on any status change. IMPORTANT: Teamwork Desk retries a failed delivery at 1, 5 and 10 minutes, then disables the endpoint after the third failure. If status changes stop triggering the workflow, re-enable this trigger to re-register the endpoint.

#### Configuration

| Field                    | Type            | Required | Description                                                                                                            |
| ------------------------ | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| Only when status becomes | select (string) | No       | Fire only when the ticket moves to this status; leave empty for any change. Options load from the selected connection. |

#### Event inputs

| Field           | Type    | Required | Description                     |
| --------------- | ------- | -------- | ------------------------------- |
| Ticket ID       | integer | Yes      | The ticket that changed.        |
| New status      | string  | Yes      | New status name.                |
| New status code | string  | No       | Machine code of the status.     |
| Changed by      | integer | No       | Id of the agent who changed it. |
| Ticket subject  | string  | No       | Subject of the ticket.          |
| Ticket URL      | string  | Yes      | Link to the ticket.             |

#### Outputs

| Field           | Type    | Description                     |
| --------------- | ------- | ------------------------------- |
| Ticket ID       | integer | The ticket that changed.        |
| New status      | string  | New status name.                |
| New status code | string  | Machine code of the status.     |
| Changed by      | integer | Id of the agent who changed it. |
| Ticket subject  | string  | Subject of the ticket.          |
| Ticket URL      | string  | Link to the ticket.             |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# 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.stackai.com/integrations/catalog/teamwork-desk.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.
