# useDocyrusAgentAttachments
URL: /docs/native/hooks/use-docyrus-agent-attachments

Uploads chat attachments to a Docyrus agent thread (creating the thread on first use) and returns the storage paths for the chat request.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-agent-attachments
```

**Dependencies:**
- [ai](https://www.npmjs.com/package/ai)

Port of the web hook with one native change: the web hook fetches each file's `blob:` URL; on React Native `FileUIPart.url` is the local `file://` / `content://` URI returned by the picker, so the upload appends the RN FormData file shape `{ uri, name, type }` instead. Thread state is **controlled**: pass the active `threadId` (`null` for a new chat) and capture the created id with `onThreadCreated`. [`useDocyrusAgentChat`](/docs/native/hooks/use-docyrus-agent-chat) already embeds it.

Endpoints: `POST /v1/apps/base/data-sources/thread/items` (create thread, `thread_type: 'assistant'`) and `POST /v1/apps/base/data-sources/thread/items/{threadId}/files/upload` (multipart `file`).

## Usage

```tsx
const [threadId, setThreadId] = useState<string | null>(null);
const { resolveFilePaths, ensureThread } = useDocyrusAgentAttachments({
  client, agentId: AGENT_ID, threadId, onThreadCreated: setThreadId
});

const onSendMessage = async ({ text, files }: AgentMessagePayload) => {
  await ensureThread(text);
  const { filePaths } = files?.length ? await resolveFilePaths(files, text) : { filePaths: [] };

  await sendMessage({ text }, { body: { files: filePaths, supportFiles: filePaths.length > 0 } });
};
```

## API Reference

### UseDocyrusAgentAttachmentsArgs

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `DocyrusAgentAttachmentsClient \| null \| undefined` | - | Client with `post(url, body)` |
| `agentId` | `string` | - | Tenant AI agent ID (required) |
| `threadId` | `string \| null` | - | Current thread; `null` → first call creates one (required) |
| `onThreadCreated` | `(threadId: string) => void` | - | Fires when a new thread is created |
| `projectId` | `string \| null` | `null` | Project scope of new threads |
| `deploymentId` | `string \| null` | `null` | Deployment scope of new threads |
| `senderName` | `string` | `'User'` | `sender_name` of new threads |
| `threadSubject` | `(messageText: string) => string` | first 100 chars | Subject of new threads |

### UseDocyrusAgentAttachmentsResult

| Field | Type | Description |
|-------|------|-------------|
| `resolveFilePaths` | `(files: FileUIPart[], messageText: string) => Promise<{ filePaths: string[]; threadId: string \| null }>` | Uploads every file, returns storage paths |
| `ensureThread` | `(messageText: string) => Promise<string \| null>` | Returns the current thread id or creates one |