API Campagne #

Una campagna raggruppa tutto ciò di cui il bot AI ha bisogno per parlare con i tuoi contatti: le sue istruzioni, i canali su cui viene eseguito, i suoi orari di attività e il suo comportamento di follow-up. L’API Campagne ti consente di elencare, creare, aggiornare, duplicare, abilitare, archiviare e ottimizzare le campagne dal tuo codice invece che dalla dashboard.

Tutti gli endpoint sottostanti sono relativi all’URL di base https://api.youraiconnector.com/v1. Ogni richiesta deve essere autenticata: consulta Accesso API e Autenticazione per sapere come ottenere e trasmettere la tua chiave API. L’accesso all’API è una funzionalità a pagamento; senza di essa, le richieste verranno rifiutate con un 403.

Attenzione: Alcuni esempi mostrano il semplice modulo di query ?apiKey=YOUR_API_KEY, altri utilizzano l’intestazione X-API-Key. Entrambi funzionano ovunque: usa quello più adatto alla tua configurazione.

Tipi di campagna #

Quando crei una campagna devi scegliere uno di questi tipi:

Le maiuscole/minuscole non contano. type, status, booking_provider, first_response_mode, bot.anthropic_model e bot.ai_speed accettano tutti qualsiasi combinazione di maiuscole e minuscole — "live", "Live" e "LIVE" sono la stessa cosa — e il valore viene memorizzato nella sua forma canonica, che è quella che viene restituita quando leggi la campagna. L’unica eccezione è la coppia di pausa: "Paused" e "paused" sono due stati genuinamente diversi, quindi un’ortografia ambigua come "PAUSED" viene rifiutata con un 400 che ti invita a sceglierne uno.

I due stati di pausa #

Entrambi interrompono la campagna: l’instradamento in entrata funziona solo mentre lo stato è esattamente Live. Dall’API, usa Paused per mettere in pausa e Live per riprendere — la coppia in minuscolo esiste per il pulsante della dashboard e viene mantenuta funzionante per esso.

Nessuno di questi è ciò che accade quando l’IA smette di rispondere all’interno di una conversazione. Si tratta di un interruttore per singolo contatto, is_bot_active sul contatto — impostato quando un umano prende il controllo, quando il contatto rinuncia o quando l’IA conclude la chat. Lo stato della campagna rimane invariato e ogni altra conversazione al suo interno continua a funzionare. Vedi mettere in pausa o riprendere l’IA per un singolo contatto.

La creazione di una campagna non determina chi risponde a un canale. Il routing è gestito dai Punti di Ingresso su un Agente AI, non dalle campagne. Ogni canale ha un Punto di Ingresso predefinito che indica l’Agente che risponde ai contatti nuovi e sconosciuti: impostalo con PUT /entry-points/channel-defaults, verifica se la scala è attiva per l’account con GET /entry-points/routing-status, cancellalo con DELETE /entry-points/channel-defaults. POST /channels/campaign scrive ancora la mappa di routing legacy delle campagne per canale, ma tale mappa non viene più consultata per il routing in entrata su nessun account; è mantenuta solo per il rollback. Non basare lo sviluppo su di essa. Vedi Instradare un canale verso una campagna per confrontare entrambe le interfacce.

Elenca campagne #

GET /campaigns

Restituisce le tue campagne, dalla più recente alla meno recente. Le campagne archiviate sono escluse a meno che non passi archived=true.

Parametri di query

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Risposta

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Quando next_cursor è null, hai raggiunto l’ultima pagina.

Ottieni una campagna #

GET /campaigns/{campaignId}

Restituisce il documento completo della campagna, inclusa la configurazione del bot live (bot), le impostazioni di follow-up, i canali abilitati e tutte le parole chiave. I timestamp vengono restituiti come millisecondi dall’epoca.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Risposta

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Crea una campagna #

POST /campaigns

Crea una nuova campagna. name e type sono obbligatori; tutto il resto è facoltativo. Puoi includere qualsiasi altro campo della campagna nella stessa richiesta — ad esempio language, ai_mode o un oggetto di configurazione bot completo — e verrà salvato con la nuova campagna. Il proprietario e l’ora di creazione vengono impostati automaticamente.

