Links Tools¶
The links_* tools work with the user's bookmarks and with the links that appear across Huddo: finding them, saving them, seeing where they appear and how often they're clicked, and previewing a web page safely.
All six tools are in the links tool group and need Huddo Links. To add a link to a page, idea or space, see huddo_link.
A link that your organisation's link rules block comes back with its domain only, never its title or address.
links_find¶
Lists links: the user's own bookmarks, links they opened lately, bookmarks shared with the organisation, or links that appear anywhere in Huddo the user can see, with where they appear.
Read-only · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
scope |
string | No | mine |
mine (the user's bookmarks), recent (opened lately), org (shared with the organisation) or across (anywhere in Huddo) |
tag |
string | No | mine and org only: a tag to filter by, up to 40 characters |
|
query |
string | No | Words to match in the title, address, notes or tags, up to 200 characters | |
domain |
string | No | Part of a domain to match, up to 200 characters | |
before |
string | No | across only: next from an earlier answer, to read the next page |
|
limit |
integer | No | 20 | 1 to 50 |
withTags |
boolean | No | false | Also list up to 100 of the user's tags, with counts |
Returns: scope, links and total. Each link has its slug, title, url, domain and description; bookmarks also have tags, notes, visibility and bookmarkId; recent links have openedAt; and links from across have placeCount and up to 3 places where they appear. Also next (for across) and tags (with withTags).
Example: "Find the bookmarks I've tagged onboarding."
links_get_link¶
Details for one link: its card, every place in Huddo the user can see it in, and, if asked for, how often it's been clicked. Given a web address instead of a slug, it returns the card Huddo shows for that address (title, description and state), without the places.
Read-only · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
slug |
string | No | The link's slug, from links_find or huddo_related |
|
url |
URL | No | Instead of slug: a web address |
|
withClicks |
boolean | No | false | Include click totals |
days |
integer | No | 30 | 30 or 90: the period the click totals cover |
Give either slug or url.
Returns: for a slug, the link's slug, url, domain, title, description, bookmarkId (when the user has bookmarked it), up to 20 occurrences (where it appears, with title and URL) and occurrenceCount, and with withClicks, clicks (total, unique users, direct clicks and clicks by source). For a url: title, excerpt, state and contextLabel. Not found means the user can't see the link anywhere.
Example: "How many people clicked the benefits portal link in the last 90 days?"
links_preview¶
A safe preview of any web page, fetched by Huddo under your organisation's link rules: where the address ends up after redirects, and its title, description and site name.
Read-only · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url |
URL | Yes | An http or https address |
Returns: url (after redirects), title, description and siteName. A page blocked by the organisation's link rules, or one that can't be fetched, says so instead.
Example: "What's at this link before I open it?"
links_save¶
Bookmarks a web address for the user, with an optional title, notes and tags. Saving an address that's already bookmarked changes only the fields given.
Overwrite · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
url |
URL | Yes | An http or https address, up to 2,048 characters |
|
title |
string | No | Up to 300 characters | |
notes |
string | No | Up to 2,000 characters | |
tags |
array of strings | No | Up to 20 tags, each 1 to 40 characters, with no spaces or commas. Replaces existing tags | |
visibility |
string | No | private |
private, or org to share the bookmark with everyone in the organisation |
Returns: the bookmark, including its bookmarkId, and existed, true when the address was already bookmarked. pending means Huddo hasn't fetched the page's title and summary yet.
Example: "Bookmark https://example.com/style-guide and tag it design."
links_update_bookmark¶
Changes a bookmark's title, notes, tags or visibility. Only the fields given change.
Overwrite · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
bookmarkId |
id | Yes | From links_find or links_save |
|
title |
string | No | Up to 300 characters | |
notes |
string | No | Up to 2,000 characters | |
tags |
array of strings | No | Up to 20 tags, with no spaces or commas. Replaces existing tags | |
visibility |
string | No | private, or org to share the bookmark with the organisation |
Returns: the updated bookmark.
Example: "Share my style guide bookmark with the whole organisation."
links_delete_bookmark¶
Permanently deletes one of the user's own bookmarks. Only the bookmark goes: the link itself, its click counts and the places it appears stay.
Delete · Needs: Links
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
bookmarkId |
id | Yes | From links_find or links_save |
|
confirmUrl |
string | Yes | The bookmark's exact address. An address that doesn't match is refused |
Returns: deleted, bookmarkId, url and title.
Example: "Delete my bookmark for the old intranet."