Inbound call webhook: pass caller data to your agent
Use the inbound call webhook to look up the caller before your AI agent answers and pass details such as their name or order status into the prompt.
The inbound call webhook lets your system look up the caller before your AI agent answers. When a call comes in, Trillet sends a GET request to your URL with the caller's phone number, and the variables your endpoint returns are filled into the agent's prompt and welcome message. In the call flow editor it is the Pre-call webhook, under Settings > Advanced Settings > Data & Events > Webhooks. Web calls to the same call flow use it too.
How the request is sent
- The method is
GET, with the headers and query parameters you configure. - The caller's number is sent as the
phone_numberquery parameter. To put it somewhere else, use the{{_system.phoneNumber}}placeholder in the URL, a header or a parameter. Phone number metadata tags are available as{{_metadata.your_key}}. - Your endpoint must respond with HTTP 200 within 10 seconds. If it fails or times out, the call goes ahead without the variables.
Prerequisites
Before you begin, make sure you have:
- An account for your application.
- A valid URL to handle webhook calls.
Configure Webhook Settings
To get started, open your call flow, go to Settings > Advanced Settings > Data & Events > Webhooks, expand Pre-call webhook, and set up your webhook URL, headers, and query parameters. Publish the call flow afterwards: live calls use the published version.
- Enter your webhook URL
- Add your API authentication details, such as bearer tokens or API keys.
- Include any dynamic parameters you wish to pass, such as customer_name and order_status.

Create an API Receiver
- Create an API endpoint to process incoming webhook requests.
app.get('/get-webhook', (req, res) => {
console.log("Request Headers: ", req.headers);
console.log("Request Query: ", req.query);
// Respond with variables for AI prompt
res.status(200).json({
variables: {
customer_name: "John Doe",
order_status: "shipped"
}
});
});
Note: The API response should always include the variables object in the following format:
{
"variables": {
"customer_name": "John Doe",
"order_status": "shipped"
}
}
Replace Variable in AI Prompts
Use the returned variables from your webhook to dynamically update AI prompts.
Example Prompt in Call Flow Designer:
Hello, {{customer_name}}, your order status is {{order_status}}.
When the webhook processes the request, variables are replaced dynamically:
Hello, John Doe, your order status is shipped.Last updated on