Set up Zendesk

Back to 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:

Prepare the Sunshine Conversations app and its API key.
Artemis channel configuration: create the connection, then copy its Webhook URL.
Register the webhook in the same app.
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.

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.

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.

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.

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.

Open Artemis and select the project.
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.

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.

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

Select Create.
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.

Confirm the Artemis connection exists and is Active.
Paste the full App-ID-specific URL. Use the public HTTPS Runtime origin, and keep the final encoded App ID segment.
Subscribe to conversation:message for customer text, and conversation:postback for reply-button actions. Artemis ignores unsupported event types.
Save the webhook and keep it enabled. Confirm deliveries reach Artemis with a 2xx response, and keep event IDs stable for retry deduplication.
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.

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.

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.
Confirm Artemis posts the reply to /v2/apps/{appId}/conversations/{conversationId}/messages as a business author, and that it appears in the same conversation.
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.
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.

Credentials
Configuration
Deployment

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.

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.

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	Creating API keys in Admin Center.
Creating conversations integrations	Registering the webhook.
Receiving messages	Payload structure, triggers, and switchboard control.
Structured messages	Buttons, postbacks, and channel fallbacks.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Zendesk events

Prepare the Sunshine Conversations app

Artemis channel configuration

Register the webhook

Validation checklist

Verify the connection

Message behavior and limits

Security and lifecycle boundaries

Manage the channel connection

Troubleshoot connection issues

Zendesk reference

​Prerequisites

​How Artemis routes Zendesk events

​Prepare the Sunshine Conversations app

​Artemis channel configuration

​Register the webhook

​Validation checklist

​Verify the connection

​Message behavior and limits

​Security and lifecycle boundaries

​Manage the channel connection

​Troubleshoot connection issues

​Zendesk reference

Prerequisites

How Artemis routes Zendesk events

Prepare the Sunshine Conversations app

Artemis channel configuration

Register the webhook

Validation checklist

Verify the connection

Message behavior and limits

Security and lifecycle boundaries

Manage the channel connection

Troubleshoot connection issues

Zendesk reference