Campi della richiesta

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Aggiorna una campagna #

PUT /campaigns/{campaignId}

Aggiorna parzialmente una campagna: invia solo i campi che desideri modificare. Questo è l’unico verbo di aggiornamento generale; non esiste un PATCH /campaigns/{campaignId} (i due percorsi PATCH sono gli interruttori specifici abilita e archivia).

Quali campi puoi modificare. Tutto ciò che scrive l’editor della campagna, inclusi name, status, type, language, ai_mode, enabled_channels, le impostazioni di trigger e drip, i flag di prenotazione e follow-up, i campi di monitoraggio di Instagram/Facebook e l’intera configurazione bot. L’identità e la proprietà sono bloccate per tutta la durata della campagna: user, id e created_at vengono rifiutati, così come qualsiasi nome di campo non riconosciuto dall’endpoint. Il rifiuto avviene per richiesta, non per campo: una chiave sconosciuta restituisce un 400 e nulla in quella richiesta viene scritto.

ai_mode in una campagna supportata da un Agente riflette l’Agente. Quando una campagna riceve risposta da un Agente AI, la lettura della campagna restituisce ai_mode derivato dall’interruttore Attivo di quell’Agente — l’unico interruttore che decide effettivamente se l’AI risponde. La scrittura di ai_mode su una tale campagna viene accettata ma non modificherà ciò che viene letto in seguito; è necessario attivare o disattivare l’interruttore Attivo dell’Agente (nella dashboard o tramite l’API degli Agenti). Nelle campagne classiche senza Agente, ai_mode legge e scrive il valore memorizzato come in precedenza.

I campi del bot vengono uniti, non sovrascritti. Invia le impostazioni del bot come chiavi puntate ("bot.instructions": "...") o come oggetto nidificato ("bot": { "instructions": "..." }) — entrambi scrivono foglia per foglia, quindi i campi che tralasci mantengono i loro valori attuali. bot.instructions, bot.goal, bot.rules e bot.personality sono tutti modificabili in questo modo, così come ogni altra impostazione del bot elencata in Campi di configurazione del bot. Lo stesso vale per test_bot, frequency e follow_up_config.

Per sostituire completamente una configurazione del bot — eliminando qualsiasi campo che non invii — usa bot_replace (o test_bot_replace) con l’oggetto completo. Non puoi combinare una sostituzione e un’unione per lo stesso oggetto in una sola richiesta; ciò restituisce un 400.

Alcuni campi vengono impostati tramite una chiave dedicata anziché essere scritti direttamente: utilizzare list_id per l’elenco contatti, event_id per il tipo di evento (o event_ids, un array ordinato di ID di tipi di evento, per consentire all’AI di prenotarne diversi — il primo è quello predefinito; un array vuoto li scollega tutti) e contact_ids (un array di ID contatto) per i contatti della campagna. Le voci della knowledge base sono gestite tramite le API FAQ, non tramite questo endpoint.

I tag sostituiscono, non si uniscono. Invia tags come array completo e questo diventerà il set di tag della campagna — consulta Tag della campagna per i campi e per gli endpoint che aggiungono o modificano un singolo tag.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Elimina una campagna #

DELETE /campaigns/{campaignId}

Elimina definitivamente una campagna. Questa operazione non può essere annullata: se potessi aver bisogno della campagna in futuro, archiviala invece.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true
}

Duplica una campagna #

POST /campaigns/{campaignId}/duplicate

Crea una copia della campagna mantenendo tutte le sue impostazioni. La copia viene avviata come disabilitata e il suo nome riceve un suffisso (copy), in modo che non invii mai messaggi finché non la abiliti esplicitamente.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Risposta

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Copie duplicate all’interno di un singolo account.

Abilita o disabilita una campagna #

PATCH /campaigns/{campaignId}/enabled

Attiva o disattiva una campagna. Una campagna disabilitata smette di interagire con i contatti ma mantiene tutta la sua configurazione.

Campi della richiesta

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Archivia o ripristina una campagna #

PATCH /campaigns/{campaignId}/archived

Archivia o ripristina una campagna. Le campagne archiviate sono nascoste dall’elenco predefinito delle campagne, ma conservano tutti i loro dati e possono essere ripristinate in qualsiasi momento.

