Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Every chat app says what it is doing. Read its state first.

The state is in the agent’s TUI (Bots tab, ⇄ Connect, Chat apps) and in state of GET /api/v1/agent/bots/{id}/channels/{cid}. The last connection error is in last_error (code, message, at). When the chat app knows why it is in its state, state_reason says it (one of the reasons below).

In the Hub, open Bots, select the Bot and open Chat apps. State shows each chat app’s state, and Needs you names what to fix. Choose Manage to open its setup. To replace a token, use Replace… under Bot token, or use the Replace the token setup step if sign-in failed. Under Settings, use the switch named for the chat app to turn it off or on. Pause all and Resume all pause or resume the Bot’s chat apps.

StateWhat it meansWhat to do
connectingThe chat app is opening its connection to the platform.Wait a few seconds.
connectedMessages flow both ways.Nothing.
awaiting_ownerNobody is paired as owner yet. With dm_policy: owner, nobody can talk to the Bot in a direct message. Group conversations follow group_mode.Send the owner code to the bot in a direct message. Make a new one if it expired.
degradedThe chat app has trouble connecting, receiving or saving, or has stopped running. Check state_reason and last_error.Usually heals by itself: the chat app keeps retrying. If it stays, see the reasons below. If it stays with no reason, wait a minute. If it is still degraded with no reason, restart the agent. If it happens again, delete the chat app and connect it again.
standbyAnother chat app already runs this platform bot. This one waits.Turn off or delete the other chat app, or delete this one.
conflictAnother program reads the same bot, or a webhook was set on it.Stop the other program. For a webhook: Turn the chat app off ("enabled": false), wait until its state is paused, then turn it on with "enabled": true, "delete_webhook": true in the same update. delete_webhook alone, on a chat app that is on, does nothing.
auth_failedThe platform refused the token, or the token now belongs to another bot. Nothing retries.Replace the token (PUT …/channels/{cid}/credentials, or Replace keys in the TUI).
pausedThe chat app is turned off, or chat apps are paused for the whole Bot. With the reason not_running, it is on but nothing runs it: see Reasons.Turn it on (enabled: true, or Resume on the chat app in the TUI), or set channels_paused: false on the Bot.
realm_unservedThe agent cannot confirm that its current login can serve this Bot. This can be temporary.Wait a moment and read the state again. If it stays, sign the agent in again with a login that covers the Bot’s realm. See The Bot is gone from the list.
stoppingA change is waiting for the connection to close.Wait. If it stays with the reason stop_stuck, restart the agent.
stoppedThe Bot is being deleted.Nothing.

state_reason or last_error.code can carry one of these reasons:

