API dei Punti di Ingresso #

Un Punto di Ingresso è una regola di instradamento: “quando succede questo su questo canale, passa la conversazione a questo Agente”. Collegare un canale permette di ricevere messaggi nell’account e creare un Agente ti dà qualcuno che può rispondere, ma nessuno dei due decide chi risponde al primo messaggio di uno sconosciuto. I Punti di Ingresso lo fanno. Per il prodotto in sé, consulta la guida ai Punti di Ingresso.

• URL di base — https://api.youraiconnector.com/v1
• Autenticazione — la tua chiave API (vedi Autenticazione)
• Errori e paginazione — vedi Errori e paginazione

Tutti gli esempi seguenti mostrano il formato di query ?apiKey= in cURL e l’intestazione X-API-Key in JavaScript e Python; entrambi funzionano su ogni endpoint.

Nell’API explorer. Ogni endpoint in questa pagina è presente nella specifica OpenAPI pubblicata, quindi puoi consultare i suoi campi esatti ed eseguire richieste live nell’API explorer.

L’unica chiamata di cui la maggior parte delle integrazioni ha bisogno #

Collega un canale, crea un Agente, quindi punta il canale verso l’Agente:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Questa è l’intera configurazione per “questo Agente risponde a WhatsApp”. Tutto il resto in questa pagina riguarda regole più specifiche (parole chiave, commenti, nuovi follower), diversi numeri su un unico canale e la lettura della configurazione attuale.

Come viene deciso l’instradamento #

Quando arriva un messaggio, la piattaforma segue una gerarchia fissa e il primo passaggio che prende una decisione vince:

1. Un essere umano ha preso il controllo della conversazione — niente IA.
2. Il contatto è già assegnato a un Agente, manualmente o perché è in corso una conversazione con quell’Agente — lo stesso Agente la mantiene. I Punti di Ingresso non spostano mai una conversazione esistente; per passare una chat a un Agente diverso, assegnala (nell’app o con l’azione Automazioni).
3. Il contatto sta rispondendo a una trasmissione — risponde l’Agente della trasmissione, o nessuno se la trasmissione non ne aveva uno.
4. Corrisponde un Punto di Ingresso specifico. Le regole per parola chiave prevalgono su quelle per commento, che prevalgono su quelle per follower. Tra due regole dello stesso tipo, vince quella aggiornata più di recente.
5. Il valore predefinito del canale su cui è arrivato il messaggio. Un valore predefinito limitato allo specifico numero a cui il contatto ha scritto prevale sul valore predefinito dell’intero canale.
6. Nessuna corrispondenza — il messaggio finisce nella casella di posta del tuo team e nessun assistente risponde.

Due fattori attenuano il punto 6. Un account con esattamente un Agente attivo e nessuna configurazione predefinita per il canale riceve comunque quell’Agente come risponditore, quindi un account appena creato che collega WhatsApp e invia un messaggio di prova non riceve il silenzio. Questo limite minimo non si applica mai a un canale che ha una regola per parola chiave (lì, un messaggio che non corrisponde a nessuna parola chiave viene deliberatamente lasciato a un umano) e non sovrascrive mai un canale impostato su “nessuno” (vedi Lasciare un canale senza nessuno che risponda).

Se la gerarchia è attiva per un account viene segnalato da GET /entry-points/routing-status. Oggi è attiva per ogni account; la chiamata esiste affinché un’integrazione possa verificare invece di dare per scontato.

L’oggetto Punto di Ingresso #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Tipi di regola #

Una regola basata su parole chiave su un canale senza impostazione predefinita funziona anche come filtro: i messaggi che non corrispondono a nessuna delle parole chiave non ricevono alcuna risposta automatica e finiscono semplicemente nella tua casella di posta, anche su un account con un solo Agente.

Assegna un canale a un Agente #

