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.

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) #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

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 USA, +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. Cerca prima il contatto se devi lavorarci.
• Esegui test con un piccolo set di dati prima di eseguire 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.