Huddo (Cross-App) Tools¶

The huddo_* tools work across Huddo apps: they tell an assistant who the user is and what's installed, catch the user up on recent activity, work out what a pasted URL points to, and handle comments, links and files on pages, ideas and spaces alike.

huddo_whoami is in the core tool group. The rest are in the crossapp group.

huddo_whoami¶

Tells the assistant who the signed-in user is and which Huddo apps this install has. Assistants are told to call it first, since its app list says which other tools apply.

Read-only · Needs: Huddo

This tool takes no parameters.

Returns: the user's id, name, email and locale; their current organisation (id, name and role); up to 10 orgs they belong to, with their role in each; and apps, the installed apps with their URLs.

Example: "Which Huddo apps do I have access to?"

huddo_resolve¶

Works out what a Huddo URL points to: the app, the kind of thing (page, wiki, whiteboard, lab, idea, space or link), its ids, and its title. Every tool that takes a url does this for itself, so assistants use this tool mainly to check a link before deciding what to do with it.

Read-only · Needs: Huddo

Parameter	Type	Required	Default	Notes
`url`	URL	Yes		A Huddo URL, up to 2,048 characters

Returns: outcome and, depending on it, the app, type, ids, slugs and title:

resolved: the URL is a Huddo object and the app confirmed it.
parsed: the URL has a known Huddo shape, but there's no tool to read that kind of object yet.
unresolvable: the URL isn't a Huddo object, for example a URL on another site.

Example: "What is this link? https://connections.example.com/huddo/wikis/..."

huddo_recent¶

What the user opened or worked on lately across Huddo, newest first: links they opened, wiki pages, ideas and labs, and spaces they visited.

