Create chat agent

Chat agents hold text conversations with your users. They use the same prompt types, functions, and knowledge bases as voice agents, so you can offer the experience you built for calls over text as well — on your website, over SMS, or inside your own app.

​

When to use a chat agent

Use a chat agent when your users type instead of talk:

• Website support — answer product, billing, or order questions in a chat widget on your site.
• SMS conversations — run two-way text threads on a Twilio number, such as appointment reminders with reschedule handling.
• In-app assistant — power a chat UI you build into your own web or mobile app.

For example, an e-commerce store embeds a chat agent in its help center to handle order-status questions: the agent looks up the order with a custom function and replies with the tracking link, so support staff only see the conversations the agent escalates.

​

Create a chat agent

To create chat agents programmatically, call Create Chat Agent with a Retell LLM or conversation flow response engine.

​

Convert an existing voice agent

Converting creates a new chat agent based on your voice agent’s setup. The original voice agent is not modified and keeps working as before. Conversion removes what doesn’t apply to text:

• Nodes and functions: call transfer (including bridge and cancel transfer), press digit (IVR navigation), and mid-call SMS are deleted, and any dangling flow connections are cleaned up.
• Settings: voice, speech, transcription, and call settings (voicemail detection, DTMF input, and similar) don’t exist on chat agents.

Conversion works in both directions: a chat agent’s More options menu offers Convert to Voice Agent.

​

Chat settings

Chat agents share most configuration with voice agents — prompt, functions, knowledge base, webhooks, security, and Post chat extraction — and add a Chat settings section:

• Auto-close inactive chats — end the chat automatically when the user stops responding. Set the timeout anywhere from 2 minutes to 72 hours (end_chat_after_silence_ms; the API default is 1 hour).
• Auto-close message — an optional message sent when a chat is closed automatically (auto_close_message).

For chat events, webhooks fire chat_started, chat_ended, and chat_analyzed by default; add transcript_updated through the agent’s webhook_events if you need per-message updates. The agent’s Workflow page works the same as it does for voice, with the two function slots named pre-chat and post-chat functions: look the user up in your CRM before the agent’s first message, then log the outcome once the chat ends. See agent workflow.

​

Welcome message

For a single-prompt chat agent, choose User speaks first or AI speaks first under Welcome Message. Inbound chats always start with the user, regardless of this setting. For outbound SMS, select AI speaks first; otherwise the agent sends no initial message. With AI speaks first, choose Dynamic message to generate the greeting from the agent’s instructions, or Custom message to send the text you enter. Custom messages support dynamic variables, such as Hi {{customer_name}}, can we confirm your appointment?. For a conversation flow chat agent, select the begin node and set Who speaks first to AI speaks first. Configure the opening message in the flow’s first speaking node.

​

Deploy your chat agent

Chat agents are headless — Retell does not host a chat UI for end users, so you choose how to surface the agent:

• Website widget — embed a single <script> tag on your site for text chat, in-browser voice calls, or both, with no backend required. See website widget.
• SMS — connect the agent to a Twilio phone number so users can text it directly. See Enable SMS.
• Custom integration — build your own UI on the chat API: Create chat starts a session, Create chat completion exchanges messages, and the session stays open until you call End chat or the inactivity timeout closes it.

Once live, set up alert rules on chat volume, success rate, negative sentiment, or cost to hear about problems without watching the dashboard.

​

FAQ