Skip to main content
Agents on Vapi, Retell AI and ElevenLabs

Retell Chat Agents

See your Retell AI chat agents, edit their prompt and welcome message, sync the webhook and use them for chat in a web widget.

Written By voiceaiwrapper

Last updated 26 days ago

Retell AI keeps text chat agents separate from its voice agents. VoiceAIWrapper lists your Retell chat agents on their own page, so you can change their prompt and opening message, connect them to VoiceAIWrapper, and use them as the chat side of a web widget.

You build chat agents in your Retell dashboard. VoiceAIWrapper reads them from your Retell account each time you open the page, so new ones show up without any import.

Applies to: Retell AI Pods (an engine or provider connection). Vapi, ElevenLabs and VAW Native don't have a separate chat agent list.

Before you start

  • A connected Retell AI Pod. See Connect Retell AI.
  • At least one chat agent created in the same Retell account.

Find your chat agents

  1. In the sidebar, switch to your Retell AI Pod.
  2. Open Chat Agents.

The page is titled Retell Chat Agents. Each row is one chat agent:

ColumnWhat it shows
NameThe chat agent's name in Retell. If it has no name, you see its ID.
Agent IDRetell's ID for the agent, with a copy button.
VersionThe agent version, such as v3.
Webhook URLWhere the agent sends its events. Not set means it has no webhook.
WebhookSynced if the agent sends its events to VoiceAIWrapper, Sync required if it doesn't.
Voice, Language, EngineDetails from Retell. Engine shows whether the agent runs on a Retell LLM or a conversation flow.
ModifiedWhen the agent last changed in Retell.

Type in Search agents... to search across every column, or use the filter button to narrow by name, ID, webhook status, engine or date modified. The line under the search box shows how many agents match, for example "Showing 3 of 8 agents".

A Retell AI Pod's Chat Agents page (title Retell Chat Agents) with at least two chat agents: one row showing the green Synced badge in the Webhook column and one showing Sync required with the Sync now button. The Name, Agent ID, Version, Webhook URL and Webhook columns are visible. Blur webhook URLs that point at a private domain.

Sync the webhook

A chat agent has to send its events to VoiceAIWrapper before VoiceAIWrapper can record its chats. Once it's synced, every chat that runs through one of your widget campaigns is saved to Chat Logs once Retell finishes analysing it after the chat ends, and is billed to the client the campaign belongs to if you charge for chats.

  1. Find a row that shows Sync required in the Webhook column. Hover over it to see the webhook the agent uses now.
  2. Click Sync now.

You'll see Webhook updated successfully, and the row changes to Synced. If you see Failed to update webhook, check that the Pod's Retell API key still works, then try again.

Syncing replaces the chat agent's webhook URL in Retell with VoiceAIWrapper's. If the agent sent its events to another address (for example your own automation), that address stops receiving them from Retell. To keep getting chat events, add your address as the widget campaign's Post-call event webhook (Settings β†’ Webhooks and Emails). VoiceAIWrapper forwards each chat event to it. See Post-Call Event Webhook.

Edit the prompt and welcome message

  1. Click the chat agent's row. A sheet opens with the agent's name and ID at the top.

  2. Choose a Welcome Message Type:

    OptionWhat happens
    User Initiates: AI remains silent until users speak first.The agent waits for the visitor's first message.
    AI Initiates: AI begins with a dynamic begin message.The agent writes its own opening line.
    AI Initiates: AI begins with your defined begin message.The agent opens with the text you type in Welcome Message.
  3. If you chose your own begin message, type it in Welcome Message.

  4. Edit the System Prompt. It can't be empty ("System prompt is required").

  5. Click Update Agent. The button stays greyed out until you change something.

You'll see Agent updated successfully and the sheet closes. The change is saved to your Retell account straight away.

The edit sheet opened by clicking a chat agent row: agent name and ID at the top, Welcome Message Type set to 'AI Initiates: AI begins with your defined begin message.', the Welcome Message field filled in, the System Prompt box with text, and the Update Agent button at the bottom.

Good to know:

  • Conversation flow agents can't be edited here. The sheet shows "This agent is a conversational flow agent. It cannot be edited here." Edit them in your Retell dashboard.
  • The prompt lives on the agent's Retell LLM. VoiceAIWrapper saves your change to the LLM the chat agent uses. If another Retell agent shares that LLM, it gets the change too.
  • Everything else (model, knowledge base, functions, voice) is edited in your Retell dashboard.

Use a chat agent in a web widget

A chat agent powers the chat side of a web widget on a Retell AI Pod. You set this up in an Inbound widget campaign.

Available on: plans that include Web widget. Without it, the Web Widget tab shows an upgrade prompt.

  1. Create or open an inbound widget campaign on your Retell AI Pod. See Create an Inbound Widget Campaign.
  2. Open the Web Widget tab. It opens on Configuration.
  3. Under Interaction, set Interaction mode to Chat or Voice + Chat.
  4. Under Agents, pick your agent in Chat Agent. Until you do, you'll see Retell Chat Agent Required: "Retell requires a separate chat agent. Please select a chat agent below for chat mode to work properly."
  5. If the picker shows "Sync our webhook to use this agent.", click Sync now under it.
An inbound widget campaign on a Retell AI Pod, Web Widget tab, Configuration tab: Interaction mode set to Chat, the yellow 'Retell Chat Agent Required' message under it, and the Chat Agent picker in the Agents section below.

Offering chat to a client? The widget builder reminds you to turn on chat mode in the client's configuration and to turn on chat billing in their Stripe plan. Without chat billing, the client isn't charged for chats. See Bill Chat Conversations.

Give clients access

On a Retell AI workspace, the Chat Agents area sets what the client can do with the chat agents you assign. Under Chat Agent Access, choose:

  • No Access: the client doesn't see chat agents.
  • View Only: the client can see the chat agents you assigned.
  • View & Edit: the client can also edit the chat agent prompt. This level needs a plan that includes Advanced client access controls.

See Set Client Permissions on Vapi, Retell and ElevenLabs Workspaces.

Troubleshooting

The list comes from the Retell account connected to this Pod. Check that the chat agent was created in that same Retell account, then reload the page. If you have several Retell AI Pods, make sure you're in the right one.

It only appears on Retell AI Pods. Switch to your Retell AI Pod in the sidebar.

Check the chat agent's Webhook column on the Chat Agents page. If it says Sync required, click Sync now. VoiceAIWrapper only records chats from agents that send their events to it, and only chats that start from one of your widget campaigns.