API-created `html_text` mention is not treated as a mention

Following on from Any way to create User @mentions using API? - the rich-text markup there works, and John_Vu’s note that the API does not auto-add the mentioned user as a collaborator, with addFollowersForTask as the follow-up, is clear and matches what I see. I add the follower, and the note does arrive. My question is about where it arrives.

A mention posted through POST /tasks/{task_gid}/stories with the documented markup never appears in the mentioned user’s Inbox when that Inbox is filtered to “Mentioned”. With the addFollowersForTask call it arrives in the unfiltered Inbox, but as activity on a followed task rather than as a mention. The identical comment typed in the web UI, by the same user on the same workspace, does reach the filtered view.

That makes the documented approach unusable for the case it is most needed for. Filtering the Inbox to “Mentioned” is the normal way to keep a busy Inbox readable, and an agent posting review notes through the API cannot reach a person who does that - the write succeeds, the comment is correct on the task, and nothing surfaces. There is no error and nothing logged.

Tested on 6 November across three markup variants (self-closing as documented, with inner text, and empty paired tags; all stored identically), with and without the follower pre-add, on new and pre-existing tasks, and with the web UI comparison performed signed in as the same user whose token the API calls use. Reading the story back confirms the mention resolved: the anchor comes back annotated data-asana-type="user", data-asana-accessible="true", with the right data-asana-gid and the user’s display name as the anchor text.

The new Notifications API does not distinguish the two cases either. Both an API-created mention and a UI-typed one return story_resource_subtype: comment_added, so a client cannot reproduce the “Mentioned” filter itself as a workaround.

Two questions. Is an API-created mention intended to be excluded from the “Mentioned” filter? And if it is, is there any supported way for an integration to reach a user who filters their Inbox that way?

Happy to send a full reproduction with GIDs and request/response bodies privately.

Hi @Mark_Bain , thank you for the thorough write-up.

My tests suggest the order of the two calls is what matters here. If you first add the user as a task collaborator and then post the story with <a data-asana-gid="{user_gid}"/> in the html_text, the notification lands in the @mentions tab of their Inbox.

From my quick review, the notification condition seems to be that the user is a collaborator at the moment the story is created which matches what I see in testing.

Could you try this order and let me know whether it resolves the use case for you?

Thanks Mikhail — that’s the order my integration already uses, and it doesn’t reach the @mentions tab here, so I think there’s a second variable in play.

What the sync script does on every note, in this order:

  1. GET /tasks/{task_gid}?opt_fields=followers.gid — check whether the user is already a collaborator.
  2. If not: POST /tasks/{task_gid}/addFollowers with {"data":{"followers":["{user_gid}"]}}.
  3. Wait 3 seconds.
  4. POST /tasks/{task_gid}/stories with {"data":{"html_text":"<body><a data-asana-gid=\"{user_gid}\"/> …</body>"}}.

So the user is a collaborator at the moment the story is created in both branches — the one where step 2 ran, and the one where it was skipped because they already were. Neither lands in an Inbox filtered to @mentions. The story itself looks right: Asana stores it with data-asana-type="user" added, and the mention renders as a live link in the web UI. It arrives as ordinary activity on a followed task, with a browser notification, but not under the @mentions filter.

I tested six variants on 6 November, all in the same workspace:

  • collaborator added immediately before the story (the order above) — not in @mentions
  • user already a collaborator, no add call — not in @mentions
  • no collaborator at all — no Inbox entry whatsoever
  • <a data-asana-gid="…"/> self-closing — not in @mentions
  • <a data-asana-gid="…">Name</a> with inner text — not in @mentions
  • the same comment typed in the web UI, signed in as the same service account — does appear under @mentions

That last line is what makes me think the distinction is drawn by the posting route rather than by the markup or the call order: same author, same task, same collaborator state, same rendered comment, different Inbox classification.

Three things that might explain the difference between your test and mine:

  1. Author. Mine are posted by a service account via a PAT, mentioning a different, human user. Were you mentioning the token owner, or a second account?
  2. Auth type. PAT vs OAuth app — does the notification path treat an app-authored story differently?
  3. What was on screen. I’m checking the Inbox with the @mentions filter applied, not the unfiltered Activity list, where these notes do show up.

If it helps, I can post a task GID and story GID from a note that didn’t reach the filter, so you can compare it with one of yours.

Separately, and relevant to anyone else hitting this: the Notifications API returns story_resource_subtype=comment_added for both cases, so an integration can’t tell a direct mention from ordinary activity either. Dominik picked that up in the Notifications API thread.

Hi @Mark_Bain, thank you for such thorough testing and write-up.

I looked into it deeper and can confirm that, currently, a comment mentioning a user is not recognized as a real mention if it is posted less than 30 seconds after that user was added as a collaborator on the task. This appears to be a bug to me, and I’m raising it to review with the owning team.

If it’s feasible for your use case, the current workaround is to post the comment story 30+ seconds after the user was added as a task collaborator.

Thanks again for the careful review, and for your patience while I looked into this.

Many thanks for digging into this for me. I’ve updated my iintegration to wait 35s between adding a collaborator and any mention. Tested and working!
All the best