ReasonMeaningWhat to do
unauthorizedThe platform refused the token.Copy the token again, whole, and replace it.
binding_changedThe token now belongs to another bot or another Slack workspace.Replace it with a token of the original bot, or delete the chat app and connect the new bot as a new one.
missing_scopeA Slack token lacks a scope. For the App-level token: it needs connections:write.Add the scope, reinstall the Slack app, replace the token.
missing_intentDiscord refused even the basic gateway intents (auth_failed). This should not happen.Check the bot in the Developer Portal, then replace the token.
message_content_missingDiscord did not grant Message Content. The chat app connected without it: in servers the Bot reads only messages that @mention it.Turn on Message Content Intent in the Developer Portal, then turn the chat app off and on again, pause and resume the Bot’s chat apps, or enter its token again. Waiting is not enough. The next connection asks for the intent; if it is still off, the chat app connects without it again. Until Discord grants the intent, mention_only cannot be set to false.
mismatched_appThe two Slack tokens come from different apps.Take both tokens from the same app.
app_unverifiedSlack did not say which app the Bot token belongs to.Add users:read, reinstall the Slack app, and replace the Bot token.
unreachableThe platform could not be reached.Wait. The chat app retries.
rate_limitedThe platform slowed the chat app down, or a configured connection limit was reached.Wait, and read last_error to identify the limit. Lower your own traffic if it keeps happening.
identity_in_useAnother chat app runs this bot account (standby).Run it from one place only.
other_pollerAnother program reads this Telegram bot (conflict).Stop the other program.
webhook_setA webhook was set on this Telegram bot (conflict).Turn the chat app off ("enabled": false), wait until its state is paused, then turn it on with "enabled": true, "delete_webhook": true in the same update. delete_webhook alone, on a chat app that is on, does nothing.
storage_failingThe agent cannot save the chat app’s data.Check free disk space on the computer that runs the agent.
credentials_missingThe saved token is gone.Replace the saved credentials first, supplying both tokens for Slack. If replacement is refused because the credentials storage is missing, delete the chat app and connect it again.
not_runningThe chat app is on, but nothing runs it on this agent right now (paused).Wait a few seconds and read the chat app again. If the Bot is suspended, resume it (see The Bot is gone from the list). If it still shows, restart the agent.
channel_disabledThe chat app is turned off (paused).Turn it on ("enabled": true, or Resume on the chat app in the TUI).
bot_pausedChat apps are paused for the whole Bot (paused).Set channels_paused: false on the Bot.
lock_unavailableThe agent process on this computer cannot lock this chat app’s bot account, so the chat app does not run (degraded). Either file locks do not work where the agent keeps its data, or a Discord chat app is missing its application or bot id.Restart the agent. If it still shows on a Discord chat app, delete the chat app and connect it again.
lock_lostThe chat app’s lock was taken away while it ran, so another agent process may run this bot now. The chat app stopped (degraded) and does not start again by itself.Make sure only one agent process runs this bot. Then turn the chat app off and on again ("enabled": false, then "enabled": true), or restart the agent.
stop_stuckThe connection did not close in time (stopping).Restart the agent.
gateway_refusedDiscord refused the gateway connection because of its shard, sharding requirement, API version or intents.Check the bot’s settings. Use the bot in fewer servers only when Discord requires sharding. If the settings do not explain the refusal, report the error.
missing_accessDiscord refused a channel.Restore the bot’s permission to read and send in that Discord channel. If the chat is muted, open the Bot’s Chat apps, choose Manage, open Chats, and choose Approve for it (for a group, then confirm Approve group). Ask the sender to send the message again.
guild_unavailableA Discord server is briefly unavailable.Wait.
payload_too_largeAn outgoing message, an incoming event or a platform response went over a size limit.For an outgoing message, try a lower part_chars on this chat app. For an incoming event or response, read last_error for details; part_chars does not change incoming sizes.
chat_migratedThe Telegram group became a supergroup with a new chat id.Read the new id in last_error.message, then bind and approve the new chat. The approval does not carry over.
CodeStatusWhat to do
channel_credentials_invalid422The platform refused the token, or could not be reached to check it. reason says why (table above).
channel_exists409This Bot already has this platform bot. Use the existing chat app.
channel_identity_in_use409Another chat app, of this Bot or another one, already runs this platform bot. Delete or turn off the other one first, or use another bot.
channel_conflict409Read details.reason. For webhook_set (the Telegram bot has a webhook), send the create, or the update that turns the chat app on, again with delete_webhook: true. For bot_paused, first set channels_paused: false on the Bot, then send the request again with delete_webhook: true.
channel_identity_changed409The new token belongs to another bot. Use a token of the same bot, or connect the other bot as a new chat app.
channels_exhausted429The Bot has max_channels chat apps, or the chat app has max_principals people. A new pairing code is refused too (channels_exhausted) once the chat app already has max_principals people. Delete one first, or raise the limit.
owner_needs_pairing409The first owner must pair through the platform with an owner code. Adding an owner by user id works only after that.
acknowledgement_required422Approving a group needs "acknowledge_group_readers": true.
setting_invalid422A setting has a bad value, or does not exist on this platform (not_available). details.field names it.
setting_conflict422Two settings do not fit together. For example, approval cards can go to a group only when decide_in_groups is on (gate_push_to_group).
idempotency_key_reused422The same Idempotency-Key came with another body. Use a new key.
idempotency_replay_gone410The chat app this Idempotency-Key created was deleted since. Send the create with a new key.
idempotency_keys_exhausted429Too many keyed creates are kept. Try later, or send the create without a key.

Any chat app request can also answer one of these:

CodeStatusWhat to do
bad_request400The request is malformed. message says what to fix.
invalid_realm400The realm in X-Hoody-Realm or ?realm= is not global or a realm id. Fix it.
realm_scope_unsupported400Chat app requests take a realm only. Drop the other scope headers, or use the realm this agent is pinned to.
forbidden403Hoody Kit programs are reached through their URLs only. Call the agent through its URL.
not_found404Check the Bot id, the chat app id and the realm. A Bot that is gone from the list also answers 404.
realm_blocked409The agent’s selected realm is not usable. Select a valid realm, or name one with X-Hoody-Realm.
bot_owned_elsewhere409Another agent process on this computer serves this Bot, so nothing of it was read or changed. Wait the seconds in Retry-After, then try again, or use the agent that serves the Bot. GET /api/v1/agent/bots lists such a Bot with owned_elsewhere: true. If details.reason is lock_unavailable, the agent cannot lock the Bot’s files on its storage: if it keeps failing, keep the agent’s data on storage that supports file locks.
payload_too_large413The request body is too big. Send less.
rate_limited429Too many requests. Wait the seconds in Retry-After, then try again.
internal_error500Something failed inside the agent. Try again. If it keeps failing, check the agent’s logs.
restriction_unknown503The agent could not read which realms your login covers. Try again in a moment. If it says to sign in again, do that.
service_unavailable503The agent is busy or starting, or the Bot’s chat apps are being handed over or their store is not available right now. Try again, after the seconds in Retry-After when it is set. For a change, read the chat app first: it may already be applied. For a delete, see Delete a chat app.