Campi della richiesta

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Aggiorna la configurazione del bot #

PUT /campaigns/{campaignId}/bot-config

Questo è il modo sicuro per modificare le singole impostazioni del bot. Ogni campo inviato viene unito alla configurazione esistente del bot, pertanto tutti i campi omessi vengono preservati. Utilizza questo metodo invece dell’endpoint di aggiornamento della campagna ogni volta che desideri modificare solo una parte del bot.

Le chiavi dei campi devono contenere solo lettere, numeri, trattini bassi e trattini.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Campi di configurazione del bot #

Tutti i campi del bot sono facoltativi. Invia solo quelli che desideri impostare. Eventuali campi aggiuntivi del bot oltre a quelli elencati qui vengono accettati e archiviati così come sono.

Imposta gli orari di attività del bot #

PUT /campaigns/{campaignId}/active-hours

Imposta la pianificazione della disponibilità del bot. Al di fuori delle finestre configurate, il bot non risponde automaticamente. Questo scrive il campo availability della configurazione del bot.

Campi della richiesta

Ogni giorno della settimana contiene una singola finestra temporale o un array di finestre. Una finestra ha un start_time e un end_time nel formato HH:MM a 24 ore.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Elenca le funzioni personalizzate di una campagna #

GET /campaigns/{campaignId}/custom-functions

Restituisce le funzioni personalizzate collegate a questa campagna, risolte in definizioni complete. Le funzioni personalizzate sono azioni HTTP esterne che il bot può richiamare durante una conversazione, ad esempio per controllare la disponibilità nel tuo negozio o creare un record nel tuo CRM.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Risposta

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Collega una funzione personalizzata a una campagna #

POST /campaigns/{campaignId}/custom-functions

Collega una funzione personalizzata esistente a questa campagna in modo che il bot possa richiamarla durante una conversazione. Il collegamento di una funzione già collegata non produce alcun effetto.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Scollega una funzione personalizzata da una campagna #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Lo scollegamento di una funzione non collegata non produce alcun effetto.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Collega una fonte della knowledge base a una campagna #

POST /campaigns/{campaignId}/kb-sources

Collega una fonte della knowledge base (creata tramite l’API FAQ) a questa campagna in modo che il bot possa utilizzarla per rispondere. Il collegamento di una fonte già collegata non produce alcun effetto.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Scollega una fonte della knowledge base da una campagna #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Lo scollegamento di una fonte non collegata non produce alcun effetto.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Collega un server MCP a una campagna #

POST /campaigns/{campaignId}/mcp-servers

Collega un server MCP a questa campagna, fornendo al bot l’accesso agli strumenti di quel server durante una conversazione. Il collegamento di un server già collegato non produce alcun effetto.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Scollega un server MCP da una campagna #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Lo scollegamento di un server non collegato non produce alcun effetto.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Libreria multimediale della campagna #

La libreria multimediale contiene immagini, video, documenti e note vocali che il bot può inviare durante una conversazione.

Elenca la libreria multimediale di una campagna #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url è un URL firmato acquisito al momento del caricamento: potrebbe essere già scaduto nel momento in cui lo leggi; la dashboard lo firma nuovamente su richiesta.

Carica un elemento multimediale #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Risposta

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Aggiorna un elemento multimediale #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Modifica solo i metadati dell’elemento: per sostituire il file stesso, elimina l’elemento e caricane uno nuovo.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Elimina un elemento multimediale #

DELETE /campaigns/{campaignId}/media-library/{itemId}

L’eliminazione di un elemento già rimosso non ha alcun effetto.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Risposta

{ "success": true, "deleted": true }

Tag della campagna #

Un tag della campagna è un’etichetta che insegni al bot ad applicare a un contatto durante una conversazione — hot-lead, not-interested, booked-a-call. Ogni tag è composto da tre parti:

I nomi dei tag devono essere univoci all’interno di una campagna. Il bot applica i tag per nome, quindi due voci che condividono lo stesso nome non hanno un vincitore definito.

Imposta tutti i tag di una campagna #

PUT /campaigns/{campaignId} con un array tags.

