Skip to content

Drafting with AI

UmbSocial AI is the AI add-on for UmbSocial Pro. In the composer it adds three things:

  • Draft with AI writes a new draft post from a short brief, or from a page on your own site.
  • Rewrite rewrites a channel’s own text to suit its network, or to make it shorter, friendlier or more formal.
  • Suggest alt text describes the post’s image for screen readers.

It works through Umbraco.AI, with the AI provider you choose. UmbSocial never stores a provider key: the key lives in Umbraco.AI’s connection.

AI only ever writes text for a person to check. It never schedules or publishes anything, and a post AI has helped to write can’t go on the calendar until someone who may review it puts it there (see Review before scheduling).

  • UmbSocial Pro, licensed for the site (a Pro or Agency licence). The AI add-on runs under the same licence and does nothing without one.
  • Umbraco.AI 17.7 or later, with a provider package for your AI provider.
  • We recommend Umbraco CMS 17.8.1 or later. Umbraco.AI brings in a version of the SixLabors.ImageSharp image library with known vulnerabilities; Umbraco CMS 17.8.1 depends on the fixed version, so a site on it gets that one instead.

These steps use Anthropic as the example provider. Any provider Umbraco.AI supports works the same way.

Terminal window
dotnet add package UmbSocial.AI
dotnet add package Umbraco.AI
dotnet add package Umbraco.AI.Anthropic

UmbSocial.AI brings UmbSocial Pro and Umbraco.AI’s core with it. Restart the site afterwards.

In the backoffice, go to AI › Connections, add an Anthropic connection and paste your Anthropic API key. Umbraco.AI stores the key; UmbSocial only ever refers to the connection.

Open Settings › UmbSocial › Schedule & writing. The AI box there sets itself up the first time it opens: UmbSocial creates a UmbSocial copywriter profile on your connection, and a UmbSocial brand voice context for you to fill in under AI › Contexts. You can choose another chat profile, or No brand voice. Save the page. AI Settings describes the box in full.

Draft with AI can start from a page, but only from a site listed under Sites to start from in the same box, such as example.com (which covers its subdomains too). Leave it empty to turn starting from a page off. Only list sites you trust: AI reads what the page says.

AI’s buttons need the UseAi permission on the user group (Users › User groups › (group), in the UmbSocial box). See Permissions below.

Open a new post in UmbSocial › Compose and choose Draft with AI. If the buttons stay disabled, hover over one to see why. “AI isn’t set up yet” means there is no working connection or chat profile: check steps 2 and 3.

Draft with AI is in the composer’s top bar. It opens a panel with two tabs:

  • Brief: what the post is about, in a sentence or two (up to 2,000 characters).
  • From a link: an https page on one of the sites listed under Sites to start from. UmbSocial reads the page itself (https only, on the listed sites only, every redirect checked again, at most 512 KiB, within 5 seconds) and passes its text to AI. The tab is disabled while no sites are listed.

Choose the channels the post is for, then Write draft. AI writes the main text, and its own version for any network that needs one (a shorter one for X, say). Two channels on the same network share that network’s version. Every text is checked against its network’s limit, counted the way the network counts it; an answer that doesn’t fit is sent back to AI once with the problem, and refused if it still doesn’t fit (ai.bad_output).

The new post opens as a draft. A draft from a page gets the page as its link, with the page’s own title and description on the link card (not AI’s), so check them as you would any link. A draft never gets alt text: add an image, then use Suggest alt text.

Draft with AI creates a separate post, so it can be used from any post, saved or not. If the post you are on has unsaved changes, Umbraco asks before leaving it.

Rewrite is on the card of each channel whose text you have customised (Customise for each channel), beside Use main text. Its menu has Rewrite, Shorter, Friendlier and More formal. The rewritten text replaces that channel’s text in the composer, counted with the post’s link as the network will count it. The text isn’t saved until you save the post, so you can change it or undo it, but the post is marked as written with AI straight away, even if you undo the text.

The main text has no Rewrite button: customise a channel’s text first.

