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

# API Integration

> Connect external APIs to your Dialgen AI agents with custom functions.

## Function Definition Structure

A complete function definition includes:

```json theme={null}
{
  "name": "function_name",
  "description": "Clear description of what this function does and when to use it",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  },
  "api_endpoint": "https://api.yourcompany.com/endpoint",
  "http_method": "POST",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body_template": {
    "field": "{{param1}}"
  }
}
```

***

## Components

### Name

* Use snake\_case
* Be descriptive but concise
* Unique within agent

```json theme={null}
{
  "name": "check_order_status"
}
```

### Description

The most important part. Be specific about:

* What the function does
* When to call it
* What triggers it

**❌ Bad:**

```json theme={null}
{
  "description": "Gets data"
}
```

**✅ Good:**

```json theme={null}
{
  "description": "Retrieves the customer's order status including tracking information and estimated delivery date. Call this when the customer asks about their order, delivery, shipping, or tracking."
}
```

### Parameters

Define using JSON Schema:

```json theme={null}
{
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order number or ID"
      },
      "email": {
        "type": "string",
        "format": "email",
        "description": "Customer's email for verification"
      }
    },
    "required": ["order_id"]
  }
}
```

### API Endpoint

Your API URL to call:

```json theme={null}
{
  "api_endpoint": "https://api.yourcompany.com/orders/status"
}
```

### HTTP Method

```json theme={null}
{
  "http_method": "POST"
}
```

Options: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`

### Headers

Authentication and content type:

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer {{API_KEY}}",
    "Content-Type": "application/json",
    "X-Custom-Header": "value"
  }
}
```

### Body Template

Map parameters to API request body:

```json theme={null}
{
  "body_template": {
    "order_id": "{{order_id}}",
    "customer_email": "{{email}}",
    "source": "ai_agent"
  }
}
```

***

## Context Variables

Use these built-in variables:

| Variable           | Description               |
| ------------------ | ------------------------- |
| `{{agent_id}}`     | Current agent ID          |
| `{{call_sid}}`     | Unique call ID            |
| `{{from_number}}`  | Caller's phone number     |
| `{{to_number}}`    | Called phone number       |
| `{{contact_id}}`   | Contact ID (if available) |
| `{{contact_name}}` | Contact name              |

Plus any custom variables from contact metadata.

***

## Parameter Types

### String

```json theme={null}
{
  "name": {
    "type": "string",
    "description": "Customer's full name"
  }
}
```

### Number

```json theme={null}
{
  "quantity": {
    "type": "number",
    "minimum": 1,
    "maximum": 100,
    "description": "Quantity to order"
  }
}
```

### Boolean

```json theme={null}
{
  "send_confirmation": {
    "type": "boolean",
    "description": "Whether to send email confirmation"
  }
}
```

### Enum

```json theme={null}
{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"],
    "description": "Priority level"
  }
}
```

### Array

```json theme={null}
{
  "items": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "description": "List of items"
  }
}
```

### Object

```json theme={null}
{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["street", "city"]
  }
}
```

***

## HTTP Methods

### GET

Retrieve data without side effects:

```json theme={null}
{
  "http_method": "GET",
  "api_endpoint": "https://api.yourcompany.com/customers/{{customer_id}}",
  "query_params": {
    "include": "orders,profile"
  }
}
```

### POST

Create new resources or submit data:

```json theme={null}
{
  "http_method": "POST",
  "api_endpoint": "https://api.yourcompany.com/orders",
  "body_template": {
    "customer_id": "{{customer_id}}",
    "items": "{{items}}"
  }
}
```

### PUT

Update existing resources:

```json theme={null}
{
  "http_method": "PUT",
  "api_endpoint": "https://api.yourcompany.com/customers/{{customer_id}}",
  "body_template": {
    "phone": "{{phone_number}}",
    "email": "{{email}}"
  }
}
```

***

## Authentication

### Bearer Token

```json theme={null}
{
  "headers": {
    "Authorization": "Bearer {{API_KEY}}"
  }
}
```

### API Key Header

```json theme={null}
{
  "headers": {
    "X-API-Key": "{{API_KEY}}"
  }
}
```

### Basic Auth

```json theme={null}
{
  "headers": {
    "Authorization": "Basic {{BASE64_CREDENTIALS}}"
  }
}
```

<Warning>
  Never hardcode API keys. Use environment variables: `{{API_KEY}}`.
</Warning>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="code" href="/guides/custom-functions/examples">
    View ready-to-use function examples
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/custom-functions/best-practices">
    Learn function calling best practices
  </Card>
</CardGroup>