iCallAgent

https://docs.icallagent.com/
Admin
iCallAgent is a platform for building, testing, and deploying conversational AI voice agents with...
Tokens:56,919
Snippets:581
Trust Score:3.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example scenario for Send Contact

Source: https://docs.icallagent.com/integrations/make

A sample Make.com scenario configuration showing how to map Google Forms responses to the iCallAgent Send Contact module.

```text
Google Forms (new response)
  → iCallAgent: Send Contact
       phone:    {{form.phone}}
       name:     {{form.name}}
       campaign: "Inbound Leads"
```

--------------------------------

### JavaScript - POST /contacts/ - Send contact

Source: https://docs.icallagent.com/api-reference/contacts/create

Fetch API example to queue a call. Body is prepared with JSON.stringify.

```JavaScript
fetch('https://api.icallagent.com/api/public/v1/contacts/', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+15550101999',
    campaign_id: 13,
    name: 'Jane Doe',
    company: 'Acme',
    consent_status: 'implied',
    external_id: 'docs-demo-001'
  })
})
```

--------------------------------

### Python - POST /contacts/ - Send contact

Source: https://docs.icallagent.com/api-reference/contacts/create

Python requests example to queue a call. Uses the same payload and headers as cURL.

```Python
requests.post(
    "https://api.icallagent.com/api/public/v1/contacts/",
    headers={
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    json={
      "phone": "+15550101999",
      "campaign_id": 13,
      "name": "Jane Doe",
      "company": "Acme",
      "consent_status": "implied",
      "external_id": "docs-demo-001"
    }
)
```

--------------------------------

### Better greeting example

Source: https://docs.icallagent.com/guides/anatomy

A specific greeting that names the business and agent and offers two paths, leading to in-scope answers. Shown as the 'Better' example in the greeting comparison.

```text
Thanks for calling Northwind Plumbing, this is Sam. Are you calling about
a booking or an existing job?
```

--------------------------------

### GET /agents/

Source: https://docs.icallagent.com/api-reference/agents/list

Lists all agents that are currently in the Live state. Paused agents are excluded because they have no working phone/telephony configuration to place calls with.

```APIDOC
## GET /agents/

### Description
Lists all agents that are currently in the `Live` state. Paused agents are excluded because they have no working phone/telephony configuration to place calls with.

### Method
GET

### Endpoint
/agents/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max results to return. Default 100, clamped to [1, 200] — out-of-range values are silently clamped, not rejected.
- **offset** (integer) - Optional - Number of results to skip. Default 0. Negative values are clamped to 0.

### Authorizations
- **ApiKeyAuth** (HTTP bearer) - Personal API key. Code samples use `Authorization: Bearer <token>` — replace `<token>` with your key from Settings → API Keys (include the word `Bearer`).
- **oauth2** (OAuth2 authorization code flow) - OAuth2 access token from the consent flow third-party apps go through (see /oauth/authorize/). Interchangeable with a personal API key on every operation below — both are sent as a Bearer token in the same header.
  - Authorization URL: `/oauth/authorize/`
  - Token URL: `/oauth/token/`
  - Scopes:
    - `campaigns:read` - List your call campaigns
    - `campaigns:write` - Create new call campaigns
    - `contacts:write` - Create contacts and queue calls into your campaigns

### Response
#### Success Response (200)
- **results** (array) - List of agents.
  - **id** (integer) - Agent ID.
  - **name** (string) - Agent name.

#### Response Example
```json
{
  "results": [
    {
      "id": 7,
      "name": "Support Agent"
    }
  ]
}
```

### Notes
- Only `Live` agents are returned — a `Paused` agent has no working phone/telephony config to place calls with, so it's excluded rather than returned with a status field to filter on client-side.
- This endpoint returns just `id` and `name` for **Live** agents so dropdowns (and Make modules) stay simple. Paused agents are omitted. Creating or editing agents is done in the dashboard for now.
```

--------------------------------

### POST /campaigns/

Source: https://docs.icallagent.com/api-reference/campaigns/create

Creates a new campaign with specified configuration including name, widget, phone number, scheduling, and retry settings.

