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

# Set up Zendesk

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect a Zendesk Sunshine Conversations app to your agent so customers reach it through any channel that app already serves. You map the app's App ID and API key into Artemis, register a connection-specific webhook, then verify messages, replies, and postbacks.

The setup requires:

1. [Prepare the Sunshine Conversations app](#prepare-the-sunshine-conversations-app) and its API key.
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
3. [Register the webhook](#register-the-webhook) in the same app.
4. [Verify the connection](#verify-the-connection) with a complete customer conversation.

After setup, a customer message on any channel connected to the app opens a session in Artemis, and the reply posts back into the same conversation as a business author.

**Important considerations**

* **App ID is both the routing key and the provider destination**: Artemis resolves inbound events from the App ID at the end of the webhook URL, and uses the payload's matching `app.id` for replies. Both App ID fields must identify the same Sunshine Conversations app.
* **Never expose the Key Secret**: The API Key ID and Key Secret authorize outbound messages for every conversation in the app. Store them only in Artemis, and rotate both together.
* **Webhook Secret isn't the API Key Secret**: It's optional, and only works when a sender or trusted middleware generates the `x-api-key` HMAC header Artemis expects.
* **Artemis doesn't create the customer entry point**: The app still needs a connected Sunshine Conversations integration or client through which a customer starts a conversation.

## Prerequisites

Confirm these before you start.

* A Sunshine Conversations app with at least one customer-facing integration, such as the Web Widget or a social channel.
* Administrator access in Zendesk. In Admin Center, the Conversations API page needs Zendesk Suite Professional or above with Agent Workspace.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Zendesk events

Artemis puts the App ID at the end of the webhook path and resolves the connection from it.

| Piece | Owner | What it does |
| - | - | - |
| **App ID** | Zendesk | Routes inbound events from the URL, and identifies the app for replies. It appears in a public URL and isn't a secret. |
| **API Key ID** and **API Key Secret** | Zendesk | Send outbound messages through HTTP Basic authentication. |
| **Webhook Secret** | You | Optional. When set, every request must carry `x-api-key` with the lowercase hex HMAC-SHA256 of the untouched raw body. |
| **Webhook URL** | Artemis | Receives events at `/api/v1/channels/zendesk/webhook/{appId}`. The generic `/zendesk/webhook` path can't select a connection. |

Artemis keys each session to the app and the conversation, and posts replies to `/v2/apps/{appId}/conversations/{conversationId}/messages`.

***

## Prepare the Sunshine Conversations app

Do this in Zendesk before you open Artemis. Select **Open Sunshine Conversations** or **Open API documentation** in the setup guide to jump straight there.

**1. Create or select the target app**

Sign in to the Sunshine Conversations dashboard, or in Admin Center go to **Apps and integrations** > **APIs** > **Conversations API**. Choose the app that owns the customer-facing integration. Keep development and production apps separate.

**2. Copy the immutable App ID**

Copy the app-level identifier from the app settings. Don't use a Zendesk subdomain, integration ID, conversation ID, user ID, webhook ID, or API key ID.

**3. Create a server-side API key**

Open the app's **API keys** settings and create a key for this connection. Copy both the Key ID and the Key Secret while the secret is visible, because Zendesk shows it once.

**4. Confirm a customer integration exists**

The app needs a supported Sunshine Conversations integration or client, such as the Web Widget, through which a customer can start a conversation. The Artemis webhook doesn't create one.

***

## Artemis channel configuration

Create the connection before Zendesk sends webhooks. Artemis resolves webhooks only for an active connection.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Zendesk** > **+ New**. The **New Zendesk Connection** dialog opens, with the setup guide on the left and the fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see. Name it for the app and environment. Routing ignores it. |
   | **App ID** (identifier) | App settings | The routing key, used in the webhook path to select the connection. |
   | **App ID** (credential) | The same App ID | Used for provider operations. A mismatch can accept one app's route but fail or misdirect replies. |
   | **API Key ID** | The app's API key | The username for outbound HTTP Basic authentication. |
   | **API Key Secret** | The app's API key | The password for outbound HTTP Basic authentication. |
   | **Webhook Secret** (optional) | You create it | Requires the `x-api-key` HMAC on every request. Leave it empty unless a sender or trusted middleware generates that header. |
   | **Environment** | Your published environments | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Zendesk's identity assertion when it links a customer to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | Keep it **Active** for immediate use. |

   > [!TIP]
   >
   > Artemis asks for the App ID twice, once as the routing identifier and once as an encrypted credential. Paste the same value into both.

4. Select **Create**.

5. Copy the **Webhook URL** from the connection's summary panel. It ends with the encoded App ID.

***

## Register the webhook

Register the webhook in the same Sunshine Conversations app as the credentials. In Admin Center, go to **Apps and integrations** > **Integrations** > **Conversations integrations** and select **Create integration**.

1. Confirm the Artemis connection exists and is **Active**.
2. Paste the full App-ID-specific URL. Use the public HTTPS Runtime origin, and keep the final encoded App ID segment.
3. Subscribe to `conversation:message` for customer text, and `conversation:postback` for reply-button actions. Artemis ignores unsupported event types.
4. Save the webhook and keep it enabled. Confirm deliveries reach Artemis with a 2xx response, and keep event IDs stable for retry deduplication.
5. If you set **Webhook Secret**, make sure every request carries the matching `x-api-key` HMAC of the untouched raw body. With the field blank, Artemis accepts inbound events without a signature.

> [!WARNING]
>
> Don't paste the API Key Secret into **Webhook Secret**. Configure a separate shared value only when the sender or middleware generates the `x-api-key` HMAC exactly as Artemis expects.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Prepare the app | App ID, Key ID, and Key Secret from one app, with a customer integration connected. |
| Create the Artemis connection | Saved as **Active**, with the same App ID in both fields. |
| Register the webhook | Same app, full App-ID URL, and both triggers subscribed. |
| Test a conversation | One customer message produces one agent reply. |

***

## Verify the connection

Artemis doesn't synthesize Zendesk events, so a real conversation is the only end-to-end proof.

1. From the app's connected customer client, send a unique message. Confirm one `conversation:message` delivery, one session keyed by app and conversation, and one agent turn.
2. Confirm Artemis posts the reply to `/v2/apps/{appId}/conversations/{conversationId}/messages` as a business author, and that it appears in the same conversation.
3. Send an authored response with a button, select it in the customer client, and confirm `conversation:postback` resumes the same conversation with the expected action value.
4. Confirm the agent's reply doesn't create a second turn. Artemis ignores business-authored `conversation:message` events by design.

***

## Message behavior and limits

Sunshine Conversations normalizes many channels into one API.

| Area | Behavior |
| - | - |
| Channel coverage | The connection inherits every channel the app serves. Author for the least capable channel. |
| Buttons | Zendesk falls back where a channel lacks native buttons. Test the fallback. |
| Author types | Artemis processes customer-authored events and ignores business-authored ones. |
| Retries | Artemis deduplicates on the first event ID. Preserve provider retries and don't rewrite event identifiers. |
| Switchboard control | When a custom integration holds the conversation, Agent Workspace doesn't receive it. Plan handoff if human agents take over. |

***

## Security and lifecycle boundaries

The API key is the credential that matters. The inbound side has protection only if you add it.

* **API key**: The Key ID and Key Secret authorize the Sunshine Conversations REST API. Use a dedicated key, encrypt it at rest, redact it from diagnostics, and revoke unused keys.
* **Webhook verification**: Optional in this connection. Production deployments should use the matching `x-api-key` HMAC path, or enforce an equivalent trusted ingress control.
* **App ID**: It appears in the public URL and isn't a secret. Authorization still depends on webhook verification and credential protection.
* **Environments**: Use distinct Sunshine Conversations apps or API keys, webhooks, secrets, and connections for development and production.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Zendesk** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Zendesk** and **Channel Connection**. |
| **Identifier** | The App ID this connection routes on. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The App-ID-specific URL for Zendesk, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value, or enter a new value to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile in place of the fields below. |
> | **App ID** | The credential copy. Keep it matched to the identifier. |
> | **API Key ID** and **API Key Secret** | Replace both together when you issue a new key, because Artemis sends them as one Basic credential. |
> | **Webhook Secret (optional)** | Set or clear the HMAC requirement. Clearing it accepts unsigned events. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Zendesk Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Zendesk's identity assertion. |
> | **App ID** | Read-only, with a copy control. To serve another app, create a new connection. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select **Show more** for the full list, and select **Show preview** to check it. |
> | **Webhook URL** | The App-ID-specific URL, with a copy control. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers Zendesk.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> A connection on **Working Copy (draft)** shows a warning, because the working copy is for testing. Deploy the agent to an environment and bind the channel to it before customers reach it. Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Most failures trace to App ID mismatches, the API key, or the optional HMAC.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Connection not found | Wrong URL or inactive connection | Confirm the URL ends with the exact App ID saved in Artemis, the connection is **Active**, and the payload's `app.id` names the same app. |
| Outbound replies return `401` or `403` | API key mismatch or revoked | Confirm the Key ID and Key Secret belong to the credential App ID, and nobody regenerated or revoked them. |
| Customer messages don't arrive | Wrong app, missing trigger, or unreachable endpoint | Confirm you enabled the webhook in the same app, subscribed `conversation:message`, the public URL is reachable, and delivery history shows 2xx. |
| Inbound works but no reply appears | Missing conversation, credentials, or deployment | Confirm the payload includes `conversation.id`, the app credentials match, the environment can run, and the provider API is reachable. |
| Webhook returns `401` after you set Webhook Secret | No matching HMAC header | Preserve the raw request bytes and set `x-api-key` to the lowercase hex HMAC-SHA256 made with that secret, or clear the field for an intentionally unsigned deployment. |
| Replies create repeated turns | Author type rewritten | Inspect the event `author.type`. Artemis ignores business authors, so middleware must not rewrite agent messages as customer or user authors. |
| Text works but buttons don't | Missing postback trigger or channel support | Subscribe to `conversation:postback`, confirm the customer integration supports reply actions, and verify the action payload returns unchanged. |

***

## Zendesk reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [Using the Conversations API keys](https://support.zendesk.com/hc/en-us/articles/4576088682266-Using-the-Conversations-API-keys) | Creating API keys in Admin Center. |
| [Creating conversations integrations](https://support.zendesk.com/hc/en-us/articles/4576083789850-Creating-conversations-integrations-in-Admin-Center) | Registering the webhook. |
| [Receiving messages](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/receiving-messages/) | Payload structure, triggers, and switchboard control. |
| [Structured messages](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/structured-messages/) | Buttons, postbacks, and channel fallbacks. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Twilio SMS](https://koreai.mintlify.site/agent-platform/channels/twilio)
* [Set up Genesys](https://koreai.mintlify.site/agent-platform/channels/genesys)


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