Docs - AI phone agents for SMB

Webhook actions allow your Telzino AI phone agents to interact with external systems during calls. You can fetch data, create support tickets, log calls to your CRM, and more.

Webhook Conditions

Webhooks can be triggered at different points in the call lifecycle:

Condition	When it Triggers	Use Cases
`before_call`	Before the agent answers	Pre-fetch caller info, check CRM records, inject context
`during_call`	While the call is active	Create support tickets, real-time lookups, live integrations
`after_call`	After the call ends	Log to CRM, send summaries, create follow-up tasks

Limits: You can configure one before_call webhook, up to four during_call webhooks, and one after_call webhook per agent.

Adding a Webhook via Dashboard

Navigate to Agent Settings

Log into your account and go to Agent Settings > Functions.

Add Webhook Action

Click the (+) button and select Webhooks.

Configure the Webhook

Fill in the webhook configuration form with the required fields.

Webhook Configuration

Each webhook requires the following configuration:

Required Fields

Field	Description
Name	Unique identifier for the webhook (e.g., `Create_Zendesk_Ticket`)
Friendly Name	Human-readable display name
Description	What this webhook does - helps the AI understand when to use it
Condition	When to trigger: `before_call`, `during_call`, or `after_call`
HTTP Method	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
URL	The endpoint to send the request to

Optional Fields

Field	Description
Headers	HTTP headers for authentication (e.g., API keys, Bearer tokens)
Parameters	Data to send in the request body - AI extracts values from the conversation
Include agent name in payload	On by default. `after_call` and other event-triggered webhooks (every condition except `during_call` and `before_call`) add an `agent_name` field with the agent’s name to the request body. Turn it off for APIs that reject unknown fields, such as Freshdesk. In the API this is `include_agent_name: false`.

Switch a webhook off

Each webhook card has an on/off switch. Turn it off to pause a webhook without deleting it: while it is off, the webhook is never called and the agent is not offered it as a tool. The card shows an Off badge until you turn it back on. Save the agent for the change to take effect. In the API this is enabled: false on the webhook. Leaving enabled out (or setting it to true) keeps the webhook on.

How Parameters Work

Parameters are the key to making webhooks intelligent. When you define parameters:

You specify the key name - What the external API expects (e.g., email, subject, priority)
You write instructions in the value field - The text you type in a parameter’s value becomes that parameter’s description for the AI. Use it to tell the AI what the parameter means and what rules to follow: where to get the value, what format it must be in, and what type to send (e.g., “always send as a string, never a number”)
The AI extracts actual values - During the call, the AI analyzes the conversation and fills in real values, following the rules you wrote

Some parameter keys are pre-filled automatically from call data when their names match (for example caller_phone, summary_text, transcript) — those are sent as-is without AI involvement.

If you leave a parameter value empty, the AI only sees the parameter’s name and will guess an appropriate value from the conversation context. This is not reliable — always describe the parameter and its expected format in the value field.

Example Parameter Configuration

{
  "parameters": [
    { "key": "customer_name", "value": "The caller's full name as spoken during the call" },
    { "key": "email", "value": "The caller's email address. If none was provided, use [email protected]" },
    { "key": "issue_summary", "value": "One-sentence summary of the customer's issue" },
    { "key": "priority", "value": "One of: low, normal, high. Default to normal unless the caller is upset or the issue is urgent" }
  ]
}

In this example, every value is an instruction to the AI, not a literal value:

customer_name and issue_summary tell the AI exactly what to extract from the conversation
email includes a fallback rule for when the caller doesn’t provide one
priority constrains the AI to an allowed set of values

Controlling Parameter Types and Formats

External APIs are often strict about types — a common failure is the AI sending a number where the API expects a string. Spell the required type and format out in the value text:

{
  "parameters": [
    { "key": "courseID", "value": "The courseID of the course the caller selected, taken from the GetCourses result. Always send it as a string, e.g. \"60802\", never as a number" },
    { "key": "franchiseID", "value": "The franchiseId from the GetCourses result, as a string, e.g. \"26\"" }
  ]
}

Without the type rule above, the AI may send {"courseID": 60802} and a strictly-typed API will reject it with a 400 validation error (The JSON value could not be converted to System.String). With it, the AI sends {"courseID": "60802"} and the request succeeds.