```APIDOC
## POST /campaigns/

### Description
Creates a new campaign with specified configuration including name, widget, phone number, scheduling, and retry settings.

### Method
POST

### Endpoint
/campaigns/

### Parameters
#### Request Body
- **name** (string) - Required - Name of the campaign
- **widget_id** (integer) - Required - ID of the associated widget
- **status** (string) - Required - Status of the campaign (e.g., draft)
- **phone_number_id** (integer) - Required - ID of the phone number to use
- **max_concurrent_calls** (integer) - Required - Maximum number of concurrent calls
- **retry_attempts** (integer) - Optional - Number of retry attempts
- **retry_delay_minutes** (integer) - Optional - Delay between retries in minutes
- **timezone** (string) - Optional - IANA timezone for scheduling
- **start_time** (string) - Optional - Start time in HH:MM format
- **end_time** (string) - Optional - End time in HH:MM format
- **weekdays** (array of strings) - Optional - Days of the week for scheduling

### Request Example
{
  "name": "Q3 Renewals",
  "widget_id": 2,
  "status": "draft",
  "phone_number_id": 1,
  "max_concurrent_calls": 2,
  "retry_attempts": 1,
  "retry_delay_minutes": 30,
  "timezone": "America/New_York",
  "start_time": "09:00",
  "end_time": "17:00",
  "weekdays": ["mon", "tue", "wed", "thu", "fri"]
}

### Response
#### Success Response (201)
- **campaign_id** (integer) - ID of the created campaign
- **name** (string) - Name of the campaign
- **status** (string) - Status of the campaign
- **max_concurrent_calls** (integer) - Maximum concurrent calls

#### Response Example
{
  "campaign_id": 12,
  "name": "Q3 Renewals",
  "status": "draft",
  "max_concurrent_calls": 3
}

#### Error Responses
- **400** - Bad Request
- **404** - Not Found

### Authentication
- **ApiKeyAuth** - API key authentication required

### Server
https://api.icallagent.com/api/public/v1
```

--------------------------------

### Weak greeting example

Source: https://docs.icallagent.com/guides/anatomy

A vague opening line that leads to vague callers. Shown as the 'Weak' example in the greeting comparison.

```text
Hello, how can I help you?
```

--------------------------------

### GET /agents/

Source: https://docs.icallagent.com/api-reference/pagination

Retrieves a paginated list of agents. Supports offset/limit pagination with clamping of out-of-range values.

```APIDOC
## GET /agents/

### Description
Retrieves a paginated list of agents. Supports offset/limit pagination with clamping of out-of-range values.

### Method
GET

### Endpoint
/agents/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 100, Max: 200. Number of items to return. Values above 200 are clamped to 200.
- **offset** (integer) - Optional - Default: 0. Number of items to skip before starting to collect the result set.

### Request Example
```bash
curl "https://api.icallagent.com/api/public/v1/agents/?limit=50&offset=100" \
  -H "Authorization: Bearer ic_live_<your key>"
```

### Response
#### Success Response (200)
- **items** (array) - List of agent objects.
- **limit** (integer) - The limit used for the request.
- **offset** (integer) - The offset used for the request.
- **total** (integer) - Total number of agents matching the filters.

#### Response Example
```json
{
  "items": [],
  "limit": 50,
  "offset": 100,
  "total": 0
}
```
```

--------------------------------

### List agents with Java (OkHttp with JSON)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses OkHttp with JSON parsing to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Java
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.icallagent.com/api/public/v1/agents/")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();
String json = response.body().string();
JSONObject data = new JSONObject(json);
```

--------------------------------

### List agents with Java (OkHttp)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses OkHttp to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Java
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.icallagent.com/api/public/v1/agents/")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();
```

--------------------------------

### GET /campaigns/

Source: https://docs.icallagent.com/api-reference/pagination

Retrieves a paginated list of campaigns. Supports offset/limit pagination with clamping of out-of-range values.

```APIDOC
## GET /campaigns/

### Description
Retrieves a paginated list of campaigns. Supports offset/limit pagination with clamping of out-of-range values.

### Method
GET

### Endpoint
/campaigns/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 100, Max: 200. Number of items to return. Values above 200 are clamped to 200.
- **offset** (integer) - Optional - Default: 0. Number of items to skip before starting to collect the result set.

### Request Example
```bash
curl "https://api.icallagent.com/api/public/v1/campaigns/?limit=50&offset=100" \
  -H "Authorization: Bearer ic_live_<your key>"
