Microsoft Teams Bot Framework · error code

Teams error 403 ConversationBlockedByUser: ConversationBlockedByUser - user blocked the bot

Policy / accountHTTP 403Permissions, policy & blocking

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

What Teams returns
User blocked the conversation with the agent.

What error 403 ConversationBlockedByUser means

The person on the other end blocked your bot, and the Connector now rejects every write into that conversation. The status table documents the code as ConversationBlockedByUser with the message "User blocked the conversation with the agent." (earlier doc versions say "bot") and explains: "User blocked the agent in personal chat or a channel through moderation settings." Retry is documented as No, and the developer action is specific: "Delete the conversation from cache. Stop attempting to post to conversations until interaction with agent is explicitly initiated by a user in the conversation, indicating that the agent is no longer blocked."

Teams gives users a block control on personal bot chats, and channel moderation settings can shut bots out of a channel's replies. Either way there is no webhook, no conversationUpdate, and no Graph event to tell you it happened - the 403 on your next send is the only notification you get. That makes this code (together with its proactive-messaging sibling MessageWritesBlocked) the de facto block-detection mechanism: production notification bots treat the first 403 of this kind as an unsubscribe event.

Nothing about your app registration, manifest, or admin policy is implicated. The same bot keeps working for every other user; only the blocking user's conversation is closed to you.

What it looks like

{
  "error": {
    "code": "ConversationBlockedByUser",
    "message": "User blocked the conversation with the agent."
  }
}

Why it happens

  • The user blocked the bot from the chat's context menu in Teams (personal scope).
  • A channel's moderation settings were changed to prevent bots from posting replies.
  • The user blocked the bot months ago and your notification job is still replaying cached conversation references.
  • A previously blocked user's conversation ID was re-added to your send list by a data backfill.

How to fix Teams error 403 ConversationBlockedByUser

  1. 1Match the error code string exactly: ConversationBlockedByUser means a user action, not an admin policy - do not escalate to IT.
  2. 2Follow the documented action: delete or flag the cached conversation reference so scheduled sends skip it.
  3. 3Record the block in your user store (blocked_at timestamp) for reporting and re-engagement logic.
  4. 4Do not attempt workarounds through other conversations - messaging a user who blocked you through a group thread reads as harassment and invites an admin block.
  5. 5Resume only when the user messages the bot again; that inbound activity is the documented all-clear.

How to stop it recurring

Users block bots that message too often or say too little. Make every proactive message answer three questions - why am I getting this, what changed, what can I do - and give a visible opt-out that does not require blocking. Watch your block rate as a product metric: a spike after a new notification type ships is user feedback. Frequency guidance and the message-design checklist live in Microsoft's proactive messaging best practices, summarized 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 ConversationBlockedByUser - quick answers

What does Teams error 403 ConversationBlockedByUser mean?

The person on the other end blocked your bot, and the Connector now rejects every write into that conversation.

How do I fix Teams error 403 ConversationBlockedByUser?

1. Match the error code string exactly: ConversationBlockedByUser means a user action, not an admin policy - do not escalate to IT. 2. Follow the documented action: delete or flag the cached conversation reference so scheduled sends skip it. 3. Record the block in your user store (blocked_at timestamp) for reporting and re-engagement logic. 4. Do not attempt workarounds through other conversations - messaging a user who blocked you through a group thread reads as harassment…

Stop debugging Teams by hand

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