Real-World Examples

Zendesk Ticket Creation

Create a support ticket in Zendesk during or after a call:

{
  "name": "Zendesk_Ticket",
  "friendlyName": "Create Support Ticket",
  "description": "Creates a support ticket in Zendesk with call details and transcript",
  "condition": "during_call",
  "method": "POST",
  "url": "https://yourcompany.zendesk.com/api/v2/tickets.json",
  "headers": [
    {
      "key": "Authorization",
      "value": "Basic YOUR_BASE64_ENCODED_CREDENTIALS"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "parameters": [
    {
      "key": "ticket",
      "value": "{\"ticket\":{\"subject\":\"AI Call - Customer Inquiry\",\"comment\":{\"body\":\"Call summary and transcript\"},\"priority\":\"normal\"}}"
    }
  ]
}

Zendesk Authentication

For Zendesk, use Basic authentication with your email and API token:

Authorization: Basic base64(email/token:api_token)

In JavaScript:

const credentials = btoa(`${email}/token:${apiToken}`);
const header = `Basic ${credentials}`;

Freshdesk Ticket Creation

{
  "name": "Freshdesk_Ticket",
  "friendlyName": "Create Freshdesk Ticket",
  "description": "Creates a ticket in Freshdesk after the call",
  "condition": "after_call",
  "include_agent_name": false,
  "method": "POST",
  "url": "https://yourcompany.freshdesk.com/api/v2/tickets",
  "headers": [
    {
      "key": "Authorization",
      "value": "Basic YOUR_API_KEY_BASE64"
    }
  ],
  "parameters": [
    { "key": "subject", "value": "AI Voice Agent Call" },
    { "key": "description", "value": "" },
    { "key": "email", "value": "[email protected]" },
    { "key": "priority", "type": "integer", "value": "1" },
    { "key": "status", "type": "integer", "value": "2" }
  ]
}

Freshdesk rejects fields it does not recognise, so include_agent_name must be false for an after_call Freshdesk webhook. Otherwise the request fails with 400 Validation failed (invalid_field on agent_name).Freshdesk also requires numeric fields such as priority, status, source and group_id to be integers. Give those parameters "type": "integer" so the value is sent as a number. Without it, the value is sent as a string ("2") and Freshdesk rejects it with Value set is of type String.

Chained Lookups (Course Finder)

A common pattern is chaining two during_call webhooks: one fetches a list of options, the caller picks one, and a second webhook acts on the selection. The parameter instructions tell the AI how to carry values from the first webhook’s response into the second webhook’s request — including the exact type the API expects:

{
  "name": "Get_Course_Links",
  "friendlyName": "Course Link Tool",
  "description": "Gets registration links for the course the caller selected. Call this after the caller has chosen a course from the GetCourses results.",
  "condition": "during_call",
  "method": "POST",
  "url": "https://api.yourcompany.com/GetCourseLinks",
  "headers": [
    { "key": "Content-Type", "value": "application/json" }
  ],
  "parameters": [
    {
      "key": "courseID",
      "value": "The courseID of the course the caller selected, from the GetCourses response. Always send as a string, e.g. \"60802\", never as a number"
    },
    {
      "key": "franchiseID",
      "value": "The franchiseId from the GetCourses response, as a string, e.g. \"26\""
    }
  ]
}

CRM Integration (Before Call)

Fetch caller information before the agent answers:

{
  "name": "CRM_Lookup",
  "friendlyName": "Lookup Caller in CRM",
  "description": "Fetches caller history and preferences from CRM before the call",
  "condition": "before_call",
  "method": "GET",
  "url": "https://api.yourcrm.com/v1/contacts/lookup",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer YOUR_API_TOKEN"
    }
  ],
  "parameters": [
    { "key": "phone", "value": "" }
  ]
}

Post-Call Logging

Log call details to your system after the call ends:

{
  "name": "Call_Logger",
  "friendlyName": "Log Call to System",
  "description": "Sends call summary and transcript to internal logging system",
  "condition": "after_call",
  "method": "POST",
  "url": "https://api.yourcompany.com/calls/log",
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer YOUR_API_TOKEN"
    }
  ],
  "parameters": [
    { "key": "caller_phone", "value": "" },
    { "key": "call_summary", "value": "" },
    { "key": "transcript", "value": "" },
    { "key": "duration", "value": "" },
    { "key": "sentiment", "value": "" }
  ]
}