```

### Response
#### Success Response (200)
- **items** (array) - List of campaign objects.
- **limit** (integer) - The limit used for the request.
- **offset** (integer) - The offset used for the request.
- **total** (integer) - Total number of campaigns matching the filters.

#### Response Example
```json
{
  "items": [],
  "limit": 50,
  "offset": 100,
  "total": 0
}
```
```

--------------------------------

### GET /contacts/

Source: https://docs.icallagent.com/api-reference/contacts/search

Search contacts endpoint that returns all matching outbound contacts based on query parameters.

```APIDOC
## GET /contacts/

### Description
Powers Make's "Search Contacts" lookup module. Only outbound-usage contacts are searched. Deliberately returns every match rather than guessing a single best one — a name is often ambiguous (multiple "Stephan"s), so the caller is expected to disambiguate when more than one result comes back.

### Method
GET

### Endpoint
/contacts/

### Authorizations
- **ApiKeyAuth** (HTTP bearer) - Personal API key. Code samples use `Authorization: Bearer <token>` — replace `<token>` with your key from Settings → API Keys (include the word `Bearer`).
- **oauth2** - OAuth2 access token from the consent flow third-party apps go through (see /oauth/authorize/). Interchangeable with a personal API key on every operation below — both are sent as a Bearer token in the same header.
  - Flow: authorizationCode
  - Authorization URL: `/oauth/authorize/`
  - Token URL: `/oauth/token/`
  - Scopes:
    - `campaigns:read` - List your call campaigns
    - `campaigns:write` - Create new call campaigns
    - `contacts:write` - Create contacts and queue calls into your campaigns

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max results to return. Default 100, clamped to [1, 200] — out-of-range values are silently clamped, not rejected.
- **offset** (integer) - Optional - Number of results to skip. Default 0. Negative values are clamped to 0.
- **q** (string) - Optional - Case-insensitive substring match against name OR phone. Omit to list all outbound contacts.

### Responses
#### Success Response (200)
- Content-Type: application/json
- Schema: OKJSON

#### Response Example
```json
{
  "results": [
    {
      "id": 44,
      "name": "Stephan Kim",
      "phone": "+15557890123",
      "company": "Acme Co",
      "notes": ""
    }
  ]
}
```

#### Error Response (400)
- Content-Type: application/json
- Schema: (not specified in source)

```

--------------------------------

### List agents with Go (http.Client with JSON)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses http.Client with JSON decoding to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	url := "https://api.icallagent.com/api/public/v1/agents/"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer <token>")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println(data)
}
```

--------------------------------

### POST /campaigns/

Source: https://docs.icallagent.com/api-reference/campaigns/create

Creates a new call campaign. Requires name and widget_id; returns 400 if missing, 404 if widget_id or phone_number_id do not belong to the workspace.

```APIDOC
## POST /campaigns/

### Description
Creates a new call campaign. Requires `name` and `widget_id`; otherwise returns a 400 error. If `widget_id` or `phone_number_id` do not belong to your workspace, a 404 is returned.

### Method
POST

### Endpoint
/campaigns/

### Parameters
#### Request Body
- **name** (string) - Required - The name of the campaign.
- **widget_id** (string) - Required - The ID of the widget associated with the campaign.
- **phone_number_id** (string) - Optional - The ID of the phone number to use. If provided, it must belong to your workspace.
- **max_concurrent_calls** (integer) - Optional - Maximum number of concurrent calls. Silently clamped to your workspace's concurrency entitlement; the applied value is returned in the response.
- **status** (string) - Optional - Campaign status. Invalid values silently fall back to `draft`.
- **start_date** (string) - Optional - Start date of the campaign. Unparseable values are silently ignored.
- **end_date** (string) - Optional - End date of the campaign. Unparseable values are silently ignored.
- **start_time** (string) - Optional - Start time of the campaign. Unparseable values are silently ignored.
- **end_time** (string) - Optional - End time of the campaign. Unparseable values are silently ignored.

