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

# Zendesk Messaging

> Let the agent answer first in your Zendesk Web Widget and apps, and pass a chat to your team in Zendesk when it needs a person.

Connect Zendesk Messaging and the agent becomes the first responder on your Zendesk messaging channels, such as the Web Widget and your mobile apps. It answers from its knowledge, the same way it does in website chat. When a customer needs a person, it passes the conversation to your team in Zendesk Agent Workspace, with a summary and the transcript, and stays out of it.

> [!NOTE]
>
> This is not the [Zendesk](https://wiredesk.ai/docs/integrations/helpdesks.md#zendesk) integration, which opens tickets. You can use both.

## Before you start

* A Zendesk account with messaging turned on, answered in Agent Workspace.
* Admin access to Zendesk Admin Center.
* The **owner** or **admin** role in your Wiredesk workspace.

You don't install an app from the Zendesk Marketplace. You create an API key in your own Zendesk and paste it into Wiredesk.

## Create an API key in Zendesk

**1. Open the Conversations API page**

In Zendesk Admin Center, go to **Apps and integrations → APIs → Conversations API**.

**2. Create a key**

Click **Create API key** and name it Wiredesk.

**3. Copy three values**

Copy the **App ID**, the **Key ID** and the **Secret key**. Zendesk shows the secret key only once.

## Connect it in Wiredesk

**1. Open Connections**

Go to **Agents → your agent → Actions › Connections**. On the **Zendesk Messaging** card, click **Connect**.

**2. Fill in the form**

| Field | What to enter |
| - | - |
| **Zendesk subdomain** | `acme` for `acme.zendesk.com`. |
| **App ID**, **Key ID**, **Secret key** | The three values from the Conversations API page. |
| **Summary ticket field ID** (optional) | A text ticket field for the agent's handover summary. Find the ID under **Objects and rules → Tickets → Fields**. |

**3. Click Connect**

We check the key with Zendesk, then set everything up. If something is missing, such as messaging not being turned on, you see Zendesk's reason under the form and nothing is saved.

Connecting does three things in your Zendesk, so you don't have to:

1. It adds a webhook, so Zendesk sends each customer message to Wiredesk.
2. It adds Wiredesk to your messaging switchboard, with Agent Workspace next in line.
3. It makes Wiredesk the switchboard's first responder, so it answers new conversations.

The secret key and the webhook's secret are encrypted when you save and never shown again.

## Finish in Zendesk

A connected card shows **Finish in Zendesk**, a list read live from your Zendesk. Click **Check again** after you change something.

* **Channels.** The list names each messaging channel the agent answers. A channel with its own responder set in Admin Center doesn't reach the agent. The card names the responder that answers it instead. In Admin Center, go to **Channels → Messaging and social → Messaging**, open the channel, and set its responder back to the default.
* **Let agents end sessions.** In Admin Center, go to **Channels → Messaging and social → Messaging → Manage settings → Advanced**. Under **Ending sessions**, select **Agents can end messaging sessions at any time**. Ending a session is how a conversation comes back to the agent after your team is done.
* **A person in chat & email.** Turn on [A person in chat & email](https://wiredesk.ai/docs/actions/request-a-human.md) under **Handoff**. Without it the agent can't hand over, and it offers to take a message instead.

## Check that it works

1. Open your Zendesk Web Widget and ask something your knowledge answers. The agent replies.
2. Type "I want to talk to a person". The agent says it's passing you to the team, and the conversation appears in Agent Workspace.
3. Reply as the Zendesk agent. Your reply shows in the widget, and in the Wiredesk transcript.
4. End the session in Zendesk, then write again in the widget. The agent answers again.

## How it works

### The agent answers first

Each customer message runs through the same agent as your website chat: its knowledge, its instructions, and its actions. Replies go out under the agent's name. The agent reads text messages only; it doesn't answer a file or an image without text.

### Handing over

The agent passes the conversation to Agent Workspace when:

* the customer asks for a person, or the agent decides they need one (**A person in chat & email**);
* the agent can't answer at all, for example because your workspace reached its [spend cap](https://wiredesk.ai/docs/account/spend-cap.md) or the agent was deleted. The customer is never left waiting for an answer that will not come;
* the conversation goes past the agent's [message limit](https://wiredesk.ai/docs/persona/message-limit.md).

Your team gets the conversation's history in Agent Workspace, as with any messaging ticket. The handover also carries:

* the agent's **summary** of why the customer needs a person, in your summary ticket field if you set one;
* a **link** to the conversation in Wiredesk;
* the end of the **transcript**, as much as fits;
* the tags `wiredesk` and `wiredesk_handover`, for views and routing.

While your team has the conversation, the agent says nothing. Messages from the customer and your team still appear in the Wiredesk transcript.

### When your team is done

When a Zendesk agent ends the messaging session, the conversation goes back to the Wiredesk agent. The customer's next message starts a new conversation in Wiredesk, the way a new chat would.

### In Wiredesk

Conversations show under **Conversations** with the channel **Zendesk Messaging**. You can't reply to them from Wiredesk: your team answers in Zendesk. The agent's replies are billed as chat replies.

## Limitations

* One agent per Zendesk account. To move it to another agent, disconnect it from the first agent, then connect it on the other.
* The agent doesn't send the greeting or suggested follow-ups as reply buttons yet.
* Zendesk must be able to reach Wiredesk's webhook over the internet.

## Disconnect

On the **Zendesk Messaging** card, click **Disconnect**. Wiredesk removes itself from your switchboard, gives first response back to whoever had it before, and deletes the webhook and the key. If Zendesk doesn't let us, the message says what to remove by hand in Admin Center. Conversations so far stay in Wiredesk.

## Related

* [Integrations](https://wiredesk.ai/docs/integrations/overview.md)
* [Handover](https://wiredesk.ai/docs/concepts/handover.md)
* [Helpdesks](https://wiredesk.ai/docs/integrations/helpdesks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.