> For the complete documentation index, see [llms.txt](https://docs.agentalk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agentalk.io/ai-agents/agent-functions/connect-external-apis-as-functions.md).

# Connect external APIs as functions

An External API function lets your agent call a third-party API in real time during a call and use the response in its reply. You can connect any REST endpoint, including automation tools, CRMs, or custom backends.

### When to use an External API function

Use this function type when the agent needs information it doesn't have in its instructions or knowledge base.

Common use cases include:

* Check whether a product is in stock and return its price.
* Look up a customer's account status before discussing their support issue.
* Create a record in a CRM when a sale is confirmed during the call.
* Trigger a workflow in an automation platform when a specific condition is met.

### Before you start

Make sure you have the following:

* An agent created. See [**Create an agent**](/ai-agents/create-an-agent.md).
* A REST API endpoint that Agentalk can call.
* The API URL and any required authentication credentials.

### Configure the external API function

Follow these steps to add and configure an External API function.

The following example shows how the setup appears in the interface.

{% stepper %}
{% step %}

### Access the function settings

1. Go to **AI Agents** in the left navigation and open the agent you want to configure.
2. Select the **Functions** tab.
3. In the **External API** section, click **+ Add Function**.

<figure><img src="/files/pvoSBTj7tzbw8qrLaDrv" alt=""><figcaption></figcaption></figure>

This opens the function configuration panel.
{% endstep %}

{% step %}

### Define basic information

Define what the function does and when it runs.

1. In the **Function Name** field, enter a unique name using only letters, numbers, or underscores (for example, `search_products`).
2. In the **Function Description** field, describe what the function does and when the agent should use it.\
   Example: `Search products in the system by name or category.`
3. In the **Response Message** field, enter the message the agent will use after the function runs. This message can include data returned by the API.

<figure><img src="/files/YzaO8XlNYkPZm4XgqJqr" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Configure API settings

Define how the agent connects to your API.

1. In the **HTTP Method** dropdown, select the request method required by your API (for example, `GET` or `POST`).
2. In the **API URL** field, enter the full endpoint URL.\
   Example: `https://api.yourstore.com/search`
3. (Optional) Add headers if your API requires them:
   * Click **Add Header +.**
   * Enter the header name (for example, `Authorization`).
   * Enter the value (for example, an API key or token).
4. Add parameters:
   * Click **Add Parameter +.**
   * In **Parameter Name**, enter the parameter name exactly as your API expects it (for example, `product_name`).
   * In **Parameter Description**, describe what the agent should extract from the conversation.\
     Example: *The name of the product the caller is asking about.*
   * Enable **Required** if the parameter must always be included in the request.
5. Click **Create Function +** to add the function.

<figure><img src="/files/lKLmuGywA0DcqTIchBG2" alt=""><figcaption></figcaption></figure>

The agent uses the parameter description to determine what value to send when the function runs.
{% endstep %}

{% step %}

### Save and test

Finish the setup and verify the function works.

* Click **Save draft** to keep changes without activating the agent.
* Click **Save** to apply the configuration.
* Click **Save and test agent** to run a test call.
* Click **Cancel** to discard changes.
  {% endstep %}
  {% endstepper %}

### Verify the function behavior

After testing, confirm the following:

* The function triggers at the correct time.
* The agent sends the correct parameters.
* The agent uses the API response accurately.
* The response time is suitable for a live call.

### Example: External API function in a call

This example shows how the function is configured and used during a call.

#### Configuration

* **Function name:** `check_product_availability`
* **HTTP method:** `GET`
* **API URL:** `https://api.gadgetstore.com/v1/products/search`
* **Headers:**
  * `Authorization: Bearer YOUR_API_KEY`
* **Parameters:**
  * `product_name` (required): Product name mentioned by the caller

#### Call flow example

This example shows how the function runs during a conversation.

* Caller asks: "Do you have the iPhone 17 in stock?"
* The agent runs the function.
* The agent sends `product_name: "iPhone 17"` to the API.
* The API returns availability and price.
* The agent responds with the information.

### Next steps

Here are the recommended next steps after completing this guide:

* [**Use built-in functions**](/ai-agents/agent-functions/use-built-in-functions.md): Combine external APIs with core agent actions.
* [**Manage contacts**](/contacts/manage-contacts.md): Use contact data to personalize API responses.
* [**Create an agent**](/ai-agents/create-an-agent.md): Apply your API integration in a live agent.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.agentalk.io/ai-agents/agent-functions/connect-external-apis-as-functions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.