Overview

This guide covers advanced agent configuration options that give you fine-grained control over your agent’s behavior:

Webhook Configuration — Real-time event notifications to your server
Last Message / Farewell — Professional conversation closing
Function Calling API — Programmatic function management
Multi-language Support — Serve customers in multiple languages
Greeting Configuration — Control who speaks first
Inactivity Timeout — Automatic call cleanup

1. Webhook Configuration

Overview

Webhooks send real-time HTTP POST notifications to your server when agent events occur. Use webhooks to:

Trigger actions in your external systems
Log call events for compliance
Update CRM records in real-time
Send notifications to your team
Sync data with external databases

Setup Webhook

Via Studio

Go to your agent → Settings → Webhook
Click Configure Webhook
Enter your Webhook URL (HTTPS required)
Click Save

Via API

PUT /api/agents/{agentId}/webhook
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "webhookUrl": "https://your-api.com/webhooks/talkifai"
}

Response:

{
  "success": true,
  "message": "Webhook URL updated successfully",
  "webhookUrl": "https://your-api.com/webhooks/talkifai"
}

Remove Webhook

DELETE /api/agents/{agentId}/webhook
Authorization: Bearer YOUR_API_KEY

Webhook Payload

Webhooks send JSON POST requests with the following structure:

{
  "event": "call.ended",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "agentId": "agent_xyz",
    "agentName": "Customer Support Bot",
    "callId": "call_abc123",
    "roomName": "agent_xyz_1705320000_user123",
    "duration": 300,
    "status": "completed"
  }
}

Webhook events are currently in beta. The payload structure may evolve. For critical integrations, log all webhook payloads for debugging.

Verify Webhook Signature (Coming Soon)

All webhook requests will include a signature header for security:

X-TalkifAI-Signature: sha256=abc123def456...

Verify in Node.js (Example)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// Usage in Express
app.post('/webhooks/talkifai', (req, res) => {
  const signature = req.headers['x-talkifai-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.TALKIFAI_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Webhook event:', req.body.event);
  res.status(200).send('OK');
});

Webhook Best Practices

Respond Quickly

Return 200 OK within 5 seconds. Process heavy tasks asynchronously.

Use HTTPS

Webhook URLs must use HTTPS for security. HTTP URLs will be rejected.

Log Everything

Log all webhook events for debugging and audit trails.

Validate Payload

Always validate the webhook payload structure before processing.

Troubleshooting

Webhook not receiving events

Check:

Is webhook URL accessible from public internet?
Is HTTPS enabled?
Is webhook configured on the agent?
Check your server logs for incoming POST requests

Test: Use a service like webhook.site to test webhook delivery.

Invalid URL format error

Problem: URL format validation failed.Solution:

Ensure URL starts with https://
Include full domain (e.g., https://api.example.com/webhook)
No trailing spaces or special characters

2. Last Message / Farewell

Overview

The Last Message (farewell message) is a closing statement your agent says when the conversation ends naturally. This creates a professional, polished ending to every call.

When It’s Used

Triggers Last Message:

✅ User says “thank you, goodbye”
✅ Issue resolved and user confirms
✅ Agent completes all tasks
✅ Natural conversation conclusion

Does NOT Trigger:

❌ Call dropped/technical error
❌ Inactivity timeout
❌ User hangs up abruptly
❌ Escalation to human

Configure Farewell Message

Via Studio

Go to your agent → Settings → Conversation
Find Last Message field
Enter your farewell message (max 100 characters)
Click Save

Examples

Customer Support:

"Thank you for contacting Acme Corp. Have a wonderful day!"

Sales:

"Thanks for your interest! Our team will be in touch soon. Goodbye!"

Appointment Booking:

"Your appointment is confirmed. See you then! Have a great day."

Medical:

"Thank you for calling City Clinic. Take care and stay healthy."

Best Practices

Keep It Short

Maximum 100 characters. Long farewells frustrate users.

Match Your Brand

Use tone consistent with your brand (professional, friendly, casual).

Include Well-Wishes

“Have a great day” leaves positive final impression.

Avoid CTAs

Farewell is not the time for “Visit our website” or other requests.

3. Function Calling API

Overview

Manage agent functions programmatically via dedicated API endpoints. Enable/disable functions, update configurations, and audit function usage.

Endpoints

Method	Path	Description
`PUT`	`/api/agents/{id}/function-calling`	Update function calling settings
`GET`	`/api/functions`	List built-in functions
`GET`	`/api/custom-functions/{agentId}`	List custom functions for agent
`POST`	`/api/custom-functions`	Create custom function
`PUT`	`/api/custom-functions/{id}`	Update custom function
`DELETE`	`/api/custom-functions/{id}`	Delete custom function

Update Function Calling Status

Enable/Disable Function Calling

PUT /api/agents/{agentId}/function-calling
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "functionCallingEnabled": true,
  "enabledFunctions": ["web_search", "end_call"]
}

