Campagne

Crea campagne di chiamate in uscita con più contatti, numeri alternativi per contatto e rotazione opzionale del caller ID tra i tentativi.

Creare una campagna

POST /v1/campaigns

Crea una campagna in stato DRAFT (o SCHEDULED se imposti scheduledAt). Con startImmediately: true la avvii nella stessa richiesta.

Scope richiesto: campaigns:write

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome della campagna
agentId	string	Sì	ID agente AI
fromNumber	string	Sì	Caller ID principale (E.164, deve appartenere alla tua org)
contacts	array	Sì	Righe contatto (vedi sotto)
description	string	No	Descrizione opzionale
fromNumberAttempts	string[]	No	Numeri in uscita per tentativo (E.164). Usato quando maxRetries > 0
fromNumberStrategy	string	No	rolling, clamp o custom — scelta di fromNumberAttempts se ci sono meno numeri dei tentativi
contactAttemptStrategy	string	No	rolling, clamp o custom — scelta di contact_attempts se ci sono meno alternativi dei tentativi
variableMapping	object	No	Mappa campi contatto → variabili prompt agente
maxRetries	integer	No	Retry per chiamata fallita (0–5, default 0)
retryDelayMinutes	integer	No	Minuti tra i retry (min 5 se maxRetries > 0, default 30)
callingDays	integer[]	No	Giorni consentiti (0 = domenica … 6 = sabato)
callingStartTime	string	No	Inizio finestra (HH:MM)
callingEndTime	string	No	Fine finestra (HH:MM)
timezone	string	No	Timezone IANA (default Europe/Rome)
maxConcurrency	integer	No	Chiamate simultanee massime
keepFreeForInbound	integer	No	Slot riservati all'inbound (default 0)
scheduledAt	string	No	ISO 8601 — programmazione (SCHEDULED)
startImmediately	boolean	No	Se true, avvia subito dopo la creazione

Oggetto contatto

Ogni elemento di contacts deve avere phone_number (E.164). Gli altri campi possono essere mappati alle variabili del prompt con variableMapping.

Campo	Tipo	Descrizione
phone_number	string	Obbligatorio. Numero chiamato al tentativo 1
contact_attempts	array	Numeri/variabili alternativi per i retry (tentativo 2+)

Ogni voce in contact_attempts è un oggetto con almeno phone_number e campi opzionali che sovrascrivono quelli del contatto principale per quel tentativo.

Tentativi totali per contatto = 1 + maxRetries.

Esempio

curl -X POST https://api.replicer.ai/v1/campaigns \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Follow-up Q2",
    "agentId": "clx-agent-001",
    "fromNumber": "+39000000001",
    "fromNumberAttempts": ["+39000000001", "+39000000002"],
    "fromNumberStrategy": "rolling",
    "contactAttemptStrategy": "clamp",
    "maxRetries": 2,
    "retryDelayMinutes": 30,
    "contacts": [
      {
        "phone_number": "+39111111111",
        "name": "Mario Rossi",
        "company": "Acme",
        "contact_attempts": [
          { "phone_number": "+39222222222", "name": "Luigi Bianchi" }
        ]
      }
    ],
    "variableMapping": {
      "customer_name": "name",
      "company_name": "company"
    },
    "startImmediately": true
  }'

---

Avviare una campagna

POST /v1/campaigns/{id}/start

Avvia o riprende una campagna (DRAFT, SCHEDULED o PAUSED).

Scope richiesto: campaigns:write

---

Elencare le campagne

GET /v1/campaigns

Scope richiesto: campaigns:read

---

Dettaglio campagna

GET /v1/campaigns/{id}

Restituisce la campagna con contacts, fromNumberAttempts (in E.164) e contatori di avanzamento.

Scope richiesto: campaigns:read

Strategie di tentativo

Valore	Comportamento
rolling	Ruota ciclicamente nella lista
clamp	Usa ogni voce in ordine, poi ripete l'ultima
custom	Caller ID: un numero per slot. Contatti: ogni alternativo una volta, poi il numero principale