Upload a file

Stores one file for the account and returns its public address. This is how a user’s own images, video and PDFs reach a widget’s content.

Send a multipart/form-data request with the file in the field named file. The file counts against the storage of the workspace it is uploaded in, and a full workspace is refused with 413 and QUOTA_STORAGE_EXCEEDED. For a person signed in on widgetic.com that is the workspace they are currently working in: inside a team, the team’s shared storage; inside their own workspace, their own allowance. An organization API key, and a Shopify store’s session, always work in that team’s shared storage. A personal API key or an SDK token always uses the account’s own allowance. The two never add up and one never lends room to the other. A file over the size limit is refused with 413 and UPLOAD_TOO_LARGE, and a type that is not accepted with 415 and UPLOAD_UNSUPPORTED_TYPE; getUploadLimits lists the size limit and the accepted types.

A file is judged by what is in it, not by the type it is sent as. A file that is not the type it claims (a web page sent as image/png) is refused with 415 and UPLOAD_UNSUPPORTED_TYPE, and a picture sent under the wrong picture type is stored under the type it really is, which mime_type in the answer says. An SVG is rewritten as it is stored: script, foreignObject, animation and references to other addresses are taken out, it must be UTF-8 and at most 2 MB, and the stored file can be larger or smaller than the one sent. Anything that is not an image, audio or video (a PDF, for example) is served as a download rather than shown in a page.

When the full storage is a Shopify store’s team’s, extra storage cannot be added through Shopify yet, so the message ends by saying so and what to do instead: delete files, or contact support. On a Solo plan it names the Teams plan (which holds more) and error.details.planPageUrl is the address of the plan page on Shopify. error.suggestedAction says the same in a few words, instead of the usual “upgrade your storage plan”. Any other team, and a person’s own workspace, get the shorter message.

To upload the file for one of your managed users, send managedUserId (Widgetic’s id for the user) or managedUserExternalId (your own identifier for the user), not both. The file stays in your account and counts against its allowance; the tag lets you list one user’s files with listUploads. The managed user must be yours and active: one that is not yours, or does not exist, is refused with 404 and MANAGED_USER_NOT_FOUND, and one that is switched off with 409 and MANAGED_USER_INACTIVE, before the file is stored. The tag is set here and does not change afterwards.

Called with an editor session (createManagedUserEditorSession), the file is always filed for the session’s own managed user and is always media for widget content: naming another managed user is refused with 403 and MANAGED_USER_SESSION_MISMATCH, and contextType, source, widgetId and conversationId are ignored. A full storage allowance is refused with the same 413 and QUOTA_STORAGE_EXCEEDED, but the message only says that it is not available right now (not how much is stored: that is the partner’s business) and error.details.limit is storage.

An account that administers a partner with a storage destination (setPartnerStorageDestination) has its files stored in the partner’s own bucket instead. Such a file takes none of the allowance, its url is served from the partner’s public address, and its storage_key is the key in the partner’s bucket. The file is never stored with Widgetic instead: when the destination cannot be used the upload is refused with 503 and STORAGE_DESTINATION_UNAVAILABLE, and when the partner’s storage rejects the file with 502 and STORAGE_DESTINATION_WRITE_FAILED.

Partner storage is not optional, and it does not depend on how the file arrives. A partner’s own uploads (with its API key, an SDK token, or from the Widgetic website, the resumable route and the media library alike) and the uploads of its customers’ editor sessions are kept in the partner’s own storage or not at all, so a partner with no destination (or one that removed it after the session was made) has them refused with 409 and PARTNER_STORAGE_REQUIRED; they are never stored with Widgetic. An editor session’s browser is only told that the feature is not available right now.

POST /uploads

Upload a file

cURL

curl --request POST \
  --url https://api.widgetic.com/v1/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form contextType=content-property \
  --form source=file-browser-upload \
  --form managedUserId=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form 'managedUserExternalId=<string>'

200

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "Example url",
    "mime_type": "image/png",
    "file_name": "Example file_name",
    "file_size": 42,
    "width": 42,
    "height": 42,
    "storage_key": "Example storage_key",
    "context_type": "Example context_type",
    "source": "Example source",
    "widget_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "managed_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "purpose": "Example purpose"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

file · file · required

The file to store

contextType · enum<string> · default: content-property

What the file is for. Send content-property for media that becomes widget content (images, video and PDF); the other values are used by Widgetic's own editor.

Available options: widget-codegen, browser-ic, content-property

source · enum<string> · default: file-browser-upload

Which part of the product, or which client, the file comes from

Available options: chat-upload, chat-screenshot, browser-ic-screenshot, preview-screenshot, file-browser-upload

managedUserId · string<uuid>

Upload the file for one of your managed users, by Widgetic's id for the user. Send this or managedUserExternalId, not both.

managedUserExternalId · string

The same, by your own identifier for the user, the externalId you gave when you created the managed user. Send this or managedUserId, not both.

Maximum string length: 255

purpose · enum<string>

Where in your product you use the file. It is kept with the file, so that a customer's storage can be counted by purpose (getManagedUserStorageUsage). Optional; any other value is refused with 400 and UPLOAD_INVALID_PURPOSE.

Available options: canvas, chat, field

Response

200

application/json

The stored file

success · boolean · required

Always true on a success.

Example:

true

data · object · required

A file stored for the account that uploaded it.

Show child attributes

Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "Example url",
  "mime_type": "image/png",
  "file_name": "Example file_name",
  "file_size": 42,
  "width": 42,
  "height": 42,
  "storage_key": "Example storage_key",
  "context_type": "Example context_type",
  "source": "Example source",
  "widget_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "managed_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "purpose": "Example purpose"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes