File Attachments

Images, documents, audio, and video move through Outeract as File records connected to message events by attachment edges. This guide covers the file lifecycle: receiving files on inbound messages, uploading your own, sending them with sendMessage, and reading the bytes back out.

File operations run on the developer API at https://api.outeract.com/ (Authorization: Bearer <api-key>). Creating files requires the events:write scope.

The File Model

Field	Type	Description
`id`	UUID	Unique identifier
`appId`	UUID	Application this file belongs to
`url`	string	Client-usable URL (GCS references resolve to time-limited signed URLs)
`dataUri`	string	Inline `data:<mime>;base64,...` URI of the file contents (on demand)
`storageType`	enum	`EMBEDDED` (data URI in the database) or `GCS` (Google Cloud Storage / external URL)
`status`	string	Processing status (`completed` for usable files)
`mimeType`	string	MIME type, e.g. `image/png`
`size`	int	Size in bytes
`filename`	string	Original filename, if known
`description`	string	Optional caption / description
`createdAt`	datetime	When the record was created

The raw storage reference is internal. Clients always read url (resolved at query time) or dataUri (bytes inlined at query time).

Lifecycle

flowchart LR
    subgraph Inbound
        W["Platform webhook<br/>(media message)"] --> F1["File record"]
        F1 -->|attachment edge| E1["message.inbound event"]
    end
    subgraph Outbound
        U["createFile mutation"] --> F2["File record"]
        F2 -->|fileIds| S["sendMessage"]
        S -->|attachment edge| E2["message.outbound event"]
        E2 --> P["Delivered to platform"]
    end

Files on Inbound Messages

When a user sends media on a connected platform, Outeract stores the content as a File and links it to the message.inbound event with an attachment edge. Read attachments straight off the event:

query {
  events(first: 20, eventTypes: ["message.inbound"]) {
    edges {
      node {
        id
        eventType
        payload
        attachments {
          id
          mimeType
          size
          filename
          url
        }
      }
    }
  }
}

Uploading Files

createFile mints a File record you can then attach to outgoing messages. Provide exactly one of data or url:

From base64 data

```graphql mutation { createFile( mimeType: "image/png" data: "iVBORw0KGgoAAAANSUhEUg..." filename: "receipt.png" description: "January receipt" ) { id url storageType size } } ``` `data` accepts a bare base64 string or a full `data:image/png;base64,...` URI. The bytes are stored via the configured storage backend: Google Cloud Storage when configured, otherwise embedded in the database as a data URI.

From a URL

```graphql mutation { createFile( mimeType: "application/pdf" url: "https://example.com/report.pdf" filename: "report.pdf" ) { id url storageType } } ``` An `http(s)` URL is stored **by reference**, and the bytes are downloaded at send time. A `data:` URI passed as `url` is stored embedded.

The mutation returns the File with status: "completed", ready to send. Passing both data and url (or neither) is an error, as is invalid base64.

Sending Files

Pass file IDs to sendMessage. The message text is optional when attachments are present:

mutation {
  sendMessage(
    recipientUserId: "user-uuid"
    message: "Here is your receipt"
    fileIds: ["file-uuid"]
  ) {
    id
    eventType
    attachments {
      id
      mimeType
    }
  }
}

For each file, Outeract creates an attachment edge from the outbound message event to the File, then delivers the media through the platform integration.

A `sendMessage` call must include at least one of `message`, `template`, or `fileIds`.

Downloading and Accessing Content

By URL

url is the cheap path. Embedded data URIs and external URLs pass through unchanged; GCS-stored files resolve to a time-limited signed HTTPS URL at query time, so fetch it promptly rather than persisting it.

query {
  files(fileIds: ["file-uuid"]) {
    id
    mimeType
    size
    url
  }
}

Inline with dataUri

dataUri returns the file contents as a data:<mime>;base64,... string regardless of where the file is stored: embedded files return their stored URI directly, while GCS-stored and externally hosted files are fetched and encoded on demand. This is convenient when the consumer can’t follow URLs (e.g. feeding an image directly to an AI model).

query {
  files(fileIds: ["file-uuid"]) {
    id
    mimeType
    dataUri
  }
}

`dataUri` is only computed when your query selects it, but it inlines the entire file into the GraphQL response. Prefer `url` unless you actually need the bytes in-band, and avoid selecting `dataUri` across large file lists.

If the underlying bytes can’t be fetched (e.g. an unreachable external URL), dataUri returns null.

Attachment Edges in the Graph

Attachments are ordinary graph edges: source is the message event, target is the file, edgeType is attachment. That means you can traverse them like any other relationship:

# All attachment edges for a batch of events
query {
  edges(eventIds: ["event-uuid-1", "event-uuid-2"], edgeType: "attachment") {
    sourceNodeId
    targetNodeId
    edgeType
  }
}

You can also filter the event stream by a related file. For example, every event that references a given file:

query {
  events(
    relatedNodeId: "file-uuid"
    relatedNodeType: "file"
    relatedEdgeType: "attachment"
  ) {
    edges {
      node {
        id
        eventType
        createdAt
      }
    }
  }
}