# Create a chat message link

`POST /chat.link.create`

## Description

Create a shareable Roam link to a specific chat message. Opening the link
in Roam navigates to that message in its chat.

Identify the chat with exactly one of `chatId`, `groupId`, or `userIds`,
and the message by its `timestamp` (Unix microseconds), as returned by
[`/chat.history`](/docs/api/chat-history), [`/chat.post`](/docs/api/chat-post),
or webhook message events. For a thread reply, also pass the thread root's
timestamp as `threadTimestamp` — without it the reply will not be found.

The message must exist and be readable by the caller; otherwise no link is
returned (`404` if the message does not exist, `403` if the caller is not a
member of the chat). The link itself does not grant access: recipients can
only open it if they are members of the chat.

Use [`/chat.link.resolve`](/docs/api/chat-link-resolve) for the reverse
operation — turning a Roam chat link back into the referenced message.

**Access:** Organization and Personal. In Personal mode, only chats the
authenticated user can access are allowed.

**Required scope:** `chat:history`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatId` | string | No | ID of the chat containing the message. Exactly one of `chatId`, `groupId`, or `userIds` is required. |
| `groupId` | string | No | ID of a group whose channel chat contains the message. |
| `userIds` | string[] | No | User ID(s) identifying the DM or group DM containing the message. |
| `timestamp` | integer | Yes | The message's timestamp in Unix microseconds. |
| `threadTimestamp` | integer | No | The thread root's timestamp in Unix microseconds. Required when the message is a thread reply. |

### Example Request

```json
{
  "chatId": "295155ae-7df5-4ed5-9ebc-89a170559c81",
  "timestamp": 1765602474760032
}
```

## Responses

### 200 - Link created successfully.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `link` | string | Yes | Shareable Roam link that opens the message. |
| `chatId` | string | Yes | ID of the chat containing the message. |
| `timestamp` | integer | Yes | The message's timestamp in Unix microseconds. |
| `threadTimestamp` | integer | No | The thread root's timestamp. Omitted for top-level messages. |


#### Example Response

```json
{
  "link": "https://ro.am/r/#/c/KVFVrn31TtWevImhcFWcgQ/MTc2NTYwMjQ3NDc2MDAzMi9ub3Rocg",
  "chatId": "295155ae-7df5-4ed5-9ebc-89a170559c81",
  "timestamp": 1765602474760032
}
```

### 400 - Bad request. Common causes:
- Missing `timestamp`
- Timestamps that are not positive microseconds
- Missing or multiple destinations (`chatId`, `groupId`, `userIds`)
- Destination cannot be resolved to a chat


### 401 - Presented invalid authentication credentials.

### 403 - Caller is not a member of this chat.

### 404 - No message exists at the given timestamp. For thread replies, include `threadTimestamp`.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/chat-link-create*