# API-created \`html\_text\` mention is not treated as a mention

**URL:** <https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147>\
**Category:** API & Developers\
**Created:** [9 November 2026 12:39 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147 "2026-11-09T12:39:32Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![Mark\_Bain](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/mark_bain/32/79094_2.png) [@Mark\_Bain](https://forum.asana.com/u/Mark_Bain)\
**Post date:** [9 November 2026 12:39 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147/1 "2026-11-09T12:39:32Z")

</div>

Following on from [Any way to create User @mentions using API?](https://forum.asana.com/t/any-way-to-create-user-mentions-using-api/3326) - 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.

---

<div class="post-metadata">

**Author:** ![Mikhail\_Melikhov](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/mikhail_melikhov/32/288769_2.png) [@Mikhail\_Melikhov](https://forum.asana.com/u/Mikhail_Melikhov)\
**Post date:** [13 November 2026 14:22 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147/2 "2026-11-13T14:22:57Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![Mark\_Bain](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/mark_bain/32/79094_2.png) [@Mark\_Bain](https://forum.asana.com/u/Mark_Bain)\
**Post date:** [13 November 2026 14:57 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147/3 "2026-11-13T14:57:14Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Mikhail\_Melikhov](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/mikhail_melikhov/32/288769_2.png) [@Mikhail\_Melikhov](https://forum.asana.com/u/Mikhail_Melikhov)\
**Post date:** [17 November 2026 09:11 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147/4 "2026-11-17T09:11:38Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Mark\_Bain](https://sea2.discourse-cdn.com/asana/user_avatar/forum.asana.com/mark_bain/32/79094_2.png) [@Mark\_Bain](https://forum.asana.com/u/Mark_Bain)\
**Post date:** [17 November 2026 10:42 UTC](https://forum.asana.com/t/api-created-html-text-mention-is-not-treated-as-a-mention/1161147/5 "2026-11-17T10:42:17Z")

</div>

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
