DocumentationAPI Reference

Configuring private attachments for messaging

Zendesk messaging attachments enable both agents and end users to send and receive a variety of file types during a messaging conversation. This is helpful for providing detailed support, sharing necessary documents, and improving the overall communication experience. For more information, see About private attachments in messaging in Zendesk help.

This article describes how to configure private attachments for messaging and their limitations.

Enabling private attachments

Beginning December 5, 2024, private attachments will be automatically available to all new customers. If you are an existing customer and wish to use private attachments in messaging, please contact your sales or customer success representative.

Note: When using private attachments, make sure to also enable the Secure Downloads setting in Admin Center to ensure the security of attachments for both end users and agents. This setting controls whether agent-facing attachment URLs require authentication, and should be enabled to ensure attachments are always kept private.

Downloading private attachments

For end-users on Zendesk embeddables

When loading image and file attachments in one of Zendesk's embeddables, authentication will automatically be supplied on behalf of the end-user. Files and images should be seamlessly loaded using the same credentials that are already used to send and receive messages.

Consult the SDK compatibility section below to ensure that you are using a version of our embeddables that supports downloading private attachments.

For end-users on social messaging channels

For many channels, the attachment content will be directly uploaded to the channel's API, creating a copy of the attachment owned by the social platform. While Zendesk's copy will still require a Zendesk credential to access, the new copy of the attachment becomes the responsibility of the channel from that point on.

However, some channels do not support direct upload of attachments, and instead require attachments to be sent by URL. In these cases, a special URL is crafted which grants access to the attachment for 30 days, without requiring a credential to be supplied. After the 30 day period expires, the URL will then become invalid.

For agents in the Zendesk Agent Workspace

When private attachments are rendered to agents in Agent Workspace, an agent-facing URL is generated which differs from the URL that end-users would see. Files and images should be seamlessly loaded using the agent's pre-existing login session.

Access restrictions for agent-facing URLs are governed by the Secure Downloads setting, which needs to be enabled separately from private attachments in messaging - see the note above for more information.

From your backend

When private attachments are enabled, authorization is required to retrieve media using the Sunshine Conversations API. Below are considerations for downloading private attachments from your own backend.

Attachment URL format

Zendesk-hosted messaging attachments can be recognized by the following URL pattern:

https://{subdomain}.zendesk.com/sc/attachments/v2/{attachment_id}/{filename}

When private attachments are enabled for the account, authentication is required to load any attachments hosted at this location.

Getting the required credentials

The authorization required to load attachments follows the same rules as for authorizing the Sunshine Conversations v2 API. For information on how to generate API keys, see Using the Conversations API keys.

Fetching an attachment

As explained in the v2 API spec, either Basic Auth or a signed JWT may be supplied as authentication methods. The supported scopes for downloading attachments are: app, integration, and account.

For example, to fetch an attachment using Basic Auth, the key id should be supplied as the username and the secret as the password:

curl https://{subdomain}.zendesk.com/sc/attachments/v2/{attachment_id}/{filename} \     --user 'keyId:keySecret'

How requests for private attachments are evaluated

As explained in about private attachments in messaging, attachments can either be scoped to a particular conversation, or to the account as a whole. The following conditions outline how requests for private attachments are evaluated based on the provided credentials and attachment scope:

  • For conversation-scoped attachments:

    • End-users may only load attachments for conversations in which they are a participant
    • API credentials of scope app, account or integration may load attachments in any conversation belonging to the associated account

  • For app-scoped attachments:

    • End-users may only load attachments scoped to the account the user belongs to
    • API credentials of scope app, account or integration may load any attachments scoped to the associated account

Limitations of private attachments in messaging

SDK compatibility

To ensure private attachments load properly for your end-users, ensure you are using a supported version from the list below:

  • You must use a version greater or equal to iOS v2.26.0 or Android v2.26.0 if you want private attachments supported in native messaging SDKs.

  • If you are using the Sunshine Conversations web messenger, you must use version 5.6.6 or later. This version supports sending credentials for private attachments.

  • Sunshine Conversations iOS and Android SDKs do not support downloading private attachments.

Continuous conversations

When continuous conversations is enabled, an end user who exits an ongoing conversation on a website will receive an email if an agent replies. This allows the end user to easily locate and resume the conversation at their convenience, either by responding to the email directly or returning to the web widget.

However, if the agent’s response includes an attachment, the email will only contain the message and not the attachment.

If the end user opts to respond through email and not the widget, any attachments sent through the email will not sync with the web widget. While links to attachments included in the email may sync, the actual attachments will not.

Email transcripts

Sunshine Conversation attachments are shared as links within the conversation records included in email transcripts. When using private attachments, authentication will be necessary to access these attachments from conversations. The ability to authenticate and open these attachments may vary based on the device used by the end user. There may be situations where end users cannot authenticate. For example, if a transcript of a web widget conversation was sent to the end user's email, attempts to open the attachment from the email transcript will not succeed. This is because Zendesk cannot verify that the end user is the same user from the original web widget conversation.

Third-party bots and BYOC

Before implementing third-party bots or using Bring Your Own Chat (BYOC) solutions, verify that your vendor has completed all the necessary steps outlined in this article to enable private attachments.