Skip to main content

Sharing

Introduction​

In DIAL, resources refers to conversations, prompts, files, and applications. When a resource is created or uploaded to DIAL, it is stored in a dedicated storage bucket. You can use both DIAL Chat UI and API to share resources with other users or applications.

When a resource is shared, it becomes available in DIAL Chat and DIAL Marketplace, where users (with whom the resource has been shared) can discover and utilize it.

DIAL API​

There are two sides in the sharing process: the resource owner and the resource recipient. DIAL Sharing API has endpoints to facilitate workflows for either of them.

Endpoints for resource owners​

This table lists endpoints that resource owners can use to share resources and manage shared resources:

EndpointDescription
createResource owners can use this endpoint to share a resource by creating an invitationLink which includes an invitationId.
Permissions:
- You can grant READ or WRITE access to your resource. Note: If an app/user changes the shared resource, HTTP etag is used by DIAL Core to determine versioning and resolve conflicts. You can use Subscription API to get notifications about changes made by other users or applications.
- Include a SHARE permission to enable recipients of the shared resource to re-share it with READ permissions. Use maxAcceptedUsers to apply limits on the number of users who can accept the invitation link - the default value is unlimited. Refer to Re-Sharing to learn more.
Limitations:
- The system does not support getting all the recipients of a shared resource.
- SHARE permission can be used only in combination with other permission types.
- Re-sharing is possible only with READ permission.
copyUse this endpoint to add permissions for users to access a new resource.
If a conversation with attachments has already been shared and a new attachment is added, this endpoint ensures that other users can access the updated shared resource, including the newly added attachment.
This ensures proper access control for all shared components of the resource.
listUse this endpoint to query the details of all resources that were shared by you. In the request body, provide "with": "others" to do that.
Note, that in case you share a conversation with attachments, attachments are shared as well, but they will appear in the response as a separate shared resources.
revokeUse this endpoint if you want to stop sharing a resource. As a result, the shared content becomes inaccessible to all recipients who previously had access to it, and any invitation link associated with it will no longer be valid for future use.
invitationsInvitations are created together with sharing resources using /create endpoint. Use /invitations endpoint to query a list of all active invitations you have created.
invitations/{Invitation ID}Use this endpoint with the DELETE method to revoke a specific invitation.

Endpoints for resource recipients​

This table lists endpoints that resource recipients can use to accept invitations and manage shared resources:

EndpointDescription
discardRecipients of a shared resource can use this endpoint to stop using shared resources. In this case, related resources will stop being marked as shared for the resource owner.
listUse this endpoint to query the details of all resources that were shared with you. In the request body, provide "with": "me" to do that.
invitations/{Invitation ID}Use this endpoint with the GET method to view invitation details and to accept an invitation.
createResource recipients can use this endpoint to re-share a resource by creating an invitationLink which includes an invitationId.
Permissions:
- You can grant READ access to the resource you want to re-share.

Workflow Examples​

Basic workflow​

  1. Resource owner shares a resource using the /create and provides the invitation link for the resource recipient.
  2. Resource recipient extracts the invitation id from the invitation link calls the /invitations/{Invitation ID} endpoint to accept the resource.
  3. Resource recipient can now get the list of shared resources with their details via /list.

Revoke workflow​

  1. Resource owner shares a resource via /create and provides the invitation link for the resource recipient.
  2. Resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
  3. Resource owner revokes access to the shared resource via /revoke.
  4. Resource recipient cannot access the shared resource any longer.

Re-share workflow​

  1. Resource owner shares a resource via /create (with the SHARE permission type) and provides the invitation link for the resource recipient.
  2. Resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
  3. Resource recipient can re-share the resource using the /create endpoint and provide the new invitation link for the new resource recipient.
  4. New resource recipient extracts the invitation id from the invitation link and calls the /invitations/{Invitation ID} to accept the resource.
  5. New resource recipient can now get the list of shared resources with their details via /list.

Re-Sharing​

Resource owners can share resources with the SHARE permission type, which allows resource recipients to re-share the resource with other users or applications. When a resource is re-shared, the new recipient can only access the resource with READ permissions.

In the re-sharing case, a specific validation takes place:

  • The DIAL Core API will validate if the resource can be re-shared by examining if the resource's owner shared the resource with the permission SHARE. Otherwise, DIAL Core returns 400.
  • The DIAL Core API will validate invitation TTL by taking the invitation_ttl value from the DIAL Core dynamic settings.
  • The DIAL Core API will validate the permission set for the re-shared resource. The permission WRITE is not allowed to re-share resources: DIAL Core returns 400(Invalid permissions set. The permission READ is allowed for re-sharing only).
  • The DIAL Core API will validate the number of accepted invites per shared resource (based on max_accepted_users in the DIAL Core dynamic settings) and per invitation request (based on maxAcceptedUsers in the original share request). If the number exceeds the author's share limit, DIAL Core returns the error 400(The limit of maximum accepted invites is reached).

DIAL Chat UI​

Chat users can share their resources with others, accept sharing invitations, and view resources that have been shared by or with them. When conversations that include attachments are shared, all attachments are also shared and can be accessed through the chat file manager.

Refer to DIAL Chat user guide for details: