Introduzione alle API #

L’API REST di Your AI Connector ti consente di creare la tua integrazione personale basata sul tuo account. Puoi creare e cercare contatti, gestire campagne, FAQ, attività e appuntamenti, inviare messaggi, registrare webhook, leggere analisi e connettere canali di messaggistica: tutto ciò che fa la dashboard, guidato dal codice.

Questa è la pagina principale della documentazione API. Se stai connettendo Your AI Connector a uno strumento che dispone già di un’integrazione integrata, potresti non aver bisogno dell’API. L’API è destinata a integrazioni personalizzate e all’automazione su larga scala.

URL di base #

Ogni richiesta viene inviata allo stesso indirizzo web di base e tutti i percorsi in questi documenti sono relativi ad esso:

https://api.youraiconnector.com/v1

Quindi l’endpoint delle campagne è https://api.youraiconnector.com/v1/campaigns, l’endpoint dei contatti è https://api.youraiconnector.com/v1/contacts e così via.

Tutte le richieste devono utilizzare una connessione sicura (HTTPS). Le richieste HTTP semplici vengono rifiutate.

Ottenere una chiave API #

L’accesso all’API è una funzionalità a pagamento. Se il tuo piano non la include, ogni richiesta restituirà un 403 con questo corpo:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Una volta abilitato l’accesso API sul tuo piano, genera una chiave dalla dashboard. La procedura completa passo dopo passo è disponibile in Accesso API — in breve: vai su Impostazioni → Integrazioni → Chiave API per generare o rigenerare la tua chiave. La Chiave API è una sezione a sé stante sotto Integrazioni, separata dai Webhook, e appare solo quando l’accesso API è attivo sul tuo piano. Tratta la chiave come una password: garantisce l’accesso completo al tuo account.

Autenticazione #

Puoi inviare la tua chiave API in quattro modi. Tutti funzionano su ogni endpoint che accetta l’autenticazione tramite chiave API.

Per la produzione, preferisci una delle forme di header in modo che la tua chiave non finisca mai in un log del server o nella cronologia del browser. La forma con parametro di query funziona sempre ed è la più semplice per un test occasionale.

Consulta Autenticazione per un’analisi completa di ciascun metodo, con esempi e indicazioni su quando utilizzare quale.

La tua prima richiesta #

Ecco una chiamata completa e funzionante che elenca le campagne sul tuo account. Utilizza la tua chiave API e restituisce per prime le campagne più recenti.

cURL

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

JavaScript

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

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Una risposta corretta ha questo aspetto:

{
  "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": null
}

Risposte di successo ed errore #

Ogni risposta JSON contiene un flag success in modo da poter creare una ramificazione senza dover analizzare i codici di stato.

Una risposta di successo è success: true più i dati per quell’endpoint (il nome del campo varia: campaigns, contacts, data e così via):

{
  "success": true,
  "campaigns": []
}

Una risposta fallita è success: false con un messaggio error leggibile dall’utente e un error_code numerico che corrisponde allo stato HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Controlla sempre success (o lo stato HTTP) prima di leggere i dati. Consulta Errori e paginazione per la tabella completa dei codici di stato e per sapere come scorrere set di risultati di grandi dimensioni.

Limiti di frequenza #

Le richieste autenticate sono limitate a 300 richieste al minuto per chiave API. Esiste inoltre un limite massimo più ampio di 1.200 richieste al minuto per account, che conteggia ogni richiesta autenticata effettuata per tale account.

Se superi uno dei due limiti, riceverai una risposta 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Attendi e riprova dopo una breve pausa. Puoi anche controllare il tuo utilizzo attuale in qualsiasi momento con GET https://api.youraiconnector.com/v1/api-keys/usage, che restituisce quante richieste hai utilizzato nella finestra corrente e quando si azzera: utile per creare una limitazione lato client. Consulta Chiavi API.

Guide alle risorse #

I gruppi di risorse qui sotto hanno ciascuno la propria guida con i percorsi esatti, i campi di richiesta e le strutture di risposta.

Agenti, Punti di ingresso e Broadcast #

Gli Agenti IA, i Punti di ingresso e i Broadcast sono tutti presenti nella specifica OpenAPI pubblicata, quindi puoi consultare i loro campi esatti ed eseguire richieste live tramite l’esploratore API. Ognuno ha la sua guida dedicata: Agenti IA, Punti di ingresso e Broadcast.

Leggere questa documentazione in formato Markdown #

Ogni pagina di questa documentazione ha un gemello in formato Markdown semplice: prendi l’indirizzo della pagina e aggiungi /index.md alla fine. Quindi questa pagina è disponibile anche su https://docs.youraiconnector.com/api/getting-started/index.md e viene restituita come testo semplice anziché come pagina web: utile quando vuoi incollare una pagina in un assistente AI o richiamarla in uno script.

Per consultare l’intero set, parti da https://docs.youraiconnector.com/sitemap.xml, che elenca ogni pagina che pubblichiamo. Tieni presente che la documentazione è volutamente esclusa dai motori di ricerca, quindi recuperare questi indirizzi direttamente è il modo per accedervi dal codice.

Non esiste ancora un endpoint di documentazione protetto da chiave né un download in blocco: i gemelli Markdown e la sitemap costituiscono l’intera interfaccia e nessuno dei due richiede una chiave API.

Passaggi successivi #

• Autenticazione — scegli il metodo di autenticazione corretto per la tua integrazione.
• Errori e impaginazione — gestisci gli errori e scorri i risultati.
• Accesso API — genera la tua chiave e visualizza esempi pratici.