API Configuration

You can also configure webhooks via the API when creating or updating an agent. Webhooks are stored in the extensions.tools array. Model Context Protocol (MCP) connections use the sibling extensions.mcp_servers array. GET responses document the stored shape here; POST/PUT use the validated request shape here (they differ today). Example request body with webhooks only:

curl -X POST https://dashboard.telzino.com/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "organizationId": "your-org-id",
    "greetingMessage": "Hello! How can I help you today?",
    "systemPrompt": "You are a helpful support agent...",
    "extensions": {
      "tools": [
        {
          "type": "webhook",
          "name": "Create_Ticket",
          "friendlyName": "Create Support Ticket",
          "description": "Creates a support ticket when the customer has an issue",
          "condition": "during_call",
          "method": "POST",
          "url": "https://api.helpdesk.com/tickets",
          "headers": [
            { "key": "Authorization", "value": "Bearer API_TOKEN" }
          ],
          "parameters": [
            { "key": "subject", "value": "" },
            { "key": "description", "value": "" },
            { "key": "customer_email", "value": "" }
          ]
        }
      ]
    }
  }'

Best Practices

Write Clear Descriptions

The description helps the AI understand when to trigger the webhook. Be specific:Good: “Creates a support ticket when the customer reports a problem or needs help with their order”Bad: “Creates a ticket”

Use Meaningful Parameter Names

Use descriptive key names that match what your external API expects. The AI uses these names to understand what data to extract.

Describe Every Parameter in Its Value Field

The value field is instruction text for the AI. For each parameter, say what it is, where the AI should get it (the conversation, or a previous webhook’s response), and any rules — allowed values, fallbacks, and especially the expected type and format (e.g., “always send as a string”). Avoid leaving values empty; an undescribed parameter forces the AI to guess.

Secure Your Credentials

Never expose API keys in client-side code. Use environment variables or secure credential storage when possible.

Test Your Webhooks

Test your webhook endpoints independently before configuring them in your agent. Use tools like Postman or curl to verify they work correctly.

Troubleshooting

Issue	Cause	Solution
Webhook not triggering	Wrong condition	Verify the condition matches when you want it to fire
Authentication errors	Invalid credentials	Check your API key/token and header format
Missing data in request	Parameters not configured	Ensure all required parameters are defined
400 validation errors	Wrong value type or format	State the expected type in the parameter’s value text (e.g., “always send as a string, e.g. “60802"")
400 `invalid_field` on `agent_name`	The API rejects unknown fields	Turn off Include agent name in payload (`include_agent_name: false`)
Timeout errors	Slow external API	Consider using `after_call` for slow endpoints

Using Telzino

Dashboard

Connect App

Agent Functions

Agent Examples

Integrations

SIP

Webhooks

Webhook Conditions

Adding a Webhook via Dashboard

Webhook Configuration

Required Fields

Optional Fields

Switch a webhook off

How Parameters Work

Example Parameter Configuration

Controlling Parameter Types and Formats

Real-World Examples

Zendesk Ticket Creation

Freshdesk Ticket Creation

Chained Lookups (Course Finder)

CRM Integration (Before Call)

Post-Call Logging

API Configuration

Best Practices

Troubleshooting

​Webhook Conditions

​Adding a Webhook via Dashboard

​Webhook Configuration

​Required Fields

​Optional Fields

​Switch a webhook off

​How Parameters Work

​Example Parameter Configuration

​Controlling Parameter Types and Formats

​Real-World Examples

​Zendesk Ticket Creation

​Freshdesk Ticket Creation

​Chained Lookups (Course Finder)

​CRM Integration (Before Call)

​Post-Call Logging

​API Configuration

​Best Practices

​Troubleshooting

Webhook Conditions

Adding a Webhook via Dashboard

Webhook Configuration

Required Fields

Optional Fields

Switch a webhook off

How Parameters Work

Example Parameter Configuration

Controlling Parameter Types and Formats

Real-World Examples

Zendesk Ticket Creation

Freshdesk Ticket Creation

Chained Lookups (Course Finder)

CRM Integration (Before Call)

Post-Call Logging

API Configuration

Best Practices

Troubleshooting