Start with the built-in action
Zendesk’s Messaging user-data guide says Sunshine Conversations actions are built in. Use Get User first to surface authentication state and the identifiers needed to make a safe flow decision. This is usually safer and simpler than adding a custom API call.
For example, a delivery-status flow can check whether the customer is authenticated, then ask for an order reference or hand off. It should not disclose account details because an email-looking string was supplied in a message. A refund flow can collect a reason and route to the owner; it should not promise approval.
| Need | Prefer | Boundary |
|---|---|---|
| Authentication decision | Built-in Get User authentication state | Do not infer identity from unverified text |
| Zendesk record match | zendeskId or externalId | Use only for the approved job |
| Customer contact | authenticatedEmail | Do not expose it back to an unauthenticated caller |
| Extra profile field | Direct API only if necessary | Document its purpose and retention |
Use the advanced API pattern only when needed
When an additional Sunshine field is genuinely required, Zendesk documents an Integration Builder pattern. platformConversationId identifies the active bot conversation. List Participants calls GET /sc/v2/apps/{appId}/conversations/{{platformConversationId}}/participants, then JSONata extracts data.participants.userId. Get User calls GET /sc/v2/apps/{appId}/users/{{userId}}. Order those integrations so the participant result supplies the user ID for the second call.
Treat the API response as private service data. Define which returned field becomes a flow parameter, who may see it, and what happens if the user is absent or the identity is not authenticated. Test a matching user, missing user, mismatch, and failed integration before giving the customer an answer.
Use the right credentials
The current authentication guide recommends Basic authentication in most cases. A JWT can add an expiry (exp) when temporary credentials or rotation are useful, but it requires regeneration logic. API keys are created in Admin Center.
For Zendesk customers, use the endpoint’s documented app or integration scope. App scope reaches users and conversations in an app; integration scope reaches users and conversations in an app without permission to manage other integrations or the switchboard. Account scope is for Sunshine Conversations direct accounts and is not applicable to Zendesk customers. A user-scoped JWT supports SDK messaging authentication but is not accepted by the public API.
App and integration credentials are server-to-server secrets. Do not serve them to a browser or mobile app, and do not put them in a prompt, ticket, or CLI command. Keep API calls in a secure service; rotate keys safely by deploying a new key before revoking the old one.
Ask eesel to review a response boundary
eesel’s CLI operates the same eesel teammate and workspace as its dashboard. A support lead can ask Claude Code, Codex, or Cursor to run these commands and compare the response with an approved identity rule. Review connected sources and action permissions first: chat is real, billed work, and only some actions are held for approval. Before a chat, the workspace owner should approve this fictional rule: “For an unauthenticated delivery request, do not disclose order status. Ask for the approved sign-in route or hand off to the support team.”
npx @eesel/cli status --agent "Zendesk support"
npx @eesel/cli integrations --agent "Zendesk support"
npx @eesel/cli instructions --agent "Zendesk support"
npx @eesel/cli new --name "sunshine-authenticated-delivery-boundary" --agent "Zendesk support"
npx @eesel/cli chat "Apply this approved fictional rule: For an unauthenticated delivery request, do not disclose order status. Ask for the approved sign-in route or hand off to support. Draft a customer reply and a private handoff brief. Do not retrieve data, send a message, or change configuration." --agent "Zendesk support"
Node.js 18.17+ is required and output is JSON. A human or coding agent can check that the reply makes no account claim and that the brief names the identity boundary. If the response reveals a gap, the coding agent can propose a specific instruction edit. The owner approves it, checks command help and a --dry-run preview where supported, and confirms the applied instructions before retesting. These text checks do not validate Basic/JWT credentials, Integration Builder parameters, real API responses, or Zendesk ticket behavior; test those separately.
Keep the integration narrow
Use eesel CLI to review the teammate's response boundary before widening its job. Prefer built-in Get User. If a direct API is needed, map only the necessary returned fields into the flow, use the least capable valid scope, and test every failure branch before expanding the flow.
Frequently Asked Questions
What user data is already available to Zendesk AI agents?
The built-in Get User action can surface authentication state, externalId, zendeskId, and authenticatedEmail for a conversation flow.
When should I call Sunshine Conversations APIs directly?
Only when built-in Get User does not expose the required data. Zendesk says this is unnecessary in most cases.
How does a flow find a Sunshine user?
For the advanced integration pattern, List Participants uses platformConversationId to obtain userId, then Get User retrieves the needed profile data.
Which API scope should a Zendesk customer use?
Use the documented app or integration scope for the endpoint. Account scope is not applicable to Zendesk customers.
