> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Define Custom API Functions for Your AI Voice Agents

> Connect VoiceInfra agents to any REST API with custom functions. Define endpoints, parameters, and auth headers for real-time data and actions in calls.

Custom functions let you turn any REST API endpoint into a tool your AI agent can call during a live conversation. You define the endpoint URL, request type, authentication headers, and a plain-English description of when to use the function. The moment the caller's words match the intent described, the agent calls the API, receives the response, and incorporates the result into what it says next — all while the caller waits.

## What Custom Functions Enable

* Look up customer account status, balance, or subscription tier from your database
* Check live inventory levels or product pricing before quoting a customer
* Create support tickets in your helpdesk system in real time
* Send an SMS confirmation via Twilio while the caller is still on the line
* Geocode a caller-provided address or check a delivery status
* Verify appointment availability and confirm bookings
* Retrieve order status using a dynamically extracted order ID

## Creating a Custom Function

<Steps>
  <Step title="Go to Settings → Functions → Create Function">
    Open your VoiceInfra dashboard and navigate to **Settings → Functions**. Click **Create Function**.
  </Step>

  <Step title="Name your function">
    Enter a function name between 5 and 100 characters using alphanumeric characters and underscores only — for example, `check_order_status` or `get_account_balance`. This name is used internally by the LLM to identify the function.
  </Step>

  <Step title="Write an LLM-optimized description">
    Write a clear description (10–500 characters) that tells the AI exactly when to call this function. Be specific. For example: *"Call this function when the user asks about their order status, delivery date, or shipping tracking. Requires the order ID."* The more precise your description, the more reliably the agent invokes the function at the right moment.
  </Step>

  <Step title="Set the endpoint URL">
    Enter the full URL of your API endpoint. Use curly-brace placeholders for dynamic path parameters — for example, `https://api.yourbusiness.com/orders/{order_id}`. The agent extracts the value from the conversation and substitutes it automatically.
  </Step>

  <Step title="Select the request type">
    Choose **GET** for data retrieval, **POST** for creating or updating data, or **Async** for fire-and-forget operations where you don't need to block the conversation waiting for a response.
  </Step>

  <Step title="Add authentication headers">
    In the **Request Headers** section, add any headers your API requires — for example, `Authorization: Bearer your-api-key` or `X-API-Key: your-key`. These headers are encrypted before storage and never exposed in logs.
  </Step>

  <Step title="Define the request body (POST only)">
    For POST requests, define the JSON body structure. Use placeholders for values the agent will supply from the conversation.
  </Step>

  <Step title="Save and assign to your agent">
    Click **Save**. Then open your agent's configuration, go to the **Functions** tab, and enable this function for the agent. Test it before going live.
  </Step>
</Steps>

## Start From a Template

Speed up setup by starting from a pre-built template. Available templates include:

| Template                           | Use case                          |
| ---------------------------------- | --------------------------------- |
| **Basic REST API (GET)**           | Read data from any GET endpoint   |
| **POST Request with Body**         | Submit data to a POST endpoint    |
| **Twilio Send SMS**                | Send an SMS message mid-call      |
| **Mailjet Send Email**             | Trigger a transactional email     |
| **Geocode Location**               | Convert an address to coordinates |
| **Check Appointment Availability** | Query your scheduling system      |

You can also import directly from a **cURL command** — paste any cURL command from your API docs and VoiceInfra parses the URL, headers, and body automatically.

## Example Function Configuration

```json theme={null}
{
  "name": "check_order_status",
  "description": "Call this when the user asks about their order status or delivery. Requires the order ID.",
  "method": "GET",
  "url": "https://api.yourbusiness.com/orders/{order_id}",
  "headers": {
    "Authorization": "Bearer {{env.API_KEY}}"
  }
}
```

When a caller says *"What's the status of order 45892?"*, the agent extracts `45892` as the `order_id`, calls your API, and responds with the live data returned — for example: *"Your order is out for delivery and will arrive tomorrow by 3pm."*

## Supported Request Types

| Type      | When to use                                                                             |
| --------- | --------------------------------------------------------------------------------------- |
| **GET**   | Fetching data — account lookup, inventory check, appointment slots, order status        |
| **POST**  | Creating or updating — create a ticket, book an appointment, send a notification        |
| **Async** | Fire-and-forget for slow operations — don't block the conversation waiting for a result |

<Note>
  Use **Async** for operations that take more than a few seconds or don't need to return data to the conversation — for example, sending a notification or logging an event.
</Note>

## Testing Functions

Before assigning a function to a live agent, use the built-in test tool to verify it works:

1. Open the function in **Settings → Functions**
2. Click **Test Function**
3. Enter sample parameter values (e.g., `order_id: 45892`)
4. Review the API response

Confirm the response format is what you expect before deploying. If the API returns an error, the test tool shows the full HTTP response to help you debug.

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How does the AI know when to call a function?">
    The agent reads the description you write for each function and decides whether the current moment in the conversation matches the described intent. Write specific, action-oriented descriptions — start with phrases like "Call this when the user asks about…" or "Use this to look up…". Vague descriptions lead to missed or incorrect invocations.
  </Accordion>

  <Accordion title="Is there a limit on functions per agent?">
    There is no strict limit on the number of custom functions you can create or assign to an agent. Keep in mind that assigning many functions increases the LLM's decision space — for best results, assign only the functions relevant to each agent's purpose.
  </Accordion>

  <Accordion title="How do I secure my API endpoint?">
    Add authentication headers in the function configuration (API key, Bearer token, etc.). VoiceInfra encrypts all stored credentials at rest. Your endpoint should also validate the token on every request to prevent unauthorized access.
  </Accordion>

  <Accordion title="Can a function return data back to the conversation?">
    Yes. The API response is passed back to the LLM and included in the agent's context. The agent uses the returned data to form its next spoken response. Make sure your API returns structured JSON with clearly named fields for best results.
  </Accordion>

  <Accordion title="What if a function returns an error?">
    The agent receives the error response and handles it gracefully — informing the caller of the issue, retrying if appropriate, or escalating to a human agent. Configure your agent's fallback behavior in the agent prompt.
  </Accordion>

  <Accordion title="Can I use environment variables for API keys?">
    Yes. Reference environment variables in header values using the `{{env.VARIABLE_NAME}}` syntax. Manage environment variables in **Settings → Environment Variables** to avoid hardcoding credentials in function configurations.
  </Accordion>
</AccordionGroup>