Questo sostituisce i tag della campagna esattamente con ciò che invii, che è la stessa cosa che fa la scheda Tag della dashboard quando salvi. Invia l’array completo ogni volta — un tag che ometti è un tag che hai eliminato. L’invio di [] li cancella tutti.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Leggi i tag con GET /campaigns/{campaignId}.

Aggiungi un tag #

POST /campaigns/{campaignId}/tags

Aggiunge un singolo tag senza dover inviare nuovamente gli altri. Usalo quando stai aggiungendo elementi a un set che non hai creato in questa richiesta.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Pubblicare esattamente lo stesso tag due volte non produce alcun effetto la seconda volta. Pubblicare lo stesso tag_id con un nome o una descrizione diversi aggiunge una seconda voce invece di modificare la prima — usa l’endpoint sottostante per modificare sul posto.

Aggiorna o rimuovi un tag #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Questi indirizzano una singola voce tramite il suo tag_id, quindi funzionano solo sui tag creati con uno di essi. Se un tag non ha un tag_id, modificalo con l’intero array PUT /campaigns/{campaignId} qui sopra.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Un tagId che non è presente nella campagna restituisce 404 con "Tag not found in campaign tags".

Attivare/disattivare i canali di una campagna #

POST /campaigns/{campaignId}/channels

Aggiunge o rimuove canali dall’array enabled_channels della campagna senza dover inviare nuovamente l’intero array: è più sicuro di PUT /campaigns/{campaignId} quando qualcos’altro potrebbe modificare la campagna contemporaneamente.

Invia un singolo comando di attivazione/disattivazione o un batch, ma non entrambi nella stessa richiesta:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Canali validi: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Questo modifica solo i canali pubblicizzati dalla campagna, non decide chi risponde a un canale. Per questo, vedere Tipi di campagna sopra e Instradare una campagna verso i canali in entrata sotto.

Comment-to-DM (Instagram e Facebook) #

Comment-to-DM trasforma un commento su uno dei tuoi post in una conversazione privata: qualcuno commenta, il bot invia un DM e la campagna gestisce la conversazione da quel punto in poi. È configurato interamente tramite l’oggetto campagna, quindi non c’è nulla che riguardi solo l’interfaccia utente.

Connetti prima la Pagina Facebook — vedi Connessione canale. Quindi imposta i campi sottostanti con PUT /campaigns/{campaignId}.

La campagna deve essere Live. Il monitoraggio dei commenti rileva solo le campagne il cui status è Live (qualsiasi combinazione di maiuscole/minuscole — vedi Tipi di campagna). Qualsiasi altro stato la disabilita silenziosamente, e uno inventato come "Active" viene ora rifiutato con un 400 invece di essere memorizzato. Gli stati validi includono Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent e Failed.

Campi

Cancellazione di un campo

Questi campi vengono rimossi anziché impostati su null quando invii null, quindi il bot torna alle sue impostazioni predefinite: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Una chiave sconosciuta rifiuta l’intera richiesta. PUT /campaigns/{campaignId} convalida l’intero corpo rispetto a una lista consentita. Una chiave non riconosciuta restituisce 400 per l’intera richiesta: non viene ignorata silenziosamente e nessuno degli altri campi in quel corpo viene scritto.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

La risposta visibile lasciata sul commento richiede la funzionalità di risposta ai commenti nel tuo piano. Senza di essa, il DM viene comunque inviato e la risposta pubblica viene saltata.

Ottimizzare una campagna con l’IA #

POST /campaigns/{campaignId}/optimize

Esegue la stessa riscrittura AI dei flussi di feedback “Ottimizza” e “pollice verso” della dashboard: prende il tuo feedback, riscrive le istruzioni del bot e prepara il risultato come una nuova revisione di bozza da revisionare.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Risposta (202 — la riscrittura viene eseguita in background)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Esegui il polling di GET /campaigns/{campaignId} e osserva test_bot.status: passa immediatamente a "Optimizing", poi torna a "Draft" una volta che la riscrittura arriva in test_bot. Da lì si comporta come qualsiasi bozza della dashboard: revisionala, quindi pubblicala nella dashboard per renderla attiva. Un 409 significa che un’ottimizzazione è già in esecuzione per questa campagna.