Suggest alt text is beside the image’s alt-text field once the post has an image. UmbSocial sends the image to AI (scaled down first, if it is large) and puts the answer in the field, within the strictest alt-text limit of the post’s channels.

  • Rewrite and Suggest alt text work on the saved post, so they are disabled until the post has been saved (“Save the draft first”), and while the post can’t be changed (it is being sent, for example, or you may not change it).
  • All three are disabled while AI isn’t set up: no connection, or no chat profile.

Hover over a disabled button to see why.

A post AI has helped to write carries a tag in the composer’s top bar, and in the queue, the calendar and Published:

  • AI draft, needs review while it is a draft or awaiting approval;
  • AI-assisted once a reviewer has put it on the calendar.

When AI is used on a post, whether it drafted the post, rewrote a channel’s text or suggested its alt text, the server marks the post as written with AI. The mark stays for good: rewriting every word yourself doesn’t remove it, and it is set by the server alone, so no request can set or clear it. Using AI on a post that was already scheduled takes it back to a draft, which then needs reviewing again.

Such a post goes on the calendar only when a reviewer puts it there:

Approvals Who reviews
On (Pro) Anyone with Approve
Off Anyone with Approve or Schedule

On such a post, a reviewer’s Add to queue, Schedule and Approve buttons read Review and schedule.

Everyone else can still save the post as a draft. With approvals on, a writer submits it for approval as usual, and the composer explains: “Drafted with AI: someone with Approve must review it before it’s scheduled.” Anything else is refused with ai.needs_review, through the API as well as the composer. The reviewer is recorded on the post and in its History.

Writing and scheduling posts has the full rule, including how Umbraco API users are treated.

An Umbraco Automate automation can have an AI agent write a post too, through Umbraco.AI’s Run AI Agent action and Pro’s Create social draft. Those posts are reviewed in the same way. See Drafts from an AI agent.

Action Needs
Draft with AI UseAi and Write
Rewrite UseAi, and being allowed to change the post, as for saving it (see Permissions)
Suggest alt text UseAi, being allowed to change the post, and access to the image in the media library (the user’s media start nodes)
The AI box on Schedule & writing ManageSettings
Putting a post written with AI on the calendar Approve, or Schedule while approvals are off (see above)

Someone without UseAi doesn’t see the AI buttons. A post the person may not change, or an image outside their media start nodes, is answered as if it didn’t exist.

Each person can make 10 AI requests a minute, across Draft with AI, Rewrite and Suggest alt text together. A request over the limit is refused (ai.too_many, HTTP 429) without calling the provider. The limit is counted per server. Your provider has its own limits too; when it refuses for that reason, the message says so (ai.rate_limited).

appsettings.json
{
"Umbraco": {
"AI": {
"AuditLog": {
"RetentionDays": 7
}
}
}
}

UmbSocial itself stores only the result you keep: the post, its History entry saying AI was used, and its reviewer.

  • AI only returns text. No tools are offered to the model, so it can’t act on the site, and nothing it returns can schedule, publish or review a post.
  • Pages are material, not instructions. A page’s text, and your brief, are passed to the model as quoted material, so text on a page that tries to give the model orders is treated as part of the page.
  • Pages are fetched by UmbSocial, not by the model. Only https pages on the sites you listed, with the same guards as link cards: no private or internal addresses, every redirect checked against the list again.
  • Nothing is half-applied. An answer is used whole, or refused with a message.

Each refusal has a message in the composer that says what to do. The codes are listed in Error Codes.

The composer uses these endpoints, under /umbraco/management/api/v1/umbsocial/pro/ai/. They need UmbSocial to be licensed (licence.pro_required otherwise).

Method and route Needs Body Returns
GET status UseAi { "configured", "startFromLink" }: whether AI is set up, and whether any sites are listed to start from.
POST draft UseAi and Write { "brief" } or { "link" }, and "channelKeys": [] { "key", "version" } of the new draft.
POST rewrite UseAi { "postKey", "channelKey", "text", "instruction" } (instruction optional, up to 500 characters) { "text", "version" }
POST alt-text UseAi { "postKey", "mediaKey" } { "text", "version" }

Rewrite and alt text return the post’s new version, because using AI marks the post: send it with your next save, or the save is refused as out of date (post.changed). Neither saves the text. The AI Settings endpoints are described with the settings.