### Request Example
{
  "name": "My Campaign",
  "widget_id": "widget_123",
  "phone_number_id": "phone_456",
  "max_concurrent_calls": 10,
  "status": "active",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "start_time": "09:00",
  "end_time": "17:00"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created campaign.
- **name** (string) - The name of the campaign.
- **widget_id** (string) - The widget ID associated with the campaign.
- **phone_number_id** (string) - The phone number ID used for the campaign.
- **max_concurrent_calls** (integer) - The actual maximum concurrent calls applied (may be lower than requested due to clamping).
- **status** (string) - The campaign status (e.g., `draft`, `active`).
- **start_date** (string) - The start date of the campaign.
- **end_date** (string) - The end date of the campaign.
- **start_time** (string) - The start time of the campaign.
- **end_time** (string) - The end time of the campaign.

#### Response Example
{
  "id": "campaign_789",
  "name": "My Campaign",
  "widget_id": "widget_123",
  "phone_number_id": "phone_456",
  "max_concurrent_calls": 5,
  "status": "active",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "start_time": "09:00",
  "end_time": "17:00"
}

### Error Handling
- **400 Bad Request** - Returned when `name` or `widget_id` is missing.
- **404 Not Found** - Returned when `widget_id` or `phone_number_id` does not belong to your workspace.

### Authorizations
- **ApiKeyAuth** - Personal API key. Use `Authorization: Bearer <token>` header.
- **oauth2** - OAuth2 access token from the consent flow. Scopes: `campaigns:read`, `campaigns:write`, `contacts:write`.
```

--------------------------------

### GET /phone-numbers/

Source: https://docs.icallagent.com/api-reference/pagination

Retrieves a paginated list of phone numbers. Supports offset/limit pagination with clamping of out-of-range values.

```APIDOC
## GET /phone-numbers/

### Description
Retrieves a paginated list of phone numbers. Supports offset/limit pagination with clamping of out-of-range values.

### Method
GET

### Endpoint
/phone-numbers/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default: 100, Max: 200. Number of items to return. Values above 200 are clamped to 200.
- **offset** (integer) - Optional - Default: 0. Number of items to skip before starting to collect the result set.

### Request Example
```bash
curl "https://api.icallagent.com/api/public/v1/phone-numbers/?limit=50&offset=100" \
  -H "Authorization: Bearer ic_live_<your key>"
```

### Response
#### Success Response (200)
- **items** (array) - List of phone number objects.
- **limit** (integer) - The limit used for the request.
- **offset** (integer) - The offset used for the request.
- **total** (integer) - Total number of phone numbers matching the filters.

#### Response Example
```json
{
  "items": [],
  "limit": 50,
  "offset": 100,
  "total": 0
}
```
```

--------------------------------

### Define call variables with {{placeholders}}

Source: https://docs.icallagent.com/guides/system-prompt

Use double-brace placeholders for anything that changes per call. Define the placeholders in the prompt editor and provide values when the call is placed.

```text
You are calling {{customer_name}} about their appointment on
{{appointment_date}}.
```

--------------------------------

### List agents with Kotlin (OkHttp)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses OkHttp to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Kotlin
val client = OkHttpClient()

val request = Request.Builder()
    .url("https://api.icallagent.com/api/public/v1/agents/")
    .get()
    .addHeader("Authorization", "Bearer <token>")
    .build()

client.newCall(request).execute().use { response ->
    val data = response.body?.string()
}
```

--------------------------------

### Create a campaign via API - curl POST /campaigns

Source: https://docs.icallagent.com/guides/campaigns

Creates a campaign with name, widget_id, and status set to draft. Campaign creation is separate from adding contacts.

```bash
curl -X POST https://api.icallagent.com/api/public/v1/campaigns/ \
  -H "Authorization: Bearer ic_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Renewals",
    "widget_id": "7",
    "status": "draft"
  }'
```

--------------------------------

### cURL Request with Personal API Key

Source: https://docs.icallagent.com/api-reference/authentication

Example of using a personal API key with a cURL request to the campaigns endpoint.

```bash
curl -X POST https://api.icallagent.com/api/public/v1/campaigns/ \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'
```

--------------------------------

### List agents with Go (net/http)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses net/http to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	url := "https://api.icallagent.com/api/public/v1/agents/"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer <token>")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := ioutil.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

--------------------------------

### GET /agents/

Source: https://docs.icallagent.com/api-reference

Lists live agents with their id and name. This endpoint is part of the Agents resource and is used to retrieve the available agents for the workspace.

```APIDOC
## GET /agents/

### Description
Lists live agents with their id and name.

### Method
GET

### Endpoint
`/agents/`

### Parameters
None documented.

### Request Example
```bash
curl https://api.icallagent.com/api/public/v1/agents/ \
  -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **results** (array) - List of agents.
  - **id** (integer) - Agent ID.
  - **name** (string) - Agent name.

#### Response Example
```json
{ "results": [ { "id": 7, "name": "Support Agent" } ] }
```
```

--------------------------------

### List agents with Go

Source: https://docs.icallagent.com/api-reference/agents/list

Uses the Go standard library to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.icallagent.com/api/public/v1/agents/"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer <token>")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

--------------------------------

### GET /api/mcp/sse

Source: https://docs.icallagent.com/mcp

Opens the SSE stream for MCP communication. Authentication and widget resolution happen here. This endpoint is used to establish a connection for an agent session.

```APIDOC
## GET /api/mcp/sse

### Description
Opens the SSE stream for MCP communication. Authentication and widget resolution happen here.

### Method
GET

### Endpoint
/api/mcp/sse

### Parameters
#### Query Parameters
- **widget_id** (string) - Required - The agent whose tools this session should expose.
- **call_id** (string) - Optional - The active call's channel id, if this session is tied to a live call.
- **token** (string) - Required - The runtime secret issued to the agent process. It can also be supplied as a header rather than a query parameter.

### Request Example
GET /api/mcp/sse?widget_id=<widget_id>&call_id=<ari_channel_id>&token=<secret>

### Response
#### Success Response (200)
- **body** (string) - The SSE stream for MCP communication.

#### Response Example
(SSE stream)

```

--------------------------------

### List agents with PHP (file_get_contents)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses file_get_contents with stream context to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```PHP
$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "Authorization: Bearer <token>\r\n"
    ]
]);