Response:

{
  "success": true,
  "agent": {
    "id": "agent_xyz",
    "functionCallingEnabled": true,
    "enabledFunctions": ["web_search", "end_call"]
  },
  "message": "Function calling enabled successfully"
}

Parameters

Field	Type	Required	Description
`functionCallingEnabled`	boolean	✅	Enable or disable function calling
`enabledFunctions`	string[]	❌	Array of function IDs to enable

Add/Remove Individual Functions

Add Function:

PUT /api/agents/{agentId}/function-calling
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "functionCallingEnabled": true,
  "enabledFunctions": ["web_search", "end_call", "NEW_FUNCTION"]
}

Remove Function:

PUT /api/agents/{agentId}/function-calling
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "functionCallingEnabled": true,
  "enabledFunctions": ["web_search", "end_call"]
}

Built-in Functions

List Available Functions

GET /api/functions
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "functions": [
    {
      "id": "func_web_search",
      "name": "web_search",
      "label": "Web Search",
      "description": "Search the internet for current information",
      "category": "Information",
      "parameters": [
        {
          "name": "query",
          "type": "string",
          "description": "The search query",
          "required": true
        }
      ]
    },
    {
      "id": "func_end_call",
      "name": "end_call",
      "label": "End Call",
      "description": "Programmatically end the conversation",
      "category": "Call Control",
      "parameters": []
    }
  ]
}

Custom Functions

Create Custom Function

POST /api/custom-functions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "agentId": "agent_xyz",
  "name": "check_order_status",
  "label": "Check Order Status",
  "description": "Get current status of a customer order",
  "endpoint": "https://your-api.com/check-order",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_SECRET"
  },
  "parameters": [
    {
      "name": "order_id",
      "type": "string",
      "description": "The order ID to check",
      "required": true
    }
  ]
}

Update Custom Function

PUT /api/custom-functions/{functionId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "check_order_status_v2",
  "label": "Check Order Status (Updated)",
  "description": "Get current status and tracking info",
  "endpoint": "https://your-api.com/v2/check-order",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer NEW_SECRET"
  },
  "parameters": [
    {
      "name": "order_id",
      "type": "string",
      "description": "The order ID to check",
      "required": true
    },
    {
      "name": "include_tracking",
      "type": "boolean",
      "description": "Include tracking information",
      "required": false,
      "default": true
    }
  ]
}

Delete Custom Function

DELETE /api/custom-functions/{functionId}
Authorization: Bearer YOUR_API_KEY

4. Multi-language Support

Overview

Configure your agent to understand and respond in multiple languages. The agent automatically detects the user’s language and responds accordingly.

Supported Languages

Currently Supported:

Language	Code	Best For
English	`english`	Default, global
Urdu	`urdu`	Pakistan, South Asia
Sindhi	`sindhi`	Sindh region, Pakistan

Language validation: The API validates language codes against the supported list. Invalid languages will return a 400 error.

Configure Languages

Via Studio

Go to your agent → Settings → Languages
Select Primary Language (default response language)
Add Secondary Languages (auto-detected)
Click Save

Via API