PUT /entry-points/channel-defaults — rende un Agente il responsabile delle risposte per i nuovi contatti su un canale. Qualsiasi altro Agente attualmente impostato come predefinito per quel canale viene rimosso nella stessa chiamata, in modo che un canale abbia sempre esattamente un responsabile. Impostare l’Agente che è già quello predefinito non cambia nulla.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Risposta

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id è la regola attualmente in vigore; disabled_entry_point_ids elenca le eventuali regole rimosse per farle spazio (vuoto quando non c’era nulla da sostituire). Sono interessati solo i contatti con cui non hai mai parlato: chiunque sia già in una conversazione con un Agente mantiene quell’Agente.

Un 400 significa che channel o agent_id mancano, l’Agente appartiene a un altro account o phone_number non è uno dei tuoi numeri collegati.

Vedi chi risponde a ogni canale #

GET /entry-points/channel-defaults — ogni impostazione predefinita di canale sull’account, dalla più recente, incluse quelle rimosse (enabled: false) e un canale deliberatamente impostato su nessuno (agent_id: ""). Filtra su enabled per avere il quadro attuale.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Questa è la lettura a livello di account. Elencare le regole di un Agente con GET /agents/{agentId}/entry-points non può mostrare un canale impostato su nessuno, perché quella regola non appartiene a nessun Agente.

Lascia un canale senza nessuno che risponda #

