Reserve a direct upload from the widget

Reserves storage for a file and returns a one-time URL to PUT the bytes to. Two steps, not one:

POST here with the file’s name, size, MIME type and base64 MD5 checksum.
PUT the bytes to direct_upload.url with the headers it gives you. The upload is rejected if the bytes disagree with the size or checksum you declared.

Then send signed_id as the attachment when you create the message. This is the widget’s only upload path — the account-level POST /upload needs an api_access_token, which a widget session does not have.

POST

api

widget

direct_uploads

Reserve a direct upload from the widget

curl --request POST \
  --url https://app.tied.com/api/v1/widget/direct_uploads \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "blob": {
    "filename": "receipt.png",
    "byte_size": 27,
    "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
    "content_type": "image/png"
  }
}
'

import requests

url = "https://app.tied.com/api/v1/widget/direct_uploads"

payload = { "blob": {
        "filename": "receipt.png",
        "byte_size": 27,
        "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
        "content_type": "image/png"
    } }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    blob: {
      filename: 'receipt.png',
      byte_size: 27,
      checksum: 'janaQDJaHWRN47FY/qJ9kQ==',
      content_type: 'image/png'
    }
  })
};

fetch('https://app.tied.com/api/v1/widget/direct_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/widget/direct_uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"blob\": {\n    \"filename\": \"receipt.png\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"image/png\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/widget/direct_uploads"

	payload := strings.NewReader("{\n  \"blob\": {\n    \"filename\": \"receipt.png\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"image/png\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Auth-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 22,
  "key": "8n6pgvrx80plu9nx49f6czgh7jq1",
  "filename": "receipt.png",
  "content_type": "image/png",
  "metadata": {},
  "byte_size": 27,
  "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
  "created_at": "2026-09-21T05:13:10.955Z",
  "service_name": "local",
  "attachable_sgid": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJalZuYVdRNkx5OWphR0YwZDI5dmRDOUJZM1JwZG1WVGRHOXlZV2RsT2pwQ2JHOWlMekl5UDJWNGNHbHlaWE5mYVc0R09nWkZWQT09IiwiZXhwIjpudWxsLCJwdXIiOiJhdHRhY2hhYmxlIn19--EXAMPLE",
  "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBHdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--EXAMPLE",
  "direct_upload": {
    "url": "https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/asset.png",
    "headers": {
      "Content-Type": "image/png"
    }
  }
}

{
  "error": "Resource could not be found"
}

Authorizations

X-Auth-Token

string

header

required

The signed session token from POST /api/v1/widget/config. Sent alongside website_token in the query string on every widget request. See /api-reference/widget-api-authentication.

Query Parameters

website_token

string

required

The web-widget inbox's public token, as it appears in your widget snippet. Required on every widget request.

Example:

"EXAMPLE_WEBSITE_TOKEN"

Body

application/json

blob

object

required

Describe the file before sending it. All four fields are required, and the subsequent PUT is rejected if the bytes disagree with byte_size or checksum.

Show child attributes

Response

Success

The stored blob plus the one-time URL to PUT the bytes to. This is Rails' ActiveStorage direct-upload response, passed through unchanged.

integer

The blob's numeric ID.

key

string

The storage key.

filename

string

The filename you declared.

content_type

string

The content type you declared.

byte_size

integer

The size you declared. The upload is rejected if the bytes do not match it.

checksum

string

The base64 MD5 you declared. The upload is rejected if the bytes do not match it.

metadata

object

Metadata ActiveStorage derives once the bytes arrive.

service_name

string

Which storage service holds it.

created_at

string

ISO-8601 timestamp.

signed_id

string

What you send as the attachment reference when creating the message.

attachable_sgid

string

Signed global ID for the blob, used by rich-text attachment flows.

direct_upload

object

Where and how to send the bytes.

Show child attributes

Reserve a direct upload from the widget

curl --request POST \
  --url https://app.tied.com/api/v1/widget/direct_uploads \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "blob": {
    "filename": "receipt.png",
    "byte_size": 27,
    "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
    "content_type": "image/png"
  }
}
'

import requests

url = "https://app.tied.com/api/v1/widget/direct_uploads"

payload = { "blob": {
        "filename": "receipt.png",
        "byte_size": 27,
        "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
        "content_type": "image/png"
    } }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    blob: {
      filename: 'receipt.png',
      byte_size: 27,
      checksum: 'janaQDJaHWRN47FY/qJ9kQ==',
      content_type: 'image/png'
    }
  })
};

fetch('https://app.tied.com/api/v1/widget/direct_uploads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

require 'uri'
require 'net/http'

url = URI("https://app.tied.com/api/v1/widget/direct_uploads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"blob\": {\n    \"filename\": \"receipt.png\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"image/png\"\n  }\n}"

response = http.request(request)
puts response.read_body

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.tied.com/api/v1/widget/direct_uploads"

	payload := strings.NewReader("{\n  \"blob\": {\n    \"filename\": \"receipt.png\",\n    \"byte_size\": 27,\n    \"checksum\": \"janaQDJaHWRN47FY/qJ9kQ==\",\n    \"content_type\": \"image/png\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Auth-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 22,
  "key": "8n6pgvrx80plu9nx49f6czgh7jq1",
  "filename": "receipt.png",
  "content_type": "image/png",
  "metadata": {},
  "byte_size": 27,
  "checksum": "janaQDJaHWRN47FY/qJ9kQ==",
  "created_at": "2026-09-21T05:13:10.955Z",
  "service_name": "local",
  "attachable_sgid": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJalZuYVdRNkx5OWphR0YwZDI5dmRDOUJZM1JwZG1WVGRHOXlZV2RsT2pwQ2JHOWlMekl5UDJWNGNHbHlaWE5mYVc0R09nWkZWQT09IiwiZXhwIjpudWxsLCJwdXIiOiJhdHRhY2hhYmxlIn19--EXAMPLE",
  "signed_id": "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBHdz09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--EXAMPLE",
  "direct_upload": {
    "url": "https://app.tied.com/rails/active_storage/blobs/proxy/EXAMPLE/asset.png",
    "headers": {
      "Content-Type": "image/png"
    }
  }
}

{
  "error": "Resource could not be found"
}

Getting started

Conversations

Contacts

Inboxes and channels

Automation and routing

Reporting

Help Center

Account and access

Billing

Client API

Widget API

Receiving webhooks

Reserve a direct upload from the widget

Authorizations

Query Parameters

Body

Response