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

# Trigger Outbound Calls via API

> Programmatically initiate outbound calls from your CRM, n8n, Make, Zapier, or any HTTP client

## Overview

The Public API lets you trigger outbound calls programmatically. Use it to connect Tala with your CRM, automation platforms (n8n, Make, Zapier), or any system that can send HTTP requests.

When you trigger a call, Tala dials the specified phone number and runs the workflow associated with the agent. You can optionally pass context data that the AI agent will use during the conversation.

## Authentication

All requests require an API key passed in the `X-API-Key` header. You can generate API keys from your Tala dashboard.

<Warning>
  Keep your API key confidential. Do not expose it in client-side code or public repositories.
</Warning>

## Endpoint

```
POST /api/v1/public/agent/{trigger_uuid}
```

| Parameter      | Location | Type   | Description                                                                   |
| -------------- | -------- | ------ | ----------------------------------------------------------------------------- |
| `trigger_uuid` | Path     | string | The public trigger UUID associated with the workflow trigger you want to call |

### Request Headers

| Header         | Required | Description        |
| -------------- | -------- | ------------------ |
| `X-API-Key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Request Body

```json theme={null}
{
  "phone_number": "+33612345678",
  "initial_context": {
    "customer_name": "Jean Dupont",
    "appointment_date": "2026-03-20"
  }
}
```

| Field             | Type   | Required | Description                                                               |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------- |
| `phone_number`    | string | Yes      | Phone number to call in E.164 format (e.g., `+33612345678`)               |
| `initial_context` | object | No       | Key-value pairs of context data available to the AI agent during the call |

### Response

```json theme={null}
{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "call-jean-dupont-2026-03-15"
}
```

| Field               | Type    | Description                                                |
| ------------------- | ------- | ---------------------------------------------------------- |
| `status`            | string  | Always `initiated` when the call request has been accepted |
| `workflow_run_id`   | integer | Unique identifier for the triggered call                   |
| `workflow_run_name` | string  | Human-readable name for the call                           |

## Example

```bash theme={null}
curl -X POST "https://api.tala-assistant.com/api/v1/public/agent/YOUR_TRIGGER_UUID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33612345678",
    "initial_context": {
      "customer_name": "Jean Dupont",
      "reason": "Follow-up on quote request"
    }
  }'
```

## Rate Limits

API calls are limited to **60 requests per minute** per API key. If you exceed this limit, you will receive a `429 Too Many Requests` response.

## Error Codes

| Status Code | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `400`       | Telephony provider is not configured, or call initiation failed |
| `200`       | Call triggered successfully                                     |
| `401`       | Invalid or missing API key                                      |
| `402`       | Insufficient credits or inactive subscription                   |
| `403`       | Trigger does not belong to your organization                    |
| `404`       | Trigger, workflow, or active trigger configuration not found    |
| `422`       | Invalid request body (e.g., missing phone number)               |
| `429`       | Rate limit exceeded                                             |

## Using with Automation Platforms

### Zapier

1. Add an **HTTP / Webhooks** action in your Zap
2. Set the method to `POST`
3. Enter the endpoint URL with your agent UUID
4. Add the `X-API-Key` and `Content-Type` headers
5. Set the body to JSON with `phone_number` and optionally `initial_context`

### Make (Integromat)

1. Add an **HTTP - Make a request** module
2. Configure the URL, method, headers, and body as described above

### n8n

1. Add an **HTTP Request** node
2. Set the method to `POST`, enter the URL
3. Add authentication headers and the JSON body