$response = file_get_contents('https://api.icallagent.com/api/public/v1/agents/', false, $context);
$data = json_decode($response, true);
```

--------------------------------

### GET /phone-numbers/

Source: https://docs.icallagent.com/api-reference/phone-numbers/list

Lists phone numbers with is_active=True. Supports pagination with limit and offset query parameters. Requires authentication via Bearer token.

```APIDOC
## GET /phone-numbers/

### Description
Retrieves a list of phone numbers where `is_active=True`.

### Method
GET

### Endpoint
`/phone-numbers/`

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max results to return. Default 100, clamped to [1, 200]. Out-of-range values are silently clamped.
- **offset** (integer) - Optional - Number of results to skip. Default 0. Negative values are clamped to 0.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **results** (array) - List of phone numbers.
  - **id** (integer) - Unique identifier of the phone number.
  - **phone_number** (string) - The phone number in E.164 format.
  - **friendly_name** (string) - A human-readable name for the phone number.

#### Response Example
```json
{
  "results": [
    {
      "id": 3,
      "phone_number": "+15551234567",
      "friendly_name": "Main line"
    }
  ]
}
```

### Error Handling
- **400** - Bad request (e.g., invalid query parameters).

### Authentication
Requires a Bearer token. Use either a personal API key (`Authorization: Bearer <token>`) or an OAuth2 access token obtained from `/oauth/authorize/`.

### Code Samples
#### cURL
```bash
curl https://api.icallagent.com/api/public/v1/phone-numbers/ \
  -H 'Authorization: Bearer <token>'
```

#### Python
```python
import requests

response = requests.get(
    "https://api.icallagent.com/api/public/v1/phone-numbers/",
    headers={"Authorization": "Bearer <token>"}
)
```

#### JavaScript
```javascript
fetch('https://api.icallagent.com/api/public/v1/phone-numbers/', {
  headers: {
    Authorization: 'Bearer <token>'
  }
})
```
```

--------------------------------

### List agents with C++ (libcurl)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses libcurl to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```C++
#include <curl/curl.h>
#include <string>

