Unfurl a link
POST/chat.unfurl
Attach app-provided preview cards to links in an existing text message. Every map key must be an exact URL currently present in the message and must match one of the app's registered unfurl domains. Validation is atomic: if any entry is invalid, no previews are changed.
App previews replace Roam-generated previews for the same exact URL while preserving unrelated previews. The server does not fetch any URL supplied in this request.
Access: Organization only (API Key or OAuth). Register unfurl domains on the API client first — see Unfurling links. Personal Access Tokens cannot register domains or call this endpoint.
Required scope: links:write
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 405
- 409
- 500
Preview cards applied successfully.
Invalid parameters or cannot_unfurl_url when a URL is absent from the message or outside the app's registered domains.
Presented invalid authentication credentials.
Missing links:write scope or no access to the chat.
The chat or message was not found.
An unsupported method was requested.
The message changed twice while previews were being applied; retry the request.
An internal error occurred.