How an email conversation flows
1
A ticket arrives
A customer emails the mailbox you have ticked for the agent, and Freshdesk creates a ticket.
2
The agent reads the thread
It works from the message history, its FAQs, and its knowledge groups. Where it needs live data — an order status, an account balance — it runs one of its in-conversation actions.
3
The agent replies in the thread
The reply goes out as a normal Freshdesk reply, so the customer sees one continuous email conversation rather than a separate channel. Each reply carries a short AI disclaimer unless you have switched it off, followed by a small Powered by SquawkVoice line.
4
The customer replies, or does not
Each new customer reply is another turn: the agent reads the thread again and answers again.
5
The conversation ends
The agent resolves the conversation, escalates it to a human, or — if the customer stops replying — it ends on inactivity.
Before you start
Make sure you have:- An agent built and saved in Build → AI Agents
- A Freshdesk account containing the mailbox you want the agent to work
- The Freshdesk connection set up in Manage → Connected Apps (see Connected Apps)
Both halves are required. An agent only starts working email once Freshdesk is connected and a mailbox is ticked on the agent. Until then nothing is picked up.
Draft and published versions. An agent that has never been published answers email with your latest saved edits. Once it has been published, it answers with the published version, so a later change to its Guidelines, FAQs, knowledge groups, actions, Closing message, Handoff Message, outcome options, Inactivity Timeout or AI Disclaimer reaches live email only after your next Publish. Ticking or un-ticking a mailbox applies at once. See Publishing Your Agent and What Waits for Publish.
1. Connect Freshdesk
If Freshdesk is not connected yet:- Open Studio → Manage → Connected Apps.
- Find the Freshdesk card and click Connect.
- Enter your Domain and API Key.
- Click Connect. The credentials are checked with Freshdesk first.
- In the Describe this connection window, enter a short description of what the connection is for — it tells the AI agent when to use the connection — and click Save Connection. The window can’t be closed until you’ve entered a description.
Automation rules in your Freshdesk account
So that the agent sees new tickets — and so that it can follow a conversation a human has taken over — SquawkVoice maintains three automation rules inside your own Freshdesk account. They are created the first time a mailbox is ticked on the connection (see Choose a mailbox), not when you connect Freshdesk, and removed again when the last mailbox on the connection is un-ticked. They are placed at the top of their automation lists and named to carry a[DO NOT DELETE, DO NOT REORDER] marker, so reordering rules in Freshdesk cannot stop the agent picking tickets up.
The third rule is what makes an escalated conversation keep updating: it fires when an agent replies and when the ticket is resolved or closed, which is how SquawkVoice records the human’s replies on the transcript and knows when the conversation has finished. A connected mailbox therefore generates more traffic to SquawkVoice during a handoff than it used to.
2. Choose a mailbox
Email is configured on the agent, in the Email Configuration card in the agent’s Modality section — described there as “Triage and reply to email with your AI agent.”- Open your agent in Studio → Build → AI Agents.
- Go to Email Configuration → Inbox.
- Under Freshdesk mailboxes, tick the mailbox this agent should work. Ticking connects it straight away, with a confirmation such as Connected support@acme.com, and un-ticking disconnects it the same way. This applies at once, even on a published agent, and doesn’t wait for Publish. A Manage in Connected Apps link beside the heading takes you to your connections.
No Freshdesk accounts connected Go to Manage → Connected Apps → Freshdesk to connect an account, then return here.That is the cue to complete step 1 first. A connected Freshdesk account that has no mailboxes shows No support mailboxes found. instead. You can also open an agent’s Email Configuration from its mailbox chip on Build → AI Agents, without opening the agent. It’s the same panel, so ticking a mailbox or changing a setting there has the same effect as it does on the agent’s own page. Or ask the Co-pilot. Ask the Squawk Co-pilot to set up email for an agent and it lists the mailboxes that agent can use, labelled as they are on the Inbox tab, and subscribes or unsubscribes the one you pick. Choosing a mailbox in that list sends your choice to the Co-pilot rather than saving it directly. If no Freshdesk account is connected, the list shows a Connect Freshdesk button that takes you to Connected Apps; if you finish within about five minutes, the Co-pilot picks the conversation back up with the mailboxes you can choose. To unsubscribe a mailbox that has open conversations, the Co-pilot asks first on a card whose button is Resolve & Unsubscribe, which works as described under Unsubscribing a mailbox. It can also change the Inactivity Timeout (3 to 7 whole days) and the AI Disclaimer on the Config tab: on or off, your own text of up to 2,000 characters, or blank for the default. On an agent you’ve published, a changed Inactivity Timeout or AI Disclaimer reaches live emails at your next Publish, while subscribing or unsubscribing a mailbox applies at once. The Co-pilot can’t publish for you.
One inbox, one agent
An inbox can be worked by exactly one AI agent. The rule is matched on the address, so the same mailbox reached through two different Freshdesk connections still counts once. A mailbox that can’t be ticked is shown locked in the list, with a badge that says why:Unsubscribing a mailbox
Un-ticking a mailbox that still has open conversations asks what should happen to them first, and tells you how many are already with a person — for example “support@acme.com has 4 open email sessions, 2 already with a live agent.” Resolve & Unsubscribe is the only way out. Escalating conversations on the way out used to be offered and has been removed: escalating leaves a conversation open, which is the opposite of what unsubscribing needs to do, and there is nothing to escalate to for conversations already with a human.3. What the agent uses to answer
There is no separate knowledge to build for email. An email agent answers from the same configuration as the same agent on voice and chat:
See Knowledge Base for adding FAQs, documents and web content to a knowledge group, and linking that group to an agent.
Pre- and post-conversation actions
Pre-conversation and post-conversation actions also run on email, but only when Email is ticked under Execute on channels on the action. New actions default to Voice only, so an action you built for calls is skipped on email until you add Email to it.- Pre-conversation actions run once per ticket, on the customer’s first email, before the agent writes its first reply.
- Post-conversation actions run once per conversation, when it ends: when the agent resolves it, at the moment the agent escalates it, when it is abandoned on inactivity, and when you escalate a thread, or resolve one that hasn’t been escalated, from email history.
Greeting and Sign-off
Greeting & Sign-off is organized as Voice, Chat and Email tabs. Your existing voice and chat wording is unchanged — it now simply lives under its own tab. The Email tab holds a single field:“Send this message when the email conversation is resolved or closed.”Pre-filled with “Thank you for contacting us. Have a great day!” It cannot be saved blank, and it accepts variables, so you can sign off with the customer’s name or a reference number.
Multiple languages
Every language configured on the agent gets its own Message to Send in Language box, below the English default — for both the email closing message and the handoff message. When you add a language to the agent, the existing email closing message and email handoff message are translated into it automatically and the new boxes are pre-filled, exactly as voice and chat copy already was. The AI disclaimer is the exception: it has a single text for every language and is not translated.Auto-translation is a starting point, not a sign-off. Read the pre-filled boxes before you go live — brand names, product names and legal wording are the parts most worth checking.
Handing a thread to a human
When the agent cannot finish a conversation itself, it escalates the thread. The reply that goes out at that moment is set in Handoff → Email → Handoff Message: “Reply with this message when the assistant escalates the email conversation to a human.”- Open your agent and go to the Handoff section.
- Select the Email tab.
- Check Handoff Platform at the top of the tab — see below.
- Fill in Message to Send in English (Default), plus one Message to Send in Language box for each configured language.
The Handoff card is greyed out, and can’t be opened, while the agent’s Transfer switch is off. Hovering over it shows “Transfer is disabled. Open Agent Settings, choose Toggle transfer, and turn it on to configure handoff.” To edit the email Handoff Message, Outcome options or Handoff Platform, open the agent’s Agent Settings, find the Toggle transfer card and switch Transfer on first. That switch also lets the agent offer a transfer to a person on voice and chat, so if you switched it off on purpose, check the agent’s voice and chat handoff settings before you turn it back on.
The handoff platform
Handoff Platform sits at the top of the Handoff → Email tab and shows where an escalation goes. For email, the connected inbox decides it: a Freshdesk mailbox escalates through Freshdesk connections, listed as “Freshdesk — instance URL”. Until a mailbox is connected the picker is disabled and reads “Connect a mailbox under Email Configuration first — the inbox decides where an escalation goes.” Each channel keeps its own platform, so changing the platform for chat no longer moves email with it.The conversation stays open
Escalating is no longer the end of the conversation. The thread moves to an Escalated state and stays open while the person works the same Freshdesk ticket. This applies whether the agent escalated or a supervisor selected Escalate in email history:- The AI stops replying — it does not interject while a human has the thread.
- The human’s replies are recorded on the SquawkVoice transcript as coming from a live agent rather than from the AI.
- The conversation is recorded as finished only when that person resolves or closes the ticket, or a supervisor selects Resolve in email history. Its outcome, transcript and usage are all written at that point, as long as SquawkVoice is still tracking the handoff (see below).
The tags SquawkVoice writes on a Freshdesk ticket to mark a conversation escalated or resolved are maintained for you, and are quietly restored if they are removed by hand. Deleting a tag is not a way to hand a thread back to the AI.
Email escalation is always available to the agent, even when the Transfer switch (Agent Settings → Toggle transfer) is off. That switch governs transferring a live call to a person; it does not hold back an email thread. What it does lock is the Handoff card in Studio, where you set the email handoff message and outcomes — see the note under the steps above.
Outcomes
Outcomes are how the agent records the way a conversation finished — and how those conversations are grouped in your reporting. Email outcomes live in Handoff → Email, under Outcome options: “Map how the agent escalates email conversations to a human.” Two outcomes are built in and cannot be edited or removed:
You can add your own outcomes alongside them — one per situation you want to be able to count later, such as a refund request or a delivery complaint that always needs a person. Click Add outcome, enter a name and a description (both are required), then confirm with the check mark. Outcomes belong to the handoff platform selected above them.
When the agent escalates a thread, it picks the outcome from your own outcomes — Contained and User Abandoned are never used for an escalation. If you haven’t added any, every escalation by the agent is recorded under a third outcome, Escalated, which isn’t listed in Outcome options. Once you have added some, the agent picks the one that fits best, and if its choice doesn’t match any of them the first outcome in your list is used. Add outcomes if you want to split escalations by reason.
AI disclaimer
An email agent’s replies carry a short AI disclaimer, so your customers can tell the message came from AI rather than from a person. It sits after the body of the reply as a separate paragraph of small grey text and, unless you change it, reads:This email was generated by AI. Verify important informationThe disclaimer is set per agent, on the AI Disclaimer card in Email Configuration → Config, below the Inactivity Timeout card. The switch at the top of the card turns it on or off for this agent. Below the switch, Disclaimer text replaces the default with your own wording, up to 2,000 characters. A counter beside the label shows how many you have used; go over the limit and a message under the field says how many characters to cut, and the text is not saved until you shorten it. Leave the field blank to use the default. Spaces at the start and end are dropped, so a field of nothing but spaces counts as blank. The field is greyed out while the switch is off. Changes save to the agent’s draft as you make them. On an agent you’ve published, they reach live emails at your next Publish.
Which emails carry it
The disclaimer is never sent on its own: a reply with nothing in it gets no disclaimer.
Below the disclaimer, the agent’s replies, its closing reply and the handoff notice end with a small Powered by SquawkVoice line, linked to the SquawkVoice website. It isn’t part of the AI Disclaimer card: it stays when you switch the disclaimer off, and it can’t be edited. The two follow-ups and replies your team writes don’t carry it.
- One text for every language. The disclaimer has no Message to Send in Language boxes and is not translated, so the English default, or your own wording, appears exactly as written on a reply in any language.
- Plain text only.
{{variables}}are not filled in, HTML and Markdown appear exactly as typed, and line breaks run together into a single line. - Separate from the chat widget. The chat widget’s AI Disclaimer is a different setting — see Chat Widget. Changing one does not change the other.
The inactivity window
An email conversation does not end when the agent sends a reply; it stays open waiting for the customer. The waiting period is set per agent, on the Inactivity Timeout card in Email Configuration → Config, with the Close After slider. The slider moves in one-day steps and saves when you release it.- Default: 72 hours (3 days)
- Range: 3 to 7 days (72 to 168 hours)
Follow-ups before abandonment
Rather than waiting in silence for the window to lapse, the agent sends two automatic follow-ups in the same email thread. Timing derives from that agent’s own Close After value, landing at roughly one third and two thirds of the way through, and the second always goes out before the thread closes.
The first reads “Just following up on your recent message — we haven’t heard back and wanted to check whether you still need help. Reply here and we’ll pick it right back up.” The second reads “This is a final check-in on your request. If we don’t hear back we’ll close this out for now, but you’re always welcome to reply and reopen it anytime.” Both are signed off with the agent’s name, or with “the team” where no name was recorded.
If the customer replies to either one, the conversation simply picks up where it left off. The second follow-up doubles as the abandonment notice — there is no separate message when the window actually closes, so before this change an abandoned thread ended with no outbound mail at all.
Follow-ups apply to email agents working a connected Freshdesk helpdesk inbox. They go out without the AI disclaimer, even when it is switched on. They do not appear as separate entries in email history or Email Analytics — the thread’s transcript shows them as agent messages.
How a conversation ends
Every email conversation finishes in one of three ways:
Supervisors can also act on a thread by hand from email history — see Email Analytics. Resolve ends a thread that hasn’t been escalated straight away, and records it as Contained. Escalate hands it to a person and leaves it open in the Escalated state, the same way as when the agent escalates. A conversation already with a person is still open and still resolvable; it offers Resolve only.
How email is billed
An email conversation is charged as one email session:- One charge per conversation, however many replies it takes, and whether or not it is escalated to a human.
- Charged when the conversation starts, not when it ends — so your wallet balance reflects a conversation while it is still running, and auto top-up can fire earlier than you might expect.
- Refunded if the agent fails to produce a reply.
- Not charged for a customer message the agent couldn’t answer because the session was refused, whether your balance couldn’t cover it or for another reason. That message is recorded in Email History as REJECTED and is never billed.
Behaviour worth knowing
- A reply is bounded work. The agent takes at most five rounds of knowledge-base look-ups and actions to compose one reply, allowing 60 seconds for each drafting pass and 30 seconds per look-up or action. The round limit and the 30-second limit still produce a reply: after the fifth round the agent sends whatever reply it has composed so far, and a look-up or action that runs past 30 seconds is stopped while the agent carries on without its result. A reply written against one of these limits may be less complete than usual. The 60-second limit works differently: if a single drafting pass takes longer, the reply is abandoned. Nothing is sent, the session charge is refunded, and the thread waits for the customer’s next message.
- Replies that do more take longer. A reply that searches a knowledge base or calls an action is slower, and costs more per turn, than a plain reply.
- Replies are deliberately concise. Email answers are kept short — point customers at a page or a document for anything genuinely long.
- The agent works from the recent part of the thread, not its entire history. Very long back-and-forth threads are exactly the ones worth escalating to a person.
- The whole FAQ list travels with every reply, so FAQ length shows up in the cost of every email turn.
Where to watch email conversations
- Optimize → Email Analytics tracks email volume, resolution rate, satisfaction and outcomes. It isn’t in an account user’s default sidebar; see Navigating Studio to add it with Customize sidebar or find it with Cmd/Ctrl+K.
- Optimize → Email History lists individual threads with their replies and escalations, and opens a full transcript for any one of them, including the handoff notices and a human agent’s replies, labelled Live Agent. A customer message the agent couldn’t answer because the session was refused, usually because your balance couldn’t cover it, is listed there too, as a REJECTED row. The Action Logs switch in the Email Thread heading of the transcript is off by default; switch it on to see the actions the agent ran mid-thread. In the Filters menu, switch on In-progress Only and you can step into a live thread yourself with Escalate or Resolve, from the menu beside View on its row or the Actions menu in the transcript; Escalated Only shows the conversations currently with a person, which offer Resolve.
Related pages
Knowledge Base
Add the FAQs, documents and web content your email agent answers from.
Connected Apps
Manage the Freshdesk connection that supplies your email mailboxes.
Email Analytics
Track containment and resolution, and review individual email threads.