Zendesk

A Zendesk connector lets a Stellar chat agent answer your customers inside your Zendesk messaging channel, hand them over to a person in Zendesk Agent Workspace, and give the conversation back to Zendesk when it's done.

How it works

When a customer writes in your Zendesk messaging channel, Zendesk sends the message to Stellar and the agent replies in the same conversation. The agent uses the same configuration as on the chat widget: its dialogue, knowledge, actions, and guardrails all apply. Replies are sent as plain text, without buttons or carousels.

The agent stays in control of the conversation until one of these happens:

• The agent hands over. Stellar passes the conversation to Zendesk Agent Workspace, where Zendesk creates the ticket and routes it to a person.
• The agent ends the conversation. Stellar releases the conversation back to Zendesk.
• The customer goes quiet. After an hour without messages, Stellar releases the conversation and closes it.
• Someone else in Zendesk takes or releases the conversation. Stellar usually closes its side of the conversation right away.

A Zendesk conversation can continue days later. If the customer writes again after the conversation ended, for example after a person in Agent Workspace solved the ticket, it reopens. Before the agent replies, Stellar imports the messages the customer and your team exchanged in Zendesk in the meantime, so the agent knows what was discussed. The same import happens when a person in Agent Workspace hands the conversation back to Stellar.

Before you start

• The agent must have the chat channel enabled. See Enable the chat channel.
• You need the Admin role for Chat to manage connectors. See Team management.
• Live chat must be enabled for your organization. If Chat → Connectors is missing from the menu, contact Stellar.
• You need admin access to Zendesk Admin Center.
• A custom integration stores two Zendesk secrets as organization secrets. If you can't manage secrets yourself, ask someone who can, such as an Organization admin.

Add a connector

Open Chat → Connectors in Studio and click Add connector. Fill in the form and click Connect.

• Name: identifies the connector in Studio, for example Support chat. Names must be unique.
• Type: Zendesk.
• Connection method: how Stellar reaches your Zendesk account. See the next section.
• Agent: the chat agent that answers. Only agents with chat enabled are listed.
• Groups: shown when groups are enabled for your organization. Conversations that arrive through the connector are assigned to these groups.

Connection methods

Custom integration (API key) is the default. It uses a Conversations integration and an API key that you create in your own Zendesk account. Clicking Connect creates the connector and opens its setup form. The next section walks through it.

Zendesk marketplace app connects through the Stellar app in the Zendesk Marketplace. Clicking Connect sends you to Zendesk to approve the app, then back to Studio. This method only works once the Stellar app is available for your Zendesk account.

You can't change a connector's connection method after you add it. To switch, remove the connector and add a new one.

Set up a custom integration

The setup form shows the steps below, together with the Webhook endpoint URL for this connector. Keep the form open while you work in Zendesk.

1. In Zendesk Admin Center, open Apps and integrations, then Conversations integrations, and choose Create integration.

2. Fill in the integration form and save it:

   • Name: anything that identifies it, for example Stellar agent.
   • Webhook endpoint URL: copy it from the setup form in Studio.
   • Webhook subscriptions: tick Conversation created, Conversation message, Conversation referral, Switchboard pass control, and Switchboard release control. Leave the other subscriptions off, including the two body-data options.

   After saving, Zendesk shows the integration ID, the app ID, and the webhook ID. Note them, and reveal the webhook's secret.

3. On the same integration, create a Conversations API key. Note its key ID and copy its secret: Zendesk shows it only once.

4. Back in Studio, fill in the fields below and click Save.

5. In Zendesk Admin Center, open AI, then AI agents, then manage marketplace bots, and assign the integration from step 2 to your messaging channel. It's listed under the name you gave it. This makes it the channel's AI agent, replacing whichever one answers the channel today.

Until you do step 5, Zendesk doesn't route the channel's conversations to the integration: Stellar receives the messages but the agent never replies.

The setup form asks for these fields:

• Zendesk subdomain: the part before .zendesk.com in your Zendesk address, for example acme for acme.zendesk.com.
• App ID, Integration ID, Webhook ID: the IDs from step 2. Stellar only accepts messages from the webhook you enter here.
• API key ID: the key ID from step 3.
• API key scope: where you created the key. Choose Integration for a key created on the integration, or App for a key created in the app's Conversations API settings. A mismatch makes Zendesk reject every call.
• API key secret: the organization secret that holds the key's secret.
• Webhook secret: the organization secret that holds the webhook's secret.

To store a secret, click the + next to the field, give the secret a name such as Zendesk API key, and paste the value. The + is only shown if you can manage secrets. Otherwise, ask someone who can to create both secrets in Secrets, then select them in the form.

info

The setup is proven by the first message Zendesk delivers. Send a test message in your Zendesk messaging channel after step 5, and check that the agent replies.

To change the integration later, for example to rotate the API key, click Edit Zendesk integration on the connector's row. The form opens with the stored values and keeps the setup steps folded away under Zendesk setup steps.

Edit a connector

Click Edit on the connector's row to change how it answers:

• Name and Agent: as when adding the connector.
• Environment: which environment of the agent answers.
• Agent version: Published uses the agent's published version, Draft uses its draft, and Pinned uses the version you choose under Pinned version. If you pick Published for an agent that has nothing published, Studio warns you, and messages go unanswered until a version is published.
• Groups: as when adding the connector.
• Enabled: turn off to pause the connector without disconnecting your Zendesk account.

important

While a connector is paused, the agent doesn't answer. Zendesk keeps sending messages to Stellar, so customers in conversations the agent holds get no reply. Stellar releases those conversations back to Zendesk after an hour without messages.

Connector status

The Status column shows where each connector stands:

Status	Meaning
Not connected	The connector exists but setup isn't finished. Click Connect to finish it.
Connected	For the marketplace app, Stellar can reach your Zendesk account. For a custom integration, the settings are saved: send a test message to confirm the agent replies.
Disconnected	Stellar can no longer authenticate with Zendesk, for example because the app was uninstalled or its access revoked. Click Reconnect.
Paused	Shown next to the connection status when Enabled is off.

Remove a connector

Click Remove on the connector's row and confirm. Stellar deletes the connector and its Zendesk webhook, so new messages stop reaching the agent. Conversations already received stay in Studio. Removing a connector doesn't delete the integration or the API key in Zendesk; remove those in Admin Center if you no longer need them.

Review Zendesk conversations

Zendesk conversations appear in Studio under Chat → Conversations, with the same review tools as other chat conversations. See Reviewing conversations. While a conversation is ongoing, its page refreshes as new messages arrive.

They don't appear in Live chat. People answer Zendesk conversations in Agent Workspace, not from Studio.

Troubleshooting

• The agent never replies after setup. Check that the integration is assigned to your messaging channel under **AI → AI agents → Manage marketplace bots ** in Zendesk Admin Center. If it is, check that the Webhook ID and Webhook secret match the integration in Zendesk, that all five webhook subscriptions are ticked, and that the connector isn't paused.
• Zendesk rejects the API key. The API key scope doesn't match where the key was created. Edit the Zendesk integration and change the scope.
• The connector shows Disconnected. Stellar's access to your Zendesk account was revoked. Click Reconnect.
• Messages go unanswered after changing the agent. The agent version can't be resolved, for example Published with nothing published. Publish the agent or pick another Agent version.

What's next

• Setup: enable chat and give it its own personality prompt.
• Reviewing conversations: go through Zendesk conversations in Studio.
• Team management: give someone the Admin role for Chat.