L’ottimizzazione consuma crediti, esattamente come qualsiasi altra operazione AI sul tuo account.

Assegna un contatto a una campagna #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Inserisce un contatto esistente in una campagna e, se richiesto, invia immediatamente il messaggio di apertura della campagna. Questo è il modo per inviare il modello WhatsApp approvato di una campagna a un contatto: il modello con cui una campagna è stata approvata appartiene a quella campagna, quindi non appare nella libreria Templates API e non può essere inviato tramite /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Risposta

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Crediti: L’invio del messaggio di apertura in una campagna WhatsApp viene addebitato come qualsiasi invio di modello, con un prezzo basato sul paese del destinatario e sulla categoria del modello. Su altri canali, il messaggio di apertura è un normale messaggio in uscita.

Instrada una campagna verso i canali in entrata #

Questi endpoint gestiscono quale campagna risponde ai contatti nuovi e sconosciuti su un canale. Preferisci i Punti di Ingresso per le nuove integrazioni (vedi la nota sotto Tipi di campagna): questi rimangono utili per lavorare con campagne che utilizzano il vecchio metodo di instradamento e per risolvere un conflitto di proprietà del canale tra due campagne in entrata.

Assegna una campagna ai canali in entrata #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Risposta

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels elenca solo i canali che sono stati effettivamente instradati verso questa campagna; failed elenca quelli che non lo sono stati. Se ogni canale richiesto fallisce, la richiesta stessa fallisce.

Cancella l’instradamento in entrata di una campagna #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Risposta

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Riattiva una campagna dormiente #

POST /campaigns/{campaignId}/reactivate

Riporta in vita una campagna da Ended, Completed, Paused o Draft e ne reclama i canali. Funziona solo su campagne Incoming from Unknown Contacts o Combined: una campagna già Live viene considerata un successo e non richiede alcuna azione.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Un canale già reclamato dall’agente di una campagna diversa viene visualizzato in channelsBlockedByConflict invece di causare il fallimento dell’intera chiamata; utilizza interrompi una campagna in entrata in conflitto qui sotto per liberarlo prima, se desideri che questa campagna ne prenda il controllo. Viene restituito un 400 per un tipo di campagna che non supporta la riattivazione o per uno stato che non rientra tra quelli dormienti sopra indicati.

Interrompi una campagna in entrata in conflitto #

POST /campaigns/{campaignId}/stop-incoming

Libera i canali di questa campagna da qualsiasi ALTRA campagna li stia attualmente occupando, in modo che questa campagna possa reclamarli successivamente. Questa è la versione REST di ciò che la dashboard esegue automaticamente quando lanci una campagna in entrata su un canale che qualcun altro sta già gestendo.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels restituisce un valore vuoto quando questa campagna possiede già tutti i canali che pubblicizza: non c’è nulla di cui prendere il controllo.

Stime dei costi #

Stima il costo del lancio di una campagna prima di inviarla.

Stima dei costi dei modelli WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode è "credits" sulla linea WhatsApp gestita. Su una linea in cui Meta fattura direttamente al tuo account WhatsApp Business, costPerContact, subtotal e totalTemplateCost restituiscono null — mai 0, che verrebbe interpretato come gratuito — poiché non c’è alcun importo di credito da segnalare.

Stima dei costi SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

Gli SMS vengono sempre inviati tramite il tuo account Twilio (vedi provider SMS), quindi questo viene sempre fatturato direttamente da Twilio: estimatedCostUsd è una stima di quella fattura Twilio, non un addebito di credito.

Controlli dei limiti #

Controlla un limite prima di avviare, invece di scoprirlo a causa di un invio non riuscito.

Controlli a livello di campagna #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — se l’avvio o la pianificazione di questa campagna supererebbe il limite di messaggistica dei crediti AI del tuo account.

GET /campaigns/{campaignId}/limits/messaging — se supererebbe il limite di messaggistica giornaliero del tuo account.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Risposta (limite non superato)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Viene restituito un 400 quando il limite viene superato, con il motivo in error.

Controlli a livello di account #

GET /campaigns/limits/campaigns — se hai raggiunto il limite mensile di creazione campagne del tuo abbonamento.