POST /api/agents/{agentId}/languages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "languages": ["english", "urdu", "sindhi"]
}

Note: Languages are stored in the AgentLanguage table and linked to the agent.

How It Works

User speaks in Urdu
         │
         ▼
Language detection (automatic)
         │
         ▼
Switch to Urdu model/STT/TTS
         │
         ▼
Agent responds in Urdu

Best Practices

Set Clear Primary Language

Define one primary language for system prompt and default behavior.

Test Each Language

Test your agent in every configured language before going live.

Use Native Speakers

Have native speakers validate pronunciation and grammar.

Cultural Adaptation

Adapt examples and references for each language/culture.

Limitations

System prompt is in primary language only
Functions return data in primary language
Knowledge base content should match configured languages
Mixed language conversations may confuse detection

5. Greeting Configuration

Overview

Control who speaks first when the call starts — the agent (with a greeting) or the user.

Greeting Types

Agent First (Default)

Agent speaks immediately after user joins:

Call connects
    │
    ▼
Agent: "Hello! Thank you for calling Acme Corp. How can I help you today?"
    │
    ▼
User responds

Best for:

Customer support
Receptionist agents
Professional contexts
Guided conversations

User First

Agent waits for user to speak first:

Call connects
    │
    ▼
Agent: [waiting silently]
    │
    ▼
User: "Hi, I need help with my order"
    │
    ▼
Agent responds

Best for:

Outbound calls (user expecting call)
Survey/follow-up calls
Casual conversations
When user initiated the action

Configure Greeting

Via Studio

Go to your agent → Settings → Conversation
Select Greeting Type:
- AI speaks first (Agent First)
- User speaks first (User First)
If Agent First, enter Greeting Message
Click Save

Greeting Message Template

Hello! Thank you for calling [COMPANY NAME].

My name is [AGENT NAME], and I'm here to help you with [PURPOSE].

How can I assist you today?

Examples

Customer Support:

"Hello! Thank you for calling Acme Corp customer support. My name is Aria. How can I help you today?"

Appointment Reminder:

"Hi! This is an automated call from City Dental to confirm your appointment. Please press 1 to confirm or 2 to reschedule."

Sales Outbound:

"Hello! This is [Agent Name] calling from Acme Corp. Am I speaking with [Customer Name]?"

Advanced: Dynamic Greetings

Use variables in greeting messages:

Variable	Example	Output
`{time_of_day}`	”Good !"	"Good morning!”
`{date}`	”Today is "	"Today is Monday, January 15”
`{customer_name}`	”Hello "	"Hello John Smith”

Configure Dynamic Greeting

"Good {time_of_day}! Thank you for calling Acme Corp. My name is {agent_name}. How can I help you today?"

Variable support is coming soon. Currently, greeting messages are static text.

6. Inactivity Timeout

Overview

Inactivity Timeout automatically ends calls after a period of silence, preventing abandoned calls from consuming resources.

How It Works

Call active
    │
    ▼
No speech detected from either party
    │
    ▼
Timer starts (default: 30 seconds)
    │
    ├──→ Speech detected → Timer resets
    │
    └──→ Timer expires → Call ends automatically

Configure Timeout

Via Studio

Go to your agent → Settings → Conversation
Find Inactivity Timeout slider
Set value (10-60 seconds)
Click Save

Recommended Settings

Use Case	Timeout	Reasoning
Customer Support	30s	Standard, allows for thinking pauses
Sales	20s	Faster pace, quicker disconnect
Survey/Follow-up	20s	Short, structured conversations
Technical Support	45s	User may be troubleshooting
Elderly Care	60s	Users may need more time to respond

Via API

PATCH /api/agents/{agentId}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "inactivityTimeout": 45
}

Validation:

Minimum: 10 seconds
Maximum: 60 seconds
Default: 30 seconds

Timeout Behavior

When timeout expires:

Call ends automatically
Session marked as abandoned (not completed)
Billing session ends with actual duration

No warning message: Currently, the call ends silently without a warning message. This behavior may change in future updates.