A Bot is suspended when the account the agent is signed in with signs out, changes, or no longer covers the Bot’s realm. A suspended Bot stops working, its chat apps stop, it is left out of the list, and its requests answer 404 not_found.

Nothing is deleted. The Bot comes back on its own when the agent is signed in again with the same account, and that account covers the Bot’s realm. To keep its Bots under the account signed in now, resume them. In the Hub, open Bots and choose Resume on the notice that says one or more Bots are paused after a sign-in change. In the TUI’s Bots tab, choose [ ⟳ Resume N ] (or press R). Through the API, call POST /api/v1/agent/bots/resume (no body). The call resumes the suspended Bots of the agent’s current realm, or of every realm the account covers with ?realm=all, and its answer lists them in resumed. A 503 means a Bot could not be resumed right now and stays suspended: try again in a moment.

Terminal window
hoody agent bots resume -c $COMPUTER_ID --realm all

--realm all resumes the suspended Bots of every realm the account covers. Leave it out to resume those of the agent’s current realm. --realm is an option of hoody itself, so hoody agent bots resume --help does not list it.

If your computer’s proxy permissions protect the agent, add the credential its group requires to the cURL example; see proxy permissions.

An agent pinned to one realm accepts only that realm, and answers realm_scope_unsupported to all. There, leave out --realm all, agentRealm: 'all' or ?realm=all.

The chat app answers some messages itself:

MessageMeaning
I only talk with people the owner allows. Ask the owner for a pairing code.The chat app’s access settings do not allow your direct message. If you are not paired, ask the owner for a code. If you are, ask the owner to check your chat right and dm_policy.
To pair, send only the pairing code, typed exactly as shown…The code was mixed with other text or was not typed exactly as shown. Send only the code using plain digits and letters; use 0 and 1, never O, I or L.
That code is not valid or has expired.Ask for a new code. By default, 5 wrong codes refuse you for 60 minutes; pairing_user_burn_tries and pairing_user_burn_minutes change those limits.
You are already paired. That code is meant for someone else, so it was not used.Nothing to do. Pass the code on to the person it was made for.
Send your pairing code in a direct message to me, not in a group.Codes work in direct messages only.
Slow down: too many messages. Try again in a moment.A message limit was reached.
Message too long: at most … bytes.Shorten it, or send it in parts.
I can only read text messages for now. Please type your message.An allowed sender sent media without text. In a group, the message must address the Bot. Type the message instead; the notice is limited to once an hour.
I held back a reply because it looked like it contained a secret…Read the answer in the session.
I do not take part in group chats.Groups are off (group_mode: off).
This group is not on my list. Ask the owner to add it.The group must be added to allowed_chats.
I asked the owner to approve this group. Until then I do not read it.The owner must approve the group.
This group is waiting for the owner’s approval.Same: approval is pending.
In groups I can only read messages that mention me.Mention the bot. Or turn on Discord’s Message Content Intent, then turn the chat app off and on again (or enter its token again).
You cannot run commands here.The command is not allowed for you in this chat: you lack the control right, or the command does not work here (bind works only in groups).
My answer to your message was lost. Send it again.Delivery failed. Send the message again.
Something went wrong before I could answer. Send your message again.The Bot’s turn failed. Send it again.
I finished without an answer.The Bot ended its turn without text. Ask again or check the session.
(the rest of this answer is in the session)The answer was longer than max_parts parts.

Messages people sent to the bot while the chat app was down may be lost. The chat app’s last_gap says when that last happened: from and to are the start and end of the window. With possible: true, messages may have been lost, not certainly. No last_gap means no gap was recorded; it does not guarantee that no messages were missed. The TUI shows it in the chat app’s details as “may have missed messages from … to …” when possible is true, and “missed messages from … to …” otherwise. Ask people who wrote in that window to send their message again.

  1. Check the state and follow the advice for it under States. awaiting_owner requires owner pairing for direct messages, but permitted group conversations can still work.
  2. Check that the chat app admits you. When dm_policy (DMs) or group_mode (groups) is open, unpaired users can chat as guests, subject to chat restrictions and blocklists. Paired users still need the chat right. Otherwise, your user must be in the chat app’s people (principals) with the chat right. dm_policy: owner admits only the owner in direct messages.
  3. In a group: check that group_mode is not off, the group is not muted, and the group is approved unless group_mode is open. If allowed_chats is not empty, check that it includes the group; allowlist requires it. If mention_only is true, address the bot with a mention or a reply. On Telegram, if privacy mode stops the bot reading the messages you need, turn privacy off at @BotFather, then remove the bot from the group and add it again: Telegram applies the change only when the bot joins. Making the bot an admin of the group works too.
  4. Send text. A file, image or voice message with no text does not reach the Bot.
  5. Check that the Bot itself answers: send it a message in the TUI.

Most problems show their name in the state. The fix is usually one step away.