Microsoft Teams Bot Framework · error code

Teams error 403 MessageWritesBlocked: MessageWritesBlocked - proactive send to a blocking user

Policy / accountHTTP 403Permissions, policy & blocking

Last verified against Microsoft Learn - Status codes from bot conversational APIs

What Teams returns
Thread is blocked from message writes.

What error 403 MessageWritesBlocked means

Your proactive message was refused because the target user has blocked or uninstalled the bot. The proactive-messaging documentation states it directly: "If the agent is blocked or uninstalled, Teams returns a 403 response code with a subCode: MessageWritesBlocked. This response indicates that the message sent by the agent isn't delivered to the user." Unlike most Connector errors, the details arrive nested: the outer body carries "errorCode":209 and a message field that itself contains JSON with "subCode": "MessageWritesBlocked" and "details": "Thread is blocked from message writes." - so naive error parsing that only reads the outer code will miss it.

Microsoft explicitly endorses using this response as telemetry: "The response code is sent on a per-user basis and includes the identity of the user. You can compile the response codes for each user alongside their identity to create a report of all users who have blocked the agent." That matters because Teams fires no event when a user blocks or uninstalls an app in personal scope - no installationUpdate, no conversationUpdate, nothing. A proactive send that comes back 403/MessageWritesBlocked is the only way to learn the relationship ended.

Treat it exactly like ConversationBlockedByUser on the reactive path: a permanent, user-initiated stop signal for that conversation, not a transient fault to retry.

What it looks like

HTTP/1.1 403 Forbidden

{"errorCode":209,"message":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\n}"}

Why it happens

  • The user blocked the bot in their personal chat and your scheduler kept sending.
  • The user uninstalled the app from personal scope; the cached conversation reference still exists on your side.
  • A broadcast job iterates conversation references collected at install time, some of which belong to users who have since left or blocked.
  • An org-wide announcement bot messages users who never interacted with it and some block it immediately.

How to fix Teams error 403 MessageWritesBlocked

  1. 1Parse the nested message JSON and branch on subCode == "MessageWritesBlocked" rather than on the outer errorCode alone.
  2. 2Mark the user/conversation as blocked in your store and remove them from future proactive audiences.
  3. 3Do not retry - delivery is blocked at the thread level until the user re-engages or reinstalls.
  4. 4If large numbers of users show up blocked after a campaign, review the campaign's content and frequency before the tenant admin reviews it for you.
  5. 5Use the per-user 403s to build the blocked-users report Microsoft describes, and reconcile it with your subscription data.

How to stop it recurring

Send proactive messages people want: Microsoft's best-practice list for welcome and notification messages (reason, result, action, opt-out) exists because blocks are the cost of ignoring it. Provide an in-bot mute or unsubscribe so users have a gentler option than the block button. Age out conversation references that have produced no inbound activity for months instead of blasting them, and cap campaign fan-out so a bad send is small. The wider proactive plumbing is covered in proactive messaging constraints.

Official reference: Microsoft Learn - Status codes from bot conversational APIs. See all Teams error codes or the Teams limits and quotas.

Related codes

Error 403 MessageWritesBlocked - quick answers

What does Teams error 403 MessageWritesBlocked mean?

Your proactive message was refused because the target user has blocked or uninstalled the bot. The proactive-messaging documentation states it directly: "If the agent is blocked or uninstalled, Teams returns a 403 response code with a subCode: MessageWritesBlocked .

How do I fix Teams error 403 MessageWritesBlocked?

1. Parse the nested message JSON and branch on subCode == "MessageWritesBlocked" rather than on the outer errorCode alone. 2. Mark the user/conversation as blocked in your store and remove them from future proactive audiences. 3. Do not retry - delivery is blocked at the thread level until the user re-engages or reinstalls. 4. If large numbers of users show up blocked after a campaign, review the campaign's content and frequency before the tenant admin reviews it for you.…

Stop debugging Teams by hand

Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.