int main() {
    CURL *curl = curl_easy_init();
    if (curl) {
        curl_easy_setopt(curl, CURLOPT_URL, "https://api.icallagent.com/api/public/v1/agents/");
        struct curl_slist *headers = NULL;
        headers = curl_slist_append(headers, "Authorization: Bearer <token>");
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_perform(curl);
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
    return 0;
}
```

--------------------------------

### GET /campaigns/

Source: https://docs.icallagent.com/api-reference/campaigns/list

Lists call campaigns. Supports status filtering and pagination. Returns a JSON object with a results array containing campaign id, name, and status.

```APIDOC
## GET /campaigns/

### Description
Retrieves a list of call campaigns. Supports filtering by status and pagination.

### Method
GET

### Endpoint
/campaigns/

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Max results to return. Default 100, clamped to [1, 200].
- **offset** (integer) - Optional - Number of results to skip. Default 0. Negative values are clamped to 0.
- **status** (string) - Optional - Single status or comma-separated list. One of: draft, active, paused, completed. Unrecognized values are dropped.

### Authorizations
- **ApiKeyAuth** (HTTP bearer) - Personal API key. Use `Authorization: Bearer <token>`.
- **oauth2** - OAuth2 access token from consent flow. Scopes: `campaigns:read`, `campaigns:write`, `contacts:write`.

### Request Example
```
curl https://api.icallagent.com/api/public/v1/campaigns/ \
  -H 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **results** (array) - List of campaigns.
  - **id** (integer) - Campaign ID.
  - **name** (string) - Campaign name.
  - **status** (string) - Campaign status.

#### Response Example
```json
{
  "results": [
    {
      "id": 12,
      "name": "Q3 Renewals",
      "status": "active"
    }
  ]
}
```

### Error Responses
- **400** - Bad request (e.g., invalid parameters).
```

--------------------------------

### List agents with cURL

Source: https://docs.icallagent.com/api-reference/agents/list

Sends a GET request to /agents/ with a Bearer token. Replace <token> with your personal API key from Settings → API Keys, including the word Bearer.

```Shell
curl -X GET "https://api.icallagent.com/api/public/v1/agents/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List agents with Node.js (axios with async/await)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses axios with async/await to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Node.js
const axios = require('axios');

async function getAgents() {
  const response = await axios.get('https://api.icallagent.com/api/public/v1/agents/', {
    headers: {
      'Authorization': 'Bearer <token>'
    }
  });
  return response.data;
}
```

--------------------------------

### Python: Create campaign

Source: https://docs.icallagent.com/api-reference/campaigns/create

Uses the requests library to POST the campaign payload to /campaigns/. Requires an API key in the Authorization header.

```python
requests.post(
    "https://api.icallagent.com/api/public/v1/campaigns/",
    headers={
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    json={
      "name": "Q3 Renewals",
      "widget_id": 2,
      "status": "draft",
      "phone_number_id": 1,
      "max_concurrent_calls": 2,
      "retry_attempts": 1,
      "retry_delay_minutes": 30,
      "timezone": "America/New_York",
      "start_time": "09:00",
      "end_time": "17:00",
      "weekdays": [
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ]
    }
)
```

--------------------------------

### System prompt for Sam, Northwind Plumbing phone assistant

Source: https://docs.icallagent.com/guides/system-prompt

A complete, working system prompt for a phone assistant. It defines the agent's identity, allowed tasks, prohibited actions, speaking style, and call-ending behavior. Use as a starting template and extend only with what real calls prove necessary.

```text
IDENTITY
You are Sam, the phone assistant for Northwind Plumbing.
You are speaking with a customer on the phone.

WHAT YOU DO
- Book plumbing appointments
- Answer questions about pricing, service areas and opening hours
- Take a message when a human needs to call back

WHAT YOU DON'T DO
- Give plumbing advice or diagnose problems over the phone
- Quote exact prices for work not on the price list
- Discuss anything unrelated to Northwind Plumbing
If asked, say plainly that you can't help with that, then offer
to take a message.

HOW YOU SPEAK
- One or two sentences per reply. This is a phone call.
- No lists, no formatting. Everything you say is read aloud.
- Confirm dates, times, addresses and phone numbers by repeating
  them back before acting.

ENDING THE CALL
When the caller's need is met and they have nothing else, say a
short goodbye and end the call. Don't wait to be dismissed.
```

--------------------------------

### List agents with Java (java.net.http)

Source: https://docs.icallagent.com/api-reference/agents/list

Uses java.net.http to call /agents/ with a Bearer token. Replace <token> with your personal API key.

```Java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.icallagent.com/api/public/v1/agents/"))
    .header("Authorization", "Bearer <token>")
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
String data = response.body();
```
Tokens:
Raw