Skip to content
Powsoo

Connect Retell

  1. Create a Retell agent

    In Retell’s dashboard, create a new agent. Any voice model works. Note the Agent ID — you’ll pick it from a dropdown in Powsoo later.

  2. Add powsoo_show_card as a server-side custom function

    Open the agent → Functions → Add custom function. Set the type to Server-side. Paste the JSON from Cards / tool reference as the function definition. Then set:

    • Name: powsoo_show_card (exact spelling — lowercase, underscores)
    • URL: https://api.powsoo.com/v1/retell/tools/show-card
    • speak_during_execution: false
    • speak_after_execution: false

    The agent pauses silently while the card is on screen. Do not set speak_during_execution: true — it causes the agent to talk over the card interaction.

  3. Add the system prompt snippet

    Append the system prompt template to the agent’s prompt. Minimum viable version:

    Use powsoo_show_card whenever the user should confirm a value (email, phone,
    address, name) or choose from a list. Never ask them to spell it back.
    The tool pauses you until the user taps. Accept edited values as canonical.

  4. Get a Retell API key

    In Retell → API Keys, create a key with permission for /v2/create-web-call. Copy the value.

  5. Connect the Retell account in Powsoo

    In the Powsoo dashboard → Voice platforms → Connect Retell. Paste the API key. Powsoo AES-GCM-encrypts it immediately — the plaintext never persists in Powsoo’s database or logs.

  6. Create a widget

    Go to Widgets → New widget. Pick the Retell account, then the agent from the dropdown (fetched live from Retell’s API). Configure Allowed origins for the domains the widget will run on.

    Copy the widget ID (wid_...) from the widget detail page — this goes in the embed snippet.

Local development

For local testing, Retell needs to reach your local API via a public URL. Use ngrok or Cloudflare Tunnel:

Terminal window
ngrok http 3001

Update the function URL in the Retell agent to the ngrok URL:

https://abc123.ngrok.io/v1/retell/tools/show-card

localhost and 127.0.0.1 are always allowed as widget origins without dashboard configuration.

Troubleshooting

See Troubleshooting for widget_unavailable, retell_auth_failed, and cards-not-appearing failures.