Discord error 220001: Forum webhooks need thread_name or thread_id
Last verified against Discord Developer Docs - Opcodes and status codes
Webhooks posted to forum channels must have a thread_name or thread_idWhat error 220001 means
You executed a webhook that belongs to a forum (or media) channel without telling Discord where the message should go. Forum channels hold posts, not messages, so a webhook there must either create a new post or write into an existing one.
To create a new post, include thread_name in the JSON body; Discord creates the post with your message as its opening message. To write into an existing post, pass thread_id as a query parameter on the execute URL, for example ?thread_id=123. Sending neither returns 220001.
This often breaks integrations that worked when the webhook pointed at a text channel, after an admin converted the destination to a forum or created the webhook in a forum by mistake.
What it looks like
{
"message": "Webhooks posted to forum channels must have a thread_name or thread_id",
"code": 220001
}Why it happens
- Webhook created in a forum channel and executed like a text-channel webhook
- thread_name or thread_id omitted by the integration
- thread_id placed in the JSON body instead of the URL query string
- Destination channel converted to a forum after the integration was set up
How to fix Discord error 220001
- 1Decide whether each message should start a new post or go into an existing one
- 2For new posts, add thread_name to the JSON body
- 3For existing posts, append ?thread_id={thread.id} to the webhook URL
- 4Retry and check the message appears in the forum
- 5Check the webhook's channel type with GET on the webhook and its channel_id before wiring up an integration
How to stop it recurring
When building integrations, check the webhook's channel type once at setup and store whether it needs a thread name. Required forum tags (40067) apply to webhook posts too. More webhook failure patterns are in the webhook debugging guide.
Official reference: Discord Developer Docs - Opcodes and status codes. See all Discord error codes or the Discord limits and quotas.
Related codes
- 220002: Forum webhooks cannot have both thread_name and thread_idWebhooks posted to forum channels cannot have both a thread_name and thread_id
- 220003: Webhooks can only create threads in forum channelsWebhooks can only create threads in forum channels
- 40058: Cannot send a message in a forum channelCannot send a message in a forum channel
- 40067: A tag is required to create a forum postA tag is required to create a forum post in this channel
Error 220001 - quick answers
What does Discord error 220001 mean?
You executed a webhook that belongs to a forum (or media) channel without telling Discord where the message should go. Forum channels hold posts, not messages, so a webhook there must either create a new post or write into an existing one. To create a new post, include thread_name in the JSON body; Discord creates the post with your message as its opening message.
How do I fix Discord error 220001?
1. Decide whether each message should start a new post or go into an existing one 2. For new posts, add thread_name to the JSON body 3. For existing posts, append ?thread_id={thread.id} to the webhook URL 4. Retry and check the message appears in the forum 5. Check the webhook's channel type with GET on the webhook and its channel_id before wiring up an integration
Should I retry after error 220001?
No. Retrying the same request produces the same error; the condition has to be fixed first. Treat it as a permanent failure for that message and surface it, rather than looping.
Stop debugging Discord by hand
Connect the channel through Conferbot: tokens, webhooks and retries are handled, failures show as readable status.