Troubleshoot visuals – Applaud Support

Visuals appear when the agent has the required Send Visual tools, clear instructions, and a scenario that benefits from structured presentation.

Celebrations use a different setting on the orchestrator agent and aren't controlled by Send Visual tools.

Before you begin

Make sure you have:

Note: Each agent can have up to 10 tools. If the agent already has 10 tools attached, remove a tool before adding another Send Visual tool.

Before investigating a specific problem:

Confirm the correct collaborator or workflow agent handled the request.
Confirm the required Send Visual tools are attached to that agent.
Confirm the agent instructions describe when each visual should be used.
If you changed a workflow agent, confirm that you published the workflow.
Test the scenario first in the employee portal or the mobile app, where visuals are interactive.

Check the following possible causes.

Likely cause	What to do
No Send Visual tool is attached	Attach the Send Visual tool the scenario needs, then save or publish the agent.
Instructions are too general	Replace instructions such as "use visuals whenever possible" with a specific trigger, such as "When the employee asks for onboarding tasks, send a checklist."
The wrong agent handled the request	Check which collaborator or workflow agent should handle the scenario, and confirm that agent has the required visual tools and instructions.
Workflow changes weren't published	Open the workflow, confirm the Agent step has the required Send Visual tools, then publish the workflow.
The response is better as text	Simple yes/no answers, clarifying questions, and short confirmations may correctly remain as text.

For more information about writing visual instructions, see Guide the assistant to use visuals.

If the assistant returns a visual, but it isn't the type you expected:

Map each employee scenario to one preferred visual in the instructions.
Attach only the Send Visual tools that the scenario needs. Unused visual tools can make selection less predictable.
Put visual guidance near the beginning of the Instructions field.
For workflow agents, keep the instructions focused on the current step and state which visuals should not be used.

Celebration visuals aren't enabled through Send Visual tools. They are controlled by Ovation mode on the orchestrator agent.

To check the setting:

Note: Don't add celebration guidance to collaborator agent instructions. Celebrations are controlled by Ovation mode on the orchestrator.

The employee's channel determines how the visual is presented.

Channel	Expected experience
Employee portal and mobile app	Interactive visuals. Employees can use supported actions, scroll carousels, pan maps, and zoom organization charts and Mermaid diagrams.
Microsoft Teams, Slack, and Outlook email	Static PNG images of the visual. Action buttons aren't clickable, and interactive exploration isn't available.

If employees need to use actions or continue an interactive task, ask them to continue in the employee portal or the mobile app.

For Slack-specific presentation details, see How visuals work in Slack.

If a visual appears but important information is missing:

Confirm the connected-system tool returns the required data.
Shape the tool response so the assistant receives clear, useful fields.
Update the agent instructions to specify what the visual should contain, such as a title, list items, or an Open action when a trusted URL is available.
Confirm the assistant isn't inventing links or claiming that actions are complete.
Instruct the assistant to omit an action or ask for clarification when the required information isn't available.

If the visual depends on live HR data, also see Shape a tool response.

Mermaid diagrams don't use Send Visual tools. They are included in the message when the agent's instructions allow them.

If a Mermaid diagram doesn't appear:

Confirm the instructions describe when to include a process or relationship diagram.
Test the scenario in Applaud web or the mobile app first.
In Microsoft Teams, Slack, and Outlook email, expect a static image rather than an interactive diagram.

After making changes, test a realistic scenario:

Start a conversation in the employee portal or the mobile app.
Ask a question that should produce a visual, such as an onboarding checklist, leave summary, office location, or team chart.
Confirm the expected visual type appears.
Confirm supported actions work in the interactive channel.
Repeat the request in a static channel and confirm the visual appears as an image.
If you use celebrations, trigger a milestone and confirm the celebration appears.

Related to