GET /campaigns/limits/contacts — se hai raggiunto il limite di contatti del tuo abbonamento.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Totali statistiche campagna #

GET /campaigns/stats/totals

Totali inviati e risposti per ogni campagna E ogni agente AI sul tuo account, su una finestra temporale mobile — gli stessi numeri che la pagina dell’elenco campagne mostra accanto a ogni riga, in una sola chiamata invece di una richiesta per ogni campagna.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent è un riepilogo a sé stante, non una somma di byCampaign — il traffico di un account nativo AI-Agent può non avere alcuna campagna associata, quindi altrimenti risulterebbe invisibile qui.

Testare una campagna nel playground #

Il playground ti consente di intrattenere una conversazione con il bot di una campagna senza toccare un canale reale o un contatto reale. È la stessa sandbox del pannello di prova della dashboard ed è completamente disponibile tramite API.

Il flusso è: crea un contatto di test nascosto, invia un messaggio, quindi interroga la campagna per la risposta del bot. Le risposte vengono generate in modo asincrono, quindi arrivano in test_messages sulla campagna anziché nel corpo della risposta.

Il Playground utilizza i crediti di costo dell’API. Una conversazione di prova avviata con una chiave API viene addebitata alla normale tariffa per messaggio AI, la stessa di una risposta reale, e appare nella cronologia di utilizzo come una voce regolare. I test dalla dashboard rimangono gratuiti. La differenza è intenzionale: un test esegue lo stesso lavoro di intelligenza artificiale di uno reale, quindi un playground API senza limiti sarebbe un modo per eseguire un numero illimitato di operazioni AI a spese di qualcun altro.

Passaggio 1 - Crea il contatto di test #

POST /campaigns/{campaignId}/try-out/contact

Crea il contatto di test nascosto e lo collega alla campagna. Tutti i campi del corpo sono facoltativi; tutto ciò che viene omesso ricade su un’identità di esempio predefinita (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Risposta

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Passaggio 2 - Registra il messaggio in arrivo #

POST /campaigns/{campaignId}/try-out/messages

Aggiunge messaggi al thread di test. Invia qui prima il messaggio del visitatore, in modo che appaia nella cronologia della conversazione letta dal bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Passaggio 3 - Chiedi al bot di rispondere #

POST /campaigns/{campaignId}/try-out/test-message

Invia il messaggio alla pipeline AI. Questa è la chiamata che produce effettivamente una risposta del bot.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Risposta

{
  "success": true,
  "data": "Published"
}

"Published" significa che il messaggio è stato inviato alla pipeline AI. "Ignored" significa che un messaggio di test più recente ha sostituito questo: il playground raggruppa una raffica rapida in un’unica risposta, circa quattro secondi dopo l’ultimo messaggio, nello stesso modo in cui una conversazione reale attende che qualcuno finisca di scrivere. A causa di questa finestra di raggruppamento, questa chiamata impiega alcuni secondi per restituire un risultato.

Passaggio 4 - Leggi la risposta #

GET /campaigns/{campaignId}

La risposta del bot viene aggiunta all’array test_messages della campagna. Esegui il polling della campagna finché non appare una nuova voce outbound.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Reimposta il playground #

POST /campaigns/{campaignId}/try-out/reset

Cancella l’intera sandbox: elimina il contatto di test, svuota test_messages e rilascia i blocchi di risposta del bot. Da utilizzare tra un’esecuzione di test e l’altra.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Altri endpoint del playground #

Errori dell’API Campagne #

Gli endpoint delle campagne restituiscono il busta di errore standard:

{
  "success": false,
  "error": "Campaign not found"
}

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

Correlati #

• Indirizza un canale a una campagna — punta Instagram, WhatsApp o qualsiasi altro canale verso l’Agente AI che dovrebbe rispondere, utilizzando i Punti di Ingresso.
• Genera modelli di follow-up con l’AI — avvia un processo in background che scrive i modelli di follow-up WhatsApp di una campagna.
• API FAQ — gestisci le voci di domande e risposte utilizzate dalle tue campagne.
• Accesso API — genera la tua chiave API.
• Autenticazione — tutti i modi per trasmettere la tua chiave.