Accesso API #

Un’API (Application Programming Interface) è un modo in cui diversi sistemi software possono comunicare tra loro. L’API Your AI Connector consente a te (o al tuo sviluppatore) di creare contatti, inviare messaggi, gestire elenchi e ricevere messaggi in arrivo da canali personalizzati, il tutto senza utilizzare la dashboard.

Perché usare l’API? Se desideri connettere l’app a uno strumento che non dispone di un’integrazione nativa, o se hai bisogno di automatizzare attività ripetitive su larga scala, l’API è la soluzione ideale.

Generazione della tua chiave API #

1. Nella barra laterale sinistra, fai clic su Impostazioni (icona a forma di ingranaggio).
2. Nella barra laterale delle Impostazioni, sotto il gruppo Integrazioni, fai clic su Chiave API.

3. Se non hai ancora una chiave, fai clic su Genera chiave API.
4. Se ne hai già una, viene mostrata mascherata sotto La tua chiave. Se la tua chiave lo supporta, fai clic su Mostra per rivelarla, quindi su Copia per copiarla: vedrai apparire un messaggio di conferma.
5. Conserva la chiave in un luogo sicuro: ti servirà per ogni richiesta API.

Membri del team: la chiave API appartiene al proprietario dell’account, quindi se hai effettuato l’accesso come membro del team invitato (incluso un Amministratore), la sezione mostrerà una nota invece della chiave. Accedi come proprietario dell’account per visualizzarla, copiarla o rigenerarla; questo vale anche per le chiavi con ambito limitato.

Dove trovarla: Chiave API è una sezione a sé stante sotto Impostazioni → Integrazioni, separata dai Webhook. Se una guida o un collega ti dice di cercare la chiave sotto “Webhook”, guarda invece nella sezione accanto.

Chiavi con ambito limitato: chiavi extra per un compito specifico #

La tua chiave principale può fare tutto, quindi non è la chiave da fornire a un report, a una dashboard cliente o a una configurazione separata di sandbox e sviluppo. Per questo, crea chiavi con ambito limitato nella scheda Chiavi con ambito limitato, nella stessa sezione Chiavi API sotto La tua chiave:

1. Fai clic su Nuova chiave.
2. Assegna un Nome che riconoscerai in seguito, ad esempio “Sandbox” o “Dashboard cliente Acme”.
3. Sotto Cosa può vedere, seleziona solo le aree necessarie.
4. Sotto Cosa può fare, lascia Sola lettura a meno che lo strumento non debba apportare modifiche. Una chiave in grado di apportare modifiche può inviare messaggi e modificare la tua configurazione.
5. Facoltativamente, imposta Richieste al minuto (il suo limite specifico, in modo che non rallenti mai le tue altre integrazioni) e una data di Scadenza.
6. Fai clic su Crea chiave e copiala immediatamente. Le chiavi con ambito limitato vengono mostrate una sola volta; se ne perdi una, revocala e creane un’altra.

Puoi crearne quante ne servono. Ogni chiave nell’elenco mostra quando è stata utilizzata l’ultima volta e Revoca chiave ne interrompe immediatamente il funzionamento. La creazione o la revoca di una chiave con ambito limitato non influisce mai sulla tua chiave principale. Le opzioni complete, incluse le chiavi limitate a specifici sotto-account, sono disponibili nella pagina delle chiavi API nel riferimento API.

URL di base #

Tutte le richieste API utilizzano il seguente indirizzo web di base:

https://api.youraiconnector.com/v1/

Autenticazione #

Ogni richiesta deve includere la tua chiave API in modo che la piattaforma sappia che sei tu. Il modo più semplice è aggiungerla alla fine dell’indirizzo web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Puoi anche inviare la chiave come intestazione della richiesta invece che nell’URL (scelta consigliata per la produzione, in modo che la chiave non finisca nei log del server):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

Cerchi le guide complete per sviluppatori? Questa pagina è una rapida introduzione che copre le operazioni più comuni. Per guide complete passo dopo passo — ogni risorsa, con esempi in cURL, JavaScript e Python — consulta Introduzione all’API e il Riferimento API.

Operazioni API comuni #

Creare un contatto #

Richiesta:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Campi obbligatori: un phoneNumber (con prefisso internazionale) è sempre richiesto per creare un contatto. Un indirizzo email da solo non è sufficiente: una richiesta senza un numero di telefono valido viene rifiutata. L’email è facoltativa.

Risposta:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Salva data.contactId: ti servirà per la chiamata “Aggiungi un contatto a una lista”.

Aggiungi un contatto a una lista #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Trova l’ID di una lista nell’app sotto Contatti → Liste, dal menu della riga della lista (Copia ID lista).

Aggiorna un contatto #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Vengono modificati solo i campi inclusi. Questo è anche il modo per caricare in blocco i valori dei campi personalizzati dopo un’importazione: consulta Campi personalizzati, Profilo lead e Note. Dettagli completi nell’API Contatti.

Invia un messaggio (Canale personalizzato) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Ricevi messaggi in entrata (Canale personalizzato) #

Accetta messaggi da sistemi esterni come canale personalizzato. È così che integrazioni come GoHighLevel inviano messaggi a Your AI Connector. Consulta Canali personalizzati per tutti i dettagli.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Panoramica delle operazioni disponibili #

Limitazione della frequenza (Rate Limiting) #

L’API applica limiti di frequenza per garantire la stabilità della piattaforma. Il superamento del limite restituisce 429 Too Many Requests: attendi e riprova dopo il tempo indicato nelle intestazioni della risposta. Per casi d’uso ad alto volume (importazioni massive), utilizza la funzionalità di importazione integrata o invia un’email a hi@youraiconnector.com per ricevere assistenza.

Best practice #

• Conserva la tua chiave API in modo sicuro — usa un gestore di password o una configurazione lato server, mai codice lato client che un visitatore del browser potrebbe leggere.
• Includi sempre il prefisso internazionale nei numeri di telefono (+1 per gli Stati Uniti, +44 per il Regno Unito, +31 per i Paesi Bassi).
• Gestisci gli errori correttamente — controlla i codici di stato e leggi eventuali messaggi di errore restituiti.
• Gestisci i duplicati — un numero di telefono duplicato restituisce { "success": false, "error_code": 409 } invece di un nuovo contatto, con l’ID del contatto esistente in contactId.
• Esegui test con un set di dati ridotto prima di effettuare operazioni in blocco.

Risposte di errore #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Prossimi passi #

• Webhook — ricevi notifiche in tempo reale dall’app (una sezione separata dalla tua chiave API).
• Connetti assistenti AI (MCP) — usa la stessa chiave API per consentire a Claude di gestire il tuo account.
• Moduli lead di Facebook — usa l’API con piattaforme di automazione per acquisire lead.
• Integrazione GoHighLevel — un esempio completo di integrazione API bidirezionale.