Best Practices

Don't Set Too Short

Under 10 seconds frustrates users who pause to think.

Consider Your Audience

Elderly users need longer timeouts than tech-savvy users.

Monitor Abandoned Rate

High abandoned rate may indicate timeout too short.

Test Realistically

Test with real users to find optimal timeout duration.

Troubleshooting

Calls ending too quickly

Problem: Timeout may be set too short.Solution:

Increase timeout to 45-60 seconds
Check if background noise is being detected as speech
Verify microphone sensitivity settings

Abandoned calls consuming resources

Problem: Timeout too long or not triggering.Solution:

Decrease timeout to 20-30 seconds
Check if agent is generating background noise
Contact support if issue persists

Next Steps

Configure Webhooks

Set up real-time event notifications for your systems.

Customize Greetings

Create professional first impressions with custom greetings.

Manage Functions

Programmatically control agent functions via API.

Enable Multi-language

Serve customers in their preferred language.

Agent Settings — Complete agent configuration guide
Function Calling — Build custom functions
API Reference — Full agents API documentation
Multi-language Agents — Detailed language setup

Getting Started

Building Agents

Voice & Audio

Telephony

Intelligence & Memory

Analytics & Insights

Organization & Settings

Guides

​Overview

​1. Webhook Configuration

​Overview

​Setup Webhook

​Via Studio

​Via API

​Remove Webhook

​Webhook Payload

​Verify Webhook Signature (Coming Soon)

​Verify in Node.js (Example)

​Webhook Best Practices

Respond Quickly

Use HTTPS

Log Everything

Validate Payload

​Troubleshooting

​2. Last Message / Farewell

​Overview

​When It’s Used

​Configure Farewell Message

​Via Studio

​Examples

​Best Practices

Keep It Short

Match Your Brand

Include Well-Wishes

Avoid CTAs

​3. Function Calling API

​Overview

​Endpoints

​Update Function Calling Status

​Enable/Disable Function Calling

​Parameters

​Add/Remove Individual Functions

​Built-in Functions

​List Available Functions

​Custom Functions

​Create Custom Function

​Update Custom Function

​Delete Custom Function

​4. Multi-language Support

​Overview

​Supported Languages

​Configure Languages

​Via Studio

​Via API

​How It Works

​Best Practices

Set Clear Primary Language

Test Each Language

Use Native Speakers

Cultural Adaptation

​Limitations

​5. Greeting Configuration

​Overview

​Greeting Types

​Agent First (Default)

​User First

​Configure Greeting

​Via Studio

​Greeting Message Template

​Examples

​Advanced: Dynamic Greetings

​Configure Dynamic Greeting

​6. Inactivity Timeout

​Overview

​How It Works

​Configure Timeout

​Via Studio

​Recommended Settings

​Via API

​Timeout Behavior

Overview

1. Webhook Configuration

Overview

Setup Webhook

Via Studio

Via API

Remove Webhook

Webhook Payload

Verify Webhook Signature (Coming Soon)

Verify in Node.js (Example)

Webhook Best Practices

Troubleshooting

2. Last Message / Farewell

Overview

When It’s Used

Configure Farewell Message

Via Studio

Examples

Best Practices

3. Function Calling API

Overview

Endpoints

Update Function Calling Status

Enable/Disable Function Calling

Parameters

Add/Remove Individual Functions

Built-in Functions

List Available Functions

Custom Functions

Create Custom Function

Update Custom Function

Delete Custom Function

4. Multi-language Support

Overview

Supported Languages

Configure Languages

Via Studio

Via API

How It Works

Best Practices

Limitations

5. Greeting Configuration

Overview

Greeting Types

Agent First (Default)

User First

Configure Greeting

Via Studio

Greeting Message Template

Examples

Advanced: Dynamic Greetings

Configure Dynamic Greeting

6. Inactivity Timeout

Overview

How It Works

Configure Timeout

Via Studio

Recommended Settings

Via API

Timeout Behavior

Best Practices

Troubleshooting

Next Steps

Related Documentation