DELETE /entry-points/channel-defaults?channel=instagram — rimuove l’impostazione predefinita a livello di canale per un canale. Il canale viene indicato come parametro di query, non nel corpo. Aggiungi &phone_number=%2B31685101091 per cancellare solo l’impostazione predefinita di quel numero e lasciare che il numero torni a chiunque risponda al canale.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { 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/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Sicuro da ripetere: cancellare un canale che non ha impostazioni predefinite è un 200 con un elenco vuoto. Cancellare significa annullare, non silenziare: su un account con esattamente un Agente attivo, un canale non configurato ricade comunque su quell’Agente. Per mantenere l’IA completamente fuori da un canale, seleziona Nessuno risponde per esso nel pannello Chi risponde alle nuove conversazioni dell’app (che scrive un’impostazione predefinita esplicita “nessuno” che il fallback non sovrascrive mai), oppure metti in pausa l’Agente con PATCH /agents/{agentId}/active.

Un Agente per numero WhatsApp #

Il routing è per canale per impostazione predefinita: tutti i tuoi numeri WhatsApp condividono un unico responsabile delle risposte. Con due o più numeri collegati su WhatsApp Business o WhatsApp Web, un’impostazione predefinita può essere limitata a un singolo numero, in modo che un’attività con un numero per filiale o marchio possa assegnare a ciascuno il proprio Agente all’interno di un unico account.

Invia phone_number con la chiamata set:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Il numero deve essere uno dei tuoi numeri collegati su quel canale, scritto come appare sotto i numeri collegati (E.164 con il +); qualsiasi altra cosa è un 400.
• La regola viene memorizzata come impostazione predefinita del canale con match_config.phone_numbers: ["+31685101091"]. Un messaggio che arriva su quel numero va al suo Agente; ogni altro numero continua a seguire l’impostazione predefinita dell’intero canale.
• Impostare o cancellare l’impostazione predefinita dell’intero canale non influisce sulle regole specifiche per numero, e viceversa. Cancella la regola di un numero specifico con DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Le risposte partono sempre dal numero a cui il contatto ha scritto, in modo che il contatto continui a parlare con lo stesso numero e lo stesso Agente.

Aggiungi una regola più specifica #

POST /agents/{agentId}/entry-points — crea una regola per parola chiave, commento o follower (o un’impostazione predefinita del canale, sebbene PUT /entry-points/channel-defaults sia la scelta migliore per questo scopo perché ritira automaticamente il risponditore precedente). L’Agente nel percorso ha sempre la priorità: una regola non può mai essere creata per un Agente diverso da quello presente nell’URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Risposta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Una regola da commento a messaggio diretto (DM) che reagisce solo ai commenti che dicono “LINK” su due post specifici, attende due minuti e invia un primo messaggio fisso:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Lascia keywords vuoto per inviare un DM a chiunque commenti i post monitorati, e post_ids vuoto per monitorare ogni post. Un 400 indica cosa non va: un type sconosciuto, un channels vuoto, una regola per parola chiave senza parole chiave, o una regola per i commenti che non elenca il proprio canale.

Elenca le regole di un Agente #

GET /agents/{agentId}/entry-points — le regole che inviano le conversazioni a questo Agente, dalla più recente: le sue impostazioni predefinite del canale, le regole per parola chiave, le regole per i commenti e le regole per i follower. Anche le regole ritirate vengono visualizzate, con enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Modifica una regola #

PUT /entry-points/{entryPointId} — modifica una regola. Invia solo i campi che stai cambiando; le impostazioni nidificate possono essere gestite singolarmente con una chiave puntata come "match_config.keywords". Ogni volta che la modifica tocca type, channels o match_config, l’intera regola viene ricontrollata, quindi una modifica parziale non può mai lasciare una regola inutilizzabile (passare da type a keyword senza fornire parole chiave viene rifiutato). L’invio di agent_id assegna la regola a un altro dei tuoi Agenti; uno vuoto viene rifiutato. I campi di proprietà e identità vengono ignorati.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Risposta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Altre modifiche comuni: { "enabled": false } ritira una regola senza eliminarla, e { "agent_id": "agOtherAgent" } la sposta su un Agente diverso. Un corpo vuoto restituisce 400 con "No fields to update".

Elimina una regola #

DELETE /entry-points/{entryPointId} — rimuove la regola in modo permanente. Nient’altro fa riferimento a un Punto di ingresso, quindi non c’è nulla da scollegare prima.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  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/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Per impedire l’attivazione di una regola mantenendola però nel sistema, imposta enabled su false. Le impostazioni predefinite del canale, in particolare, vengono solitamente ritirate anziché eliminate, che è ciò che fa DELETE /entry-points/channel-defaults.

Verifica che il routing sia attivo #

GET /entry-points/routing-status — restituisce se la gerarchia dei Punti di Ingresso decide chi risponde su questo account. Leggibile con accesso di visualizzazione, in modo che un membro del team veda la stessa risposta del proprietario.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Oggi è true su ogni account. La chiamata viene mantenuta in modo che un’integrazione possa verificare prima di comunicare a qualcuno che la modifica del routing è attiva, invece di darlo per scontato.

Le chiamate più vecchie, basate sulle campagne #

Due endpoint precedenti agli Agenti funzionano ancora per gli account organizzati attorno alle campagne. Le nuove integrazioni dovrebbero utilizzare le chiamate ai canali predefiniti sopra indicate.

• PUT /channel-routing/{channel} con { "campaignId": "cp5NbV8xQrT2wYzA" } — assegna un nome a una campagna e l’Agente di quella campagna diventa il risponditore del canale. { "campaignId": null } libera il canale. Una campagna solo in uscita viene rifiutata perché non ha alcun comportamento in entrata da offrire.
• POST /channel-routing/clear con { "channels": ["whatsapp", "instagram"] } — libera diversi canali da qualunque Agente risponda ad essi in un’unica chiamata, solitamente prima di indirizzarli altrove. La risposta elenca released_channels, quelli che avevano effettivamente un risponditore.

Entrambi annullano l’impostazione anziché silenziare: su un account con esattamente un Agente attivo, un canale liberato ricade comunque su quell’Agente.

Errori dell’API dei Punti di Ingresso #

Gli endpoint dei Punti di Ingresso restituiscono il busta di errore standard:

{
  "success": false,
  "error": "Entry point 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.

Passaggi successivi #

• Punti di Ingresso — il concetto, i tipi di regola e il pannello Chi risponde alle nuove conversazioni nell’app.
• API Agenti IA — crea e configura gli Agenti a cui queste regole indirizzano.
• API Canali — collega i canali stessi.
• Automazione Commento-a-DM — cosa fanno le regole di commento una volta attivate.