Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Nesta página, descrevemos as práticas recomendadas para escrever mensagens de erro acionáveis que informem
ao usuário como corrigir o problema para que ele possa concluir a meta.
Quando um usuário interage com um app do Google Chat, encontrar mensagens de erro pode ser uma experiência frustrante se o erro não for acionável.
Por exemplo, a mensagem de erro An error occurred não é útil porque não explica o que deu errado, como o usuário pode corrigir o problema ou como ele pode receber ajuda. Esta página descreve como estruturar mensagens de erro para que sejam úteis aos usuários, mostrando exemplos de ações e inações.
Estrutura da mensagem de erro
Uma mensagem de erro útil tem a seguinte estrutura:
O que deu errado. Explicar por que o app de chat não pode
concluir uma solicitação ajuda o usuário a resolver o problema. Explicar por que um erro
ocorreu gera confiança.
Como o usuário pode avançar em direção à meta. Não basta apenas dizer o que deu errado. Diga aos usuários como superar o erro e concluir a meta.
Como receber ajuda. Se o usuário ainda estiver com dificuldades, diga como ele pode receber mais ajuda. Pode ser um comando /help ou um link para a documentação do
app do Chat.
Exemplo de mensagem de erro: formato de data incorreto
Neste exemplo, o usuário inseriu uma data em um formato que o app Chat não esperava. Eles escreveram
November 19, 2021, mas o app Chat espera
2021-11-19.
Confira uma versão prática e outra não prática da mensagem de erro que o
app Chat responde:
Erro acionável
Um usuário pede ao app Chat para agendar uma reunião com outra pessoa. O app Chat responde com uma mensagem de erro útil e
prática:
I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.
Essa mensagem de erro é útil pelos seguintes motivos:
Diz o que deu errado. O app Chat não reconhece o formato da data.
Explica como corrigir o erro informando ao usuário o formato de data esperado
e dá um exemplo de data que ajuda as pessoas a entenderem o que escrever.
Oferece mais ajuda com um comando de barra /help. Se os usuários ainda estiverem com dificuldades,
eles saberão como saber mais.
Erro sem ação
Um usuário pede ao app Chat para agendar uma reunião com outra pessoa. O app Chat responde com uma mensagem de erro inútil e sem ação:
Enter the correct date format.
Essa mensagem de erro não pode ser corrigida pelos seguintes motivos:
Não informa se a reunião foi agendada. O usuário pode hesitar em remarcar a reunião ou presumir que ela foi agendada.
Não informa ao usuário como formatar a data. Em vez de presumir que os usuários sabem como formatar a data, é melhor dizer que o formato esperado é yyyy-mm-dd.
Não oferece mais ajuda. Quando os usuários ficam presos e não sabem como continuar,
eles podem parar de enviar mensagens para o app Chat.
Faça um teste
Agora que você sabe como escrever erros acionáveis, identifique no cenário a seguir qual deles é acionável:
Um app do Chat cria eventos da agenda quando os usuários enviam mensagens
para o app do Chat com a palavra-chave schedule. Para criar um evento da agenda, o app Chat precisa da autenticação do usuário. Se um usuário não tiver sido autenticado, o
app Chat vai responder com uma mensagem de erro.
Qual mensagem de erro é útil?
Antes de agendar a reunião, faça login digitando
/signin. Para saber mais, digite /help.
Essa mensagem de erro é útil porque diz o seguinte:
O que deu errado. O app Chat requer autenticação.
Como proceder. Digite /signin para autenticar.
Como receber ajuda. Se o usuário quiser mais informações, ele pode digitar
/help.
Você precisa fazer a autenticação.
Essa mensagem de erro não pode ser corrigida porque não diz como fazer a autenticação.
Faça login.
Essa mensagem de erro não é útil porque não informa como fazer login e implica que o usuário está desconectado em vez de dizer isso claramente, o que é confuso.
Não é possível programar uma reunião.
Essa mensagem de erro não é útil porque não informa ao usuário
por que a reunião não pode ser agendada nem como ele pode proceder. Nenhuma ajuda
é fornecida.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-29 UTC."],[[["\u003cp\u003eGoogle Chat app error messages should be actionable, guiding users on how to resolve issues and proceed.\u003c/p\u003e\n"],["\u003cp\u003eActionable error messages clearly explain the problem, provide steps for fixing it, and offer additional help resources.\u003c/p\u003e\n"],["\u003cp\u003eInactionable error messages are vague, lack guidance, and can lead to user frustration and abandonment.\u003c/p\u003e\n"],["\u003cp\u003eUse the actionable error message structure: state the problem, guide the user on fixing it, and offer further help (e.g., \u003ccode\u003e/help\u003c/code\u003e command).\u003c/p\u003e\n"],["\u003cp\u003eWhen writing error messages, assume users need clear instructions and avoid ambiguity.\u003c/p\u003e\n"]]],["Actionable error messages in Google Chat apps should specify what went wrong, how to fix it, and how to get further assistance. For example, an actionable message for an incorrect date format would state that the format is unrecognized, specify the required format (yyyy-mm-dd), and provide a /help command. In contrast, inactionable errors are vague, omit how to correct the issue, and offer no additional support. A sign-in error should also include clear instructions, and help commands.\n"],null,["# Write actionable error messages\n\nThis page describes best practices to write actionable error messages that tell\nthe user how to fix the issue so that they can complete their goal.\n\nWhen a user is interacting with a Google Chat app, encountering\nerror messages can be a frustrating experience when the error isn't actionable.\nFor example, the error message, `An error occurred`, isn't useful because the\nmessage doesn't explain what went wrong, how the user can fix the issue, or how\nthe user can get help. This page describes how to structure error messages so\nthat they're useful to users by showing actionable and inactionable examples.\n\nError message structure\n-----------------------\n\nAn actionable error message has the following structure:\n\n- **What went wrong.** Saying why the Chat app can't complete a request helps the user resolve the issue. Explaining why an error occurred builds trust.\n- **How the user can proceed toward their goal.** It's never enough to just say what went wrong. Tell users how they can move past the error and complete their goal.\n- **How to get help.** If the user is still stuck, tell them how they can get more help. This could be a `/help` command or a link to documentation for your Chat app.\n\nExample error message: incorrect date format\n--------------------------------------------\n\nIn this example, the user entered a date in a format that\nthe Chat app didn't expect. They wrote\n`November 19, 2021`, but the Chat app expects\n`2021-11-19`.\n\nHere's an actionable and an inactionable version of the error message that the\nChat app responds with:\n\n#### Actionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with a good,\nactionable error message:\n\n``I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.``\n\nThis error message is actionable for the following reasons:\n\n- Says what went wrong. The Chat app doesn't recognize the date format.\n- Explains how to fix the error by telling the user the expected date format and gives an example date that helps people understand what to write.\n- Offers more help with a `/help` slash command. If users are still stuck, they know how to learn more.\n\n#### Inactionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with an\nunhelpful, inactionable error message:\n\n`Enter the correct date format.`\n\nThis error message is inactionable for the following reasons:\n\n- Doesn't say whether it scheduled the meeting. The user might be hesitant to reschedule the meeting, or they might assume that the meeting was scheduled.\n- Doesn't tell the user how to format the date. Instead of assuming that users know how to format the date, it should say that it's expecting the date format `yyyy-mm-dd`.\n- Doesn't offer more help. When users are stuck and don't know how to proceed, they might stop messaging the Chat app.\n\nTry it out\n----------\n\nNow that you know how to write actionable errors, can you identify in the\nfollowing scenario which of these errors is actionable:\n\nA Chat app creates calendar events when users message\nthe Chat app with the keyword `schedule`. To\ncreate a calendar event, the Chat app requires user\nauthentication. If a user hasn't been authenticated, then the\nChat app responds with an error message. \nWhich error message is actionable? \nBefore I can schedule the meeting, you must sign in by typing `/signin`. To learn more, type `/help`. \nThis error message is actionable because it says the following:\n\n- What went wrong. The Chat app requires authentication.\n- How to proceed. Type `/signin` to authenticate.\n- How to get help. If the user wants more information, they can type `/help`. \nYou must authenticate. \nThis error message is inactionable because it doesn't say how to authenticate. \nSign in. \nThis error message is inactionable because it doesn't say how to sign in, and it implies that the user is signed out instead of clearly saying so, which is confusing. \nCan't schedule meeting. \nThis error message is inactionable because it doesn't tell the user why the meeting can't be scheduled or how the user can proceed. No help is provided."]]