Read-only · Needs: Huddo (each app is included only when it's installed)

Parameter	Type	Required	Default	Notes
`limit`	integer	No	20	1 to 50

Returns: items, each with app, type, title, url and at (when); apps, the apps that were checked; and unavailable, any app that couldn't be read just now (the others are still listed).

Example: "Where was I yesterday? Show me what I was working on."

huddo_digest¶

The user's week in one call: their newest unread notifications, and for each of their most recently visited spaces, the wiki page changes and the activity in its active idea labs since a date.

Read-only · Needs: Notifications (wiki changes need Wikis, lab activity needs Ideas, and spaces need Spaces)

Parameter	Type	Required	Default	Notes
`since`	date or date-time	No	A week ago	Where wiki changes and lab activity start. It doesn't limit the inbox
`spaces`	array of strings	No		Up to 3 space slugs. Without it, the user's 3 most recently visited spaces

Returns:

since, the start date.
inbox: unreadTotal, the number of all unread notifications, and the newest unread items, however old, up to 8 (type, title, URL).
spaces: for each space, its name and url; up to 5 recent page changes (what changed, which page and wiki, by whom and when); and up to 2 active labs, each with its question, url, newIdeas (the number of new ideas since since) and mostVotedSince, a list holding the idea with the most votes cast or changed since since, with its id, title, votes and url (left out when there's no such idea).
unavailable: any part that couldn't be read, for example because an app isn't installed. The rest of the digest is still returned.

Example: "Give me my weekly digest."

huddo_get_comments¶

Reads the comments on an idea, a space's feed or a wiki page. A wiki page can have several threads: comments on the page as a whole, and inline comments on a passage of text.

Read-only · Needs: Discussions

Parameter	Type	Required	Default	Notes
`url`	URL	No		The URL of the idea, space or page
`app`	string	No		Instead of `url`: `ideas`, `spaces` or `wikis`
`type`	string	No		Instead of `url`: `idea`, `space` or `page`
`id`	string	No		Instead of `url`: the idea id, the space slug or the page id
`discussionId`	id	No		Read one thread of a wiki page on its own (from an earlier answer)
`messages`	integer	No	20	1 to 50. The number of newest posts to return
`offset`	integer	No	0	Newest posts to skip, to read older ones. Pass `nextOffset` from an earlier answer
`maxChars`	integer	No	1,000	100 to 10,000. The most characters of each message
`totalChars`	integer	No	20,000	1,000 to 60,000. The most characters returned in total

Give either url, or app, type and id.

Returns: the title and url of what was commented on, and the messages, newest post first. Each message has its text as Markdown, author, time, reactions and up to the last 10 replies. For a wiki page, up to 20 threads, page threads first, then inline ones (with the quoted text), each with its discussionId. truncated and nextOffset say when there are more.

Example: "What are people saying in the comments on the Q3 roadmap page?"

huddo_comment¶

Posts a comment on an idea, a space's feed or a wiki page, or replies to an existing comment. The people in mentionUserIds are mentioned and notified.

Write · Needs: Discussions

Parameter	Type	Required	Default	Notes
`url`	URL	No		The URL of the idea, space or page
`app`	string	No		Instead of `url`: `ideas`, `spaces` or `wikis`
`type`	string	No		Instead of `url`: `idea`, `space` or `page`
`id`	string	No		Instead of `url`: the idea id, the space slug or the page id
`discussionId`	id	No		Wiki pages only: the thread to post in. Without it, each comment starts a new thread
`replyTo`	id	No		A message to reply to. On a wiki page, also give `discussionId`
`body`	string	Yes		Markdown, 1 to 20,000 characters. Headings, images and tables become plain text
`mentionUserIds`	array of user ids	No	None	Up to 20 people to mention, for example from `core_find_people`

Returns: discussionId, messageId, parentMessageId (for a reply), url, and unresolvedMentions, any id that couldn't be mentioned because it isn't a known person.

Example: "Reply to Sam's comment on that idea saying we'll trial it next sprint, and mention Priya."

huddo_link¶

Adds a link from a page, idea, lab or space to any web address, so it shows among that object's links and its clicks are counted. The user needs edit rights on the object.

Write · Needs: Links

Parameter	Type	Required	Notes
`url`	URL	No	The Huddo URL of the object to add the link to
`service`	string	No	Instead of `url`: `wikis`, `ideas`, `spaces` or `links`
`objectType`	string	No	Instead of `url`: the kind of object
`objectId`	string	No	Instead of `url`: the object's id
`to`	URL	Yes	The `http` or `https` address to link to
`title`	string	No	Up to 300 characters

Returns: the link's refId (used by huddo_unlink), slug, url, title and source, and the object it was added to.

Example: "Add a link to our design spec on the Onboarding space."

huddo_unlink¶

Removes a link that was added with huddo_link (or by hand in Huddo). Links that come from an object's content can't be removed this way; they go when the content changes. Only the link's place on that object is removed: the address's other places and its click counts stay.

Delete · Needs: Links

The user must have added the link and be able to contribute to the object, or be able to edit the object. The link can be added again, but the removal itself can't be undone.

Parameter	Type	Required	Default	Notes
`refId`	id	Yes		The link's ref id, from `huddo_link` or `huddo_related`

Returns: deleted and the refId.

Example: "Remove the old Confluence link from the Onboarding space."

huddo_related¶

What's related to a page, idea, lab or space: the links it holds, the other objects that link to it (backlinks), and, given a query, search results from inside it (within a page and the pages under it, or within a lab).

Read-only · Needs: Links (searching inside also needs Search)

Parameter	Type	Required	Default	Notes
`url`	URL	No		The Huddo URL of the object
`service`	string	No		Instead of `url`: `wikis`, `ideas`, `spaces` or `links`
`objectType`	string	No		Instead of `url`: the kind of object
`objectId`	string	No		Instead of `url`: the object's id
`query`	string	No		Words to search for inside the object, up to 1,000 characters
`include`	array of strings	No	`links`, `backlinks` and `search`	Any of `links`, `backlinks` and `search`

Returns: the object; up to 20 links (title, URL, kind, source, and the refId of links that were added by hand); up to 20 backlinks (title, where it is, URL); and up to 10 search results.

Example: "What links to the Incident Response page?"

huddo_upload_file¶

Attaches a file to a wiki page, an idea or a space, and returns a link to put in a page, idea or comment. Attach the file to the object that will show it: a file belongs to the object it's attached to, so people who can't see that object can't see the file, and it goes when that object is deleted.

Write · Needs: file attachments

Parameter	Type	Required	Notes
`url`	URL	No	The URL of the page, idea or space
`app`	string	No	Instead of `url`: `ideas`, `spaces` or `wikis`
`type`	string	No	Instead of `url`: `idea`, `space` or `page`
`id`	string	No	Instead of `url`: the idea id, the space slug or the page id
`discussionId`	id	No	Instead of the above: a comment thread. The file goes on the page, idea or space it belongs to
`filename`	string	Yes	1 to 255 characters, with no characters that file names can't hold, such as `/`, `\` or `:`
`mimeType`	string	Yes	One of the accepted types below
`content`	string	Yes	The file, base64-encoded. Up to 10 MiB once decoded
`description`	string	No	Up to 2,000 characters

Accepted types: PNG, JPEG, GIF and WebP images (image/png, image/jpeg, image/gif, image/webp), PDF (application/pdf), Word, Excel and PowerPoint (.docx, .xlsx, .pptx), plain text (text/plain), CSV (text/csv), Markdown (text/markdown) and JSON (application/json).

Returns: fileId, url, markdown (an image or link to paste into Markdown) and attachedTo, where the file lives.

Example: "Add this architecture diagram to the System Overview page."

huddo_delete_file¶

Permanently deletes an uploaded file. Anywhere the file is shown, such as an image on a page or a link to it, breaks. The user needs edit rights on the object the file belongs to.

Delete · Needs: file attachments

Parameter	Type	Required	Default	Notes
`fileId`	id	Yes		From `huddo_upload_file`
`confirmFilename`	string	Yes		The file's exact name. A name that doesn't match is refused

Returns: deleted, fileId, filename and attachedTo.

Example: "Delete the draft-diagram.png I uploaded to the System Overview page."