Setup guide - Retell AI

Create your server endpoint

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method.Example endpoint:

// install the sdk: https://docs.retellai.com/get-started/sdk
import { Retell } from "retell-sdk";
import express, { Request, Response } from "express";

const app = express();
app.use(express.json());

app.post("/webhook", (req: Request, res: Response) => {
  const {event, call} = req.body;
  switch (event) {
    case "call_started":
      console.log("Call started event received", call.call_id);
      break;
    case "call_ended":
      console.log("Call ended event received", call.call_id);
      break;
    case "call_analyzed":
      console.log("Call analyzed event received", call.call_id);
      break;
    default:
      console.log("Received an unknown event:", event);
  }
  // Acknowledge the receipt of the event
  res.status(204).send();
});

Test your endpoint locally

Before going live, test your application integration locally. For example, host the endpoint on localhost:8080/webhook and test with Postman:

Test using this CURL command:

curl --location 'localhost:8080/webhook' \
--header 'Content-Type: application/json' \
--data '{
  "event": "call_ended",
  "call": {
    "call_type": "phone_call",
    "from_number": "+12137771234",
    "to_number": "+12137771235",
    "direction": "inbound",
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
    "call_status": "registered",
    "metadata": {},
    "retell_llm_dynamic_variables": {
      "customer_name": "John Doe"
    },
    "start_timestamp": 1714608475945,
    "end_timestamp": 1714608491736,
    "disconnection_reason": "user_hangup",
    "transcript": "...",
    "opt_out_sensitive_data_storage": false
  }
}'

Make your local endpoint online

Deploy your endpoint using Ngrok:

Install ngrok:

brew install ngrok/ngrok/ngrok

Start ngrok:

ngrok http http://localhost:8080

You’ll see a console UI like this:

ngrok                                                                   (Ctrl+C to quit)

Session Status                online
Account                       inconshreveable (Plan: Free)
Version                       3.0.0
Region                        United States (us)
Latency                       78ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://84c5df474.ngrok-free.dev -> http://localhost:8080

Your webhook endpoint will be https://84c5df474.ngrok-free.dev/webhook

You have two options:Option 1: Register an account level webhook Set up through the system settings’ webhooks tab for events related to any agent under your account.

Account-level webhook URL configuration in the dashboard settings

Option 2: Register an agent level webhook Set up through the dashboard’s agent detail page. Note: If set, account level webhooks will not be triggered for that agent.

Agent-level webhook URL configuration in the agent detail page

The webhook URL field accepts dynamic variables. Type {{ to open a list of available variables, or wrap a name in double curly braces yourself (for example https://example.com/webhook?customer={{customer_name}}). Each variable is replaced with its value per call before the event is delivered.Use the Test button to send a sample request to your endpoint. If your URL uses variables whose values are only known during a live call (such as contact or CRM fields), the Test button is disabled and a tooltip explains why — the webhook will still work on real calls, but it can’t be tested here because there are no values to substitute yet. Variables that Retell can resolve ahead of time, such as system variables and your version’s environment variables, can be tested normally.

Verify your webhook endpoint

Start a web call in the dashboard to verify the webhook is triggered correctly.