API di connessione ai canali #

Questa guida mostra come connettere i canali di messaggistica a un account utilizzando l’API. È scritta per uno sviluppatore che sta creando un’integrazione o un wrapper, quindi si concentra sulle richieste esatte, sull’ordine in cui effettuarle e sulle risposte ricevute.

C’è un pattern che devi comprendere fin da subito, perché si applica a quasi tutti i canali qui presenti.

Il pattern di connessione e polling #

La maggior parte dei canali non può essere connessa con una singola chiamata API. Connettere WhatsApp, Instagram o Messenger significa che il titolare dell’account deve accedere al proprio account del provider e approvare l’accesso. Non esiste un percorso headless (completamente automatizzato) per tale approvazione: una persona reale deve aprire un URL in un browser o scansionare un codice QR con il proprio telefono.

Quindi il flusso è sempre:

1. Avvia la connessione con una POST. La risposta ti fornisce un URL da aprire o un codice QR da visualizzare.
2. Passalo all’utente finale: apri l’URL nel suo browser o visualizza il codice QR sullo schermo affinché possa scansionarlo.
3. Esegui il polling dell’endpoint di stato con GET a intervalli brevi (ogni pochi secondi) finché lo stato non raggiunge quello di connesso.

Il compito della tua integrazione è gestire questo ciclo: mostra l’URL o il QR, quindi esegui il polling fino al completamento. Progetta la tua interfaccia attorno al polling: uno spinner con un messaggio del tipo “in attesa del completamento nel browser” funziona bene.

Instagram + Messenger (Meta) #

Instagram e Messenger vengono connessi insieme in un unico flusso, poiché entrambi funzionano su una Pagina Facebook. Il titolare dell’account autorizza tramite Facebook, tu recuperi l’elenco delle Pagine che gestisce e scegli quale Pagina connettere.

Passaggio 1 - Avvia la connessione Instagram + Messenger #

POST /channels/meta/connect

Questo restituisce un URL di consenso. Nessuna credenziale viene inviata in questa richiesta: la connessione viene autorizzata interamente nel browser.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Risposta

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Apri oauth_url nel browser dell’utente finale in modo che possa accedere a Facebook e approvare l’accesso. Il tentativo di connessione scade a expires_at (circa 30 minuti): se scade, ricomincia da capo. Tratta state_token come un segreto a breve termine e non registrarlo.

Opzione più semplice per Instagram + Messenger: consegna connect_url #

La risposta include anche un connect_url pronto all’uso: una pagina ospitata che esegue l’intero flusso per il titolare dell’account. L’utente la apre, accede a Facebook e, se possiede più di una Pagina, visualizza l’elenco e può scegliere quale collegare; dopodiché, la pagina segnala autonomamente l’esito positivo. Fornisci questo link al titolare dell’account invece di aprire oauth_url personalmente, creare un selettore di Pagine ed eseguire il polling. Il link è valido per circa 30 minuti (connect_url_expires_at); se scade, avvia una nuova connessione. I passaggi manuali riportati di seguito sono destinati alle integrazioni che desiderano gestire il flusso e visualizzare autonomamente il selettore di Pagine.

Passaggio 2 - Esegui il polling dello stato finché le pagine non vengono caricate #

GET /channels/meta/status

Dopo che l’utente ha completato l’accesso a Facebook, esegui il polling di questo endpoint ogni pochi secondi. Il campo status attraversa queste fasi:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Risposta (una volta caricate le pagine)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Passaggio 3 - Elenca le pagine (facoltativo) #

Se preferisci recuperare l’elenco delle Pagine separatamente (ad esempio, per eseguire il rendering di un selettore), utilizza:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Restituisce lo stesso array pages dell’endpoint di stato. (L’endpoint status include già le pagine, quindi questa chiamata è solo una comodità.)

Passaggio 4 - Seleziona la pagina da connettere #

POST /channels/meta/select-page

Invia l’ page_id della Pagina scelta dall’utente. L’account Instagram collegato a tale Pagina viene connesso automaticamente; ti serve l’oggetto instagram solo se desideri sovrascrivere l’account Instagram da utilizzare.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Risposta

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

Il canale è ora connesso. Un GET /channels/meta/status di follow-up riporterà status: "connected".

Elenca i post della pagina connessa #

GET /channels/meta/posts?platform=instagram

Restituisce i post recenti della pagina che hai connesso: contenuti Instagram o post Facebook. È ciò da cui esegui il rendering di un selettore quando configuri un Punto di Ingresso che reagisce ai commenti su un post specifico.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType è l’etichetta propria di Instagram (REELS, FEED, STORY, o il formato - IMAGE, VIDEO, CAROUSEL_ALBUM); per Facebook è sempre POST. nextCursor è null nell’ultima pagina.

Se non è possibile elencare nulla, la chiamata restituisce comunque 200 con connected: false e un array posts vuoto, più un reason che indica il motivo:

Disconnetti Instagram + Messenger #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "disconnected": true }

Questo interrompe il routing in entrata sia per Instagram che per Messenger. È idempotente: chiamarlo quando non c’è nulla di connesso ha comunque esito positivo.

WhatsApp Business #

Questo collega un numero ufficiale WhatsApp Business. Il numero deve già esistere sull’account prima di richiamare la connessione. Come per Meta, il titolare dell’account autorizza nel proprio browser, quindi si esegue il polling finché il numero non riporta ONLINE.

Passaggio 1 - Avvia la connessione WhatsApp Business #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Risposta

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Apri oauth_url nel browser del titolare dell’account per autorizzare. Una volta approvato, la registrazione viene completata in background.

Passaggio 2 - Eseguire il polling dello stato fino a ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Esegui il polling finché status non è ONLINE.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Risposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Il campo status può essere:

live: true significa che lo stato è stato verificato presso il provider in tempo reale; false significa che proviene dall’ultimo stato memorizzato nella cache.

Disconnetti un numero WhatsApp Business #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

Il numero rimane sull’account, quindi è possibile ricollegarlo in seguito.

WhatsApp Web #

WhatsApp Web collega un normale numero WhatsApp scansionando un codice QR, proprio come quando si collega un dispositivo nell’app WhatsApp. Il flusso è: avviare la sessione, recuperare il codice QR e mostrarlo, quindi eseguire il polling fino a quando lo stato è connected.

Passaggio 1 - Avvia una sessione di accoppiamento WhatsApp Web #

POST /channels/whatsapp-web/connections

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Risposta

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Opzione più semplice per WhatsApp Web: consegna connect_url #

La risposta include un connect_url pronto all’uso: una pagina ospitata che mostra il codice QR, lo aggiorna automaticamente man mano che ruota e passa a un messaggio di successo nel momento in cui il numero viene collegato. Basta fornire questo link al titolare dell’account (aprilo in un browser, invialo o mostralo come QR/pulsante) e farglielo scansionare con WhatsApp: non è necessario recuperare il QR o eseguire il polling autonomamente. Il link funziona per circa 30 minuti (connect_url_expires_at); se scade prima che abbiano terminato, avvia una nuova connessione per ottenerne uno nuovo.

Questo è il percorso consigliato quando una persona può aprire un link. I passaggi manuali di seguito (recuperare il QR autonomamente, eseguire il polling dello stato) sono destinati alle integrazioni che desiderano invece visualizzare il QR all’interno della propria interfaccia.

La risposta fornisce anche l’esatto poll_qr_path e poll_status_path da utilizzare, così non dovrai crearli da solo.

Passaggio 2 - Recuperare il codice QR e mostrarlo #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Risposta

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Visualizza il QR affinché l’utente possa scansionarlo con il proprio telefono (WhatsApp > Dispositivi collegati > Collega un dispositivo):

• qr_data_url è un’immagine pronta all’uso: inseriscila direttamente in un <img src>.
• qr_code è il payload grezzo se preferisci generare l’immagine da solo.

Il QR ha una durata breve. Se chiami questo metodo subito dopo aver avviato la sessione, potresti ricevere un 404 con “Codice QR non ancora disponibile”: attendi un momento e riprova. Se ricevi un 410 (“Codice QR scaduto”), riavvia la connessione per ottenere un nuovo codice.

Passaggio 3 - Eseguire il polling dello stato fino alla connessione #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Risposta

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Disconnetti una sessione WhatsApp Web #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Questo scollega il dispositivo e rimuove la connessione. Pulisce sempre lo stato locale, quindi è idempotente anche se la sessione sottostante era già terminata.

Telegram #

Disponibilità: Telegram si connette come qualsiasi altro canale ed è aperto a tutti gli account; non è necessario che venga attivato per te. Gli endpoint di Telegram riportati di seguito possono comunque restituire 403 se Telegram non è incluso nel piano dell’account; in tal caso, l’errore indica "This channel is not included in your current plan. Upgrade to unlock it.".

Telegram connette un account personale tramite numero di telefono più un codice di accesso monouso (e una password a due fattori, se l’account ne ha una impostata). Il flusso è: avviare la sessione, inviare il codice, facoltativamente inviare la password, quindi confermare tramite lo stato.

Passaggio 1 - Avvia una sessione di connessione Telegram #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Risposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

In modalità code l’account riceve un codice di accesso su Telegram e status è code_required. (In modalità qr la risposta include anche login_token e qr_url da visualizzare per la scansione, e status è qr_required.)

Opzione più semplice per Telegram: consegna connect_url #

La risposta include un connect_url pronto all’uso: una pagina ospitata che completa la connessione autonomamente. In modalità code, il titolare dell’account inserisce il codice di accesso e, se l’account ne è dotato, la password di verifica in due passaggi. In modalità qr, la pagina mostra un QR code che si aggiorna automaticamente, da scansionare tramite l’app Telegram. In entrambi i casi, la pagina segnala il successo dell’operazione, quindi puoi semplicemente fornire questo link al titolare dell’account invece di creare un’interfaccia personalizzata e gestire il polling. Il link è valido per circa 30 minuti (connect_url_expires_at); se scade, avvia una nuova connessione per ottenerne uno nuovo.

I passaggi manuali riportati di seguito (raccogliere il codice autonomamente, inviarlo, eseguire il polling dello stato; oppure eseguire il rendering di qr_url ed eseguire il polling) sono destinati alle integrazioni che desiderano gestire autonomamente il rendering dell’interfaccia utente.

Passaggio 2 - Inviare il codice di accesso #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Risposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Se status è connected, hai finito. Se l’account ha l’autenticazione a due fattori abilitata, status sarà password_required - procedi al passaggio 3.

Passaggio 3 - Inviare la password a due fattori (solo se necessario) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Chiama questo metodo solo quando il passaggio 2 ha restituito password_required.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Risposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Controlla lo stato di Telegram #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status può essere connected, code_required, password_required, initializing, disconnected, not_initialized o error.

Disconnetti Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotente: le chiamate ripetute hanno successo.

Instagram (account personale) #

Beta a disponibilità limitata, abilitata per singolo account. Questa funzione collega un account Instagram personale effettuando l’accesso con nome utente e password (non tramite l’API Business ufficiale). Se l’account non è abilitato per la beta, la chiamata di connessione restituisce un errore di autorizzazione.

Poiché questa procedura richiede le credenziali Instagram del titolare dell’account, la soluzione più semplice consiste nel fornire il connect_url ospitato e lasciare che inserisca le proprie credenziali lì: la tua integrazione non gestirà mai la password.

Passaggio 1 - Avvia una connessione Instagram (personale) #

POST /channels/instagram-private/connect

Invia l’Instagram username e password.

Risposta

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Se l’account ha l’autenticazione a due fattori o Instagram presenta un checkpoint, status viene restituito come two_factor_required o challenge_required: invia il codice a /connect/{id}/verify-2fa o /connect/{id}/verify-challenge qui sotto, quindi esegui il polling di /connect/{id}/status finché non diventa connected. {id} è il nome utente Instagram normalizzato restituito come account_id/username nella risposta sopra: usalo in ogni passaggio qui sotto.

Passaggio 2 - Invia il codice a due fattori (se richiesto) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Chiama questo endpoint solo quando il passaggio 1 (o il passaggio 3) ha restituito two_factor_required.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Risposta

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status può tornare come connected (fatto), two_factor_required (codice errato, riprova), o challenge_required (Instagram richiede anche un codice di checkpoint: vai al passaggio 3).

Passaggio 3 - Invia il codice di conferma del checkpoint (se richiesto) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Chiama questo endpoint solo quando un passaggio precedente ha restituito challenge_required. Stessa forma di richiesta e risposta del passaggio 2 sopra.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Controlla lo stato di Instagram (personale) #

GET /channels/instagram-private/connect/{id}/status

Esegui il polling di questo endpoint finché status non è connected, o finché non segnala un errore terminale.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status può essere connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized, o error. live: true significa che questo valore è stato letto in tempo reale dal worker di connessione anziché essere un valore memorizzato nella cache.

Opzione più semplice per Instagram (personale): consegna connect_url #

La risposta include un connect_url: una pagina ospitata in cui il titolare dell’account inserisce il proprio nome utente e password di Instagram (e un codice 2FA o di checkpoint se richiesto da Instagram), che segnala autonomamente l’esito positivo. Le credenziali vengono inviate direttamente a Instagram e non vengono memorizzate. Fornisci questo link al titolare dell’account invece di raccogliere la sua password nella tua interfaccia. Il link è valido per circa 30 minuti (connect_url_expires_at).

Disconnetti Instagram (personale) #

DELETE /channels/instagram-private/{id}

Idempotente: le chiamate ripetute hanno successo.

Sincronizza follower #

POST /channels/instagram-private/{id}/sync-followers

Attiva manualmente una sincronizzazione dei follower per un account collegato: lo stesso processo che viene eseguito automaticamente in background, qui esposto come azione “Aggiorna follower” su richiesta. Recupera l’elenco attuale dei follower dell’account, registra i nuovi arrivati e (quando una campagna Live ha attivato il contatto dei follower) invia ai nuovi follower un messaggio diretto di apertura, fino a un limite giornaliero.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Questi cinque campi sono l’unico punto in questa pagina che restituisce camelCase invece di snake_case: è così che questo endpoint è configurato oggi, non è un errore di battitura. isBaselineSeed: true significa che questa è stata la primissima sincronizzazione dopo la connessione, che registra solo l’elenco iniziale dei follower e non invia mai messaggi diretti di contatto (quindi dmsSent è sempre 0 durante quell’esecuzione).

La primissima chiamata per un account può richiedere del tempo (scorrere l’intero elenco dei follower); le chiamate successive sono più veloci poiché vengono analizzati solo i nuovi follower. 404 significa che l’account non è collegato; 412 significa che l’inizializzazione della connessione non è ancora terminata: attendi e riprova.

LINE #

LINE è il canale più semplice da collegare perché non richiede reindirizzamenti del browser o polling. Il cliente crea un canale Messaging API nella console LINE Developers, copia due valori e tu li invii in un’unica chiamata. Successivamente, fornisci loro un URL webhook da incollare nella console.

Passaggio 1 - Connetti con le credenziali del canale #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Due campi sono importanti per le operazioni successive:

• webhook_url - il cliente deve incollarlo nel campo Webhook URL del proprio canale LINE nella console LINE Developers (e abilitare “Use webhook”). Finché non lo farà, non arriveranno messaggi in entrata. Mostralo chiaramente.
• chat_mode_ok - quando false, l’Account Ufficiale è in modalità “chat” e non riceverà né invierà messaggi finché non verrà impostato in modalità “bot” nel LINE Official Account Manager. Subordina l’onboarding a questo flag e comunica al cliente di cambiare modalità.

Il channel_access_token e il channel_secret non vengono mai restituiti da alcun endpoint. Conservali da parte se ti servono di nuovo; in caso contrario, copiali nuovamente dalla console LINE.

Il bot_user_id restituito qui è l’identificativo di connessione che utilizzi nelle chiamate di stato, verifica e disconnessione riportate di seguito.

Passaggio 2 - Verifica nuovamente dopo la configurazione del webhook #

POST /channels/line/{botUserId}/verify-webhook

Dopo che il cliente ha terminato di configurare l’URL del webhook e passa alla modalità bot, chiama questa funzione per riconvalidare il token memorizzato e aggiornare la modalità chat memorizzata nella cache.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Se token_valid è false, il token di accesso memorizzato non autentica più: chiedi al cliente di riemetterlo nella console e chiama nuovamente POST /channels/line con il nuovo token.

Controlla lo stato di LINE #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINE non dispone di un feed di stato in tempo reale, quindi live qui è sempre false: i valori riflettono lo stato acquisito al momento della connessione (o dell’ultima verifica).

Disconnetti LINE #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

Viber si collega nello stesso modo di LINE (incollando il token di autenticazione del bot dal Pannello di amministrazione di Viber in una chiamata), con una differenza importante: la connessione REGISTRA anche il nostro webhook sul tuo bot in quel momento, quindi non c’è alcun passaggio separato nella console in seguito. Ciò significa anche che un tentativo di connessione può fallire se il nostro ingresso non riesce a rispondere al controllo sincrono del webhook di Viber, non solo se il token stesso è errato.

Passaggio 1 - Connetti con il token di autenticazione del bot #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Risposta

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

Il token di autenticazione non viene mai restituito da alcun endpoint: salvalo da parte se dovessi aver bisogno di reincollarlo. bot_id è l’identificatore di connessione utilizzato dalle chiamate di stato, verifica e disconnessione di seguito.

Controlla lo stato di Viber #

GET /channels/viber/{botId}/status

Riporta lo stato della connessione memorizzato. Aggiungi ?live=true per ricontrollare anche il bot su Viber e aggiornare la registrazione del webhook memorizzata nella cache: utile prima di presumere che un bot silenzioso sia effettivamente rotto.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false significa che il webhook del bot non punta più a noi: i messaggi in entrata sono persi. Di solito significa che un altro strumento ha collegato lo stesso bot in seguito (la registrazione del webhook di Viber segue la logica “l’ultimo che scrive vince”). Risolvi il problema con la chiamata di riverifica qui sotto, non c’è bisogno di chiedere al cliente di reincollare il proprio token. live è false quando la risposta è l’ultimo stato memorizzato nella cache anziché un controllo aggiornato su Viber.

Registra nuovamente il webhook #

POST /channels/viber/{botId}/verify-webhook

L’azione di riparazione per webhook_ok: false: registra nuovamente il nostro webhook sul bot utilizzando il token di autenticazione già memorizzato.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false significa che il token memorizzato non funziona più: riconnettiti con POST /channels/viber e un nuovo token.

Disconnetti Viber #

DELETE /channels/viber/{botId}

Annulla la registrazione del nostro webhook lato Viber (best-effort) e rimuove la connessione.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Disponibilità: Beta a disponibilità limitata, abilitata per account. La connessione a TikTok restituisce un errore di autorizzazione finché l’account non viene abilitato.

TikTok Business Messaging è un canale OAuth completo come Meta, ma più semplice per quanto riguarda il polling: non c’è un passaggio dedicato di polling dello stato da implementare, poiché l’account connesso appare autonomamente una volta che TikTok reindirizza l’utente e la connessione viene scritta. L’endpoint di stato sottostante esiste per confermare lo stato su richiesta (strumenti di supporto, controlli di integrità), non come qualcosa su cui è necessario eseguire un ciclo durante la connessione.

Passaggio 1 - Avvia la connessione a TikTok #

POST /channels/tiktok/connect

Non richiede credenziali: il titolare dell’account autorizza interamente tramite il proprio browser.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Apri oauth_url nel browser del titolare dell’account in modo che possa accedere a TikTok e approvare l’accesso. Lo stato scade a expires_at (circa 30 minuti) - se scade, ricomincia da capo. Non esiste una scorciatoia di pagina ospitata connect_url per TikTok; aprire oauth_url personalmente è l’unico percorso possibile.

Controlla lo stato di TikTok #

GET /channels/tiktok/{openId}/status

openId è l’open_id dell’account TikTok Business, noto una volta eseguito il callback OAuth.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTok non dispone di un controllo di integrità live economico, quindi live qui è sempre false: i campi riflettono ciò che è stato scritto dalla connessione (o dall’ultimo aggiornamento del token). status: "reauth_required" con status_reason impostato significa che l’account deve ripetere la connessione; i token TikTok vengono aggiornati automaticamente con una rotazione annuale, e questo è ciò che appare se tale rotazione dovesse fallire.

Disconnetti TikTok #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) è un’integrazione CRM, non un canale di messaggistica: connetterlo non consuma uno slot canale nel piano, poiché sfrutta i canali esistenti dell’account invece di aggiungerne uno nuovo. È anche l’unica integrazione in questa pagina in grado di gestire più di una connessione alla volta: ogni sotto-account GHL (“posizione”) su cui il cliente installa l’app ottiene la propria voce.

Passaggio 1 - Avvia la connessione GHL #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Apri oauth_url nel browser del titolare dell’account in modo che possa scegliere una posizione GHL e approvare l’accesso. Lo stato scade alle expires_at (circa 30 minuti).

Elenca le connessioni GHL #

GET /channels/ghl/status

A differenza di altri canali, questo non è lo stato di una singola connessione: elenca ogni posizione che l’account ha collegato.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

Disconnetti una posizione GHL #

DELETE /channels/ghl/{locationId}

Elimina la connessione qui, interrompendo ogni sincronizzazione e trigger per quella posizione. Questo non disinstalla l’app dal lato GHL: il cliente la rimuove dalle installazioni del proprio marketplace GHL se desidera farlo anche lì.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Numeri di telefono (acquisto e rilascio) #

Invece di collegare un numero esistente, puoi acquistare direttamente un nuovo numero compatibile con WhatsApp. Cerca i numeri disponibili, acquistane uno, quindi esegui il polling finché il provisioning non è completato.

Passaggio 1 - Cerca numeri disponibili #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Risposta

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Ogni risultato mostra il costo una tantum purchase_credits e quello ricorrente monthly_credits. Un numero fornito dalla piattaforma costa almeno 50 crediti al mese, aumentando in base al prezzo mensile del gestore, addebitato all’acquisto e a ogni rinnovo. Cita il purchase_credits / monthly_credits restituito dalla ricerca; non calcolare mai il prezzo autonomamente. La prima ricerca su un nuovo account fornisce alcune risorse sottostanti, quindi potrebbe essere leggermente più lenta rispetto alle ricerche successive.

Passaggio 2 - Acquista un numero #

POST /phone-numbers

Utilizza un phone_number dai risultati della ricerca.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Risposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

Il numero inizia nello stato PURCHASED. La registrazione a WhatsApp procede quindi in background: PURCHASED -> PENDING -> ONLINE.

Se l’acquisto non riesce perché manca un indirizzo aziendale o non è impostato un altro dettaglio richiesto, riceverai un 400 con un error descrittivo. Configura il dettaglio mancante e riprova.

Passaggio 3 - Esegui il polling fino allo stato ONLINE #

GET /phone-numbers/{phoneNumber}/status

Questo è l’endpoint condiviso per lo stato del numero di telefono: funziona sia per i numeri WhatsApp acquistati che per gli altri numeri collegati.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Risposta

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Passaggio 4 - Rilascia un numero #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "phone_number": "+14155551234", "released": true }

Ciò che accade dipende dall’appartenenza del numero.

Per un numero noleggiato tramite la piattaforma, si tratta di un rilascio effettivo: il mittente WhatsApp viene deregistrato, il numero viene restituito all’operatore e rimosso dall’account, viene applicato un periodo di raffreddamento di 7 giorni durante il quale il numero non può essere riacquistato da nessuno e non vengono rimborsati crediti.

Per un numero gestito direttamente dall’account (il proprio account Twilio, la propria app Meta o account WhatsApp Business, o un gateway SMS Android), la stessa chiamata lo rimuove solo dall’account. Nulla viene rilasciato presso il provider a monte e non viene scritto alcun periodo di raffreddamento, quindi il numero può essere riconnesso immediatamente. La sua registrazione come mittente WhatsApp, se presente, potrebbe sopravvivere o meno: la procedura di rimozione tenta di eliminare il mittente utilizzando le credenziali Twilio gestite dalla piattaforma dell’account. Su un account ancora con la configurazione gestita, tali credenziali sono valide e il mittente viene eliminato, quindi riconnetterlo significa registrarlo nuovamente. Su un account che è passato al proprio Twilio, l’eliminazione non può autenticarsi e il mittente rimane registrato in quell’account; la riconnessione consiste quindi semplicemente nel riassociare il mittente esistente.

Aggiungi un numero che già possiedi (BYO) #

POST /phone-numbers/byo

Salta completamente il flusso di ricerca e acquisto sopra descritto. Usalo quando l’account porta il proprio numero (il proprio Twilio, il proprio account Meta WhatsApp Business o un gateway SMS Android) invece di noleggiarne uno tramite la piattaforma. Questo registra solo il numero: non vengono addebitati crediti e non viene effettuato alcun provisioning con un provider. Il numero rimane inattivo finché il titolare dell’account non completa l’OAuth di WhatsApp per registrare un mittente su di esso (lo stesso flusso avviato dal pulsante “Porta il tuo numero” della dashboard).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Risposta (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

Un phone_number che non è un numero E.164 reale (o che sembra il numero di test WhatsApp di Meta, che non può mai inviare messaggi a clienti reali) restituisce 400. L’aggiunta di un numero già esistente nell’account, anche se scritto in modo leggermente diverso, come le forme +52 e +521 del Messico, restituisce 409 invece di creare una riga duplicata.

Imposta un numero come primario #

POST /phone-numbers/{phoneNumber}/set-primary

Imposta un numero su is_active: true e tutti gli altri numeri dell’account su is_active: false, in modo atomico: l’account non si ritroverà mai con due numeri attivi, o nessuno, a metà richiesta. is_active non può essere impostato tramite l’endpoint di aggiornamento generale di proposito; questa chiamata dedicata è l’unico modo per modificare quale numero è primario.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number qui è l’oggetto numero completo (la stessa forma restituita da GET /phone-numbers), non solo la stringa. Un phoneNumber non presente nell’account restituisce 404.

Rimuovi il record di un numero (senza rilasciarlo) #

DELETE /phone-numbers/{phoneNumber}/record

Una semplice eliminazione del record del numero su questo account: nessun rilascio o de-registrazione lato provider e nessun periodo di raffreddamento di 7 giorni come quello applicato per la procedura di rilascio sopra descritta. Usalo per cancellare record BYO, WhatsApp Web, Telegram o LINE, o una voce obsoleta, senza passare attraverso il flusso di rilascio gestito. A differenza di un rilascio, eliminare un numero che non è presente nell’account è un 404, non un successo silenzioso.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Risposta

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Instradare un canale verso una campagna #

La connessione di un canale porta i messaggi all’interno dell’account. Non decide quale Agente IA risponderà.

L’instradamento è gestito dai Punti di Ingresso (Entry Points) su un Agente IA, non dalle campagne. Ogni canale ha un Punto di Ingresso predefinito che indica l’Agente che risponde ai nuovi contatti sconosciuti su quel canale:

Finché un canale non dispone di un Entry Point, un primo messaggio da qualcuno con cui non hai mai parlato viene comunque archiviato, ma nulla lo preleva e nessun assistente risponde. Questo è il passaggio che manca alla maggior parte delle integrazioni: collegare Instagram e creare un Agente non è sufficiente di per sé — devi anche indirizzare il canale verso l’Agente. L’insieme completo di chiamate — inclusi un Agente per numero WhatsApp, parole chiave e regole per i commenti — si trova nell’API degli Entry Point.

POST /channels/campaign scrive ancora la mappa di instradamento legacy delle campagne per canale, documentata di seguito, ma tale mappa non viene più consultata per l’instradamento in entrata su nessun account; è conservata solo per il rollback. Non basare lo sviluppo su di essa.

Instrada uno o più canali (mappa di instradamento legacy delle campagne) #

POST /channels/campaign

Campi della richiesta

Lo slot di instradamento e l’elenco enabled_channels della campagna vengono aggiornati insieme in un’unica operazione atomica, in modo che non possano mai divergere. Un canale già instradato verso una campagna diversa viene semplicemente reindirizzato verso questa.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
    "channels": ["instagram", "messenger"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Risposta

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

Condizioni necessarie affinché l’instradamento si attivi effettivamente #

Su un account che legge ancora la mappa di instradamento legacy delle campagne, l’instradamento ha successo come chiamata API, ma tre elementi sulla campagna decidono se un messaggio in entrata reale riceverà risposta. Controllali tutti e tre quando un canale instradato rimane silenzioso.

La corrispondenza delle parole chiave ora risiede nei Punti di Ingresso: crea un Punto di Ingresso di tipo keyword sull’Agente IA che dovrebbe rispondere.

Una campagna per canale #

Ogni canale detiene esattamente uno slot di instradamento legacy. L’instradamento di una seconda campagna sullo stesso canale ripunta silenziosamente lo slot e restituisce 200: non c’è alcun errore di conflitto. La campagna precedente continua a gestire i contatti che ha già; smette semplicemente di riceverne di nuovi.

Cancella il routing di un canale #

DELETE /channels/campaign/{channel}

Rimuove il routing per un singolo canale, indipendentemente dalla campagna a cui punta attualmente, e rimuove il canale dal enabled_channels di quella campagna. I nuovi contatti sconosciuti sul canale non vengono più presi in carico da alcuna campagna. I contatti già presenti nella campagna continuano come prima.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Risposta

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

È idempotente: cancellare un canale che non è mai stato instradato restituisce comunque 200, con cleared: false e campaign_id: null. Questo endpoint richiede la funzionalità campagne in entrata nel piano; senza di essa si ottiene un 403.

Usa la tua app Meta (Instagram + Messenger) #

Per impostazione predefinita, la connessione Instagram + Messenger viene eseguita tramite l’app Meta della piattaforma, quindi il nome di tale app è ciò che il titolare dell’account vede nella schermata di consenso di Facebook. Se desideri che la schermata di consenso mostri invece il tuo brand, puoi registrare la tua app Meta e instradare l’intero flusso attraverso di essa. Una volta configurata, si applicherà al tuo account: nulla cambia nelle chiamate di connessione sopra indicate, eccetto il branding.

Questo riguarda solo Instagram + Messenger. Le connessioni a WhatsApp, WhatsApp Web, Telegram e LINE non sono influenzate da un’app Meta personalizzata.

Di cosa ha bisogno la tua app per iniziare #

Questa è la parte che richiede tempo e avviene interamente lato Meta:

1. Un’app di tipo Business, con i prodotti Messenger e Instagram aggiunti.
2. Accesso avanzato (tramite Meta App Review) per: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Senza l’accesso avanzato, solo le persone che ricoprono un ruolo nella tua app possono completare la connessione: le connessioni dei tuoi clienti falliranno. L’App Review richiede solitamente alcune settimane e la verifica dell’attività commerciale (Business Verification).
3. Una configurazione di Facebook Login for Business creata all’interno della tua app, che conceda le stesse autorizzazioni. Il suo ID di configurazione numerico è specifico per ogni app, quindi devi crearne uno tuo.

Se alla tua app manca una delle autorizzazioni richieste, la connessione fallisce al momento del collegamento con un errore chiaro che indica cosa manca (visibile nel poll /status come byo_app_missing_permissions), invece di sembrare funzionante e fallire al primo messaggio.

Passaggio 1 - Salva la tua app #

PUT /account-config/meta-app

Tutti e tre sono necessari per il flusso di accesso a Facebook. Se esegui solo la corsia di push del token di accesso a Instagram descritta più avanti, puoi ometterli completamente.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Risposta

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Passaggio 2 - Configura la tua app per comunicare con noi #

Nella dashboard della tua app Meta:

1. Webhooks - per entrambi i prodotti Instagram e Messenger, imposta l’URL di callback sul valore webhook_urls corrispondente dalla risposta e il token di verifica su verify_token. Iscriviti ai campi messages, messaging_postbacks e comments.
2. URI di reindirizzamento OAuth validi - aggiungi https://api.youraiconnector.com/v1/auth-meta-callback-handler in modo che il flusso di consenso possa tornare indietro.

GET /account-config/meta-app restituisce sempre lo stesso materiale di configurazione; DELETE /account-config/meta-app rimuove l’app (le connessioni future torneranno all’app della piattaforma; rimuovi anche l’iscrizione al webhook all’interno della tua app).

Passaggio 3 - Connetti come di consueto #

Nient’altro cambia. POST /channels/meta/connect (e la pagina connect_url ospitata) utilizza automaticamente la tua app per il tuo account; il uses_byo_meta_app: true della risposta conferma quale app mostrerà la schermata di consenso. L’invio di messaggi, la selezione della pagina e le disconnessioni funzionano in modo identico.

Utilizza la tua app di accesso Instagram (push del token) #

La sezione precedente descrive il flusso di accesso a Facebook, in cui l’account si connette tramite una Pagina Facebook. Meta offre anche l’API di Instagram con accesso a Instagram (Business Login for Instagram): il titolare dell’account si autentica direttamente su Instagram, senza coinvolgere alcun account o Pagina Facebook.

Se la tua piattaforma utilizza già la propria app Meta con quel prodotto, non hai bisogno di alcun flusso OAuth da parte nostra. I tuoi clienti autorizzano la tua app e tu ci invii le credenziali completate per ogni account:

1. Salvi le credenziali della tua app Instagram una sola volta (così possiamo verificare i tuoi webhook).
2. Per ogni account, invii l’ID dell’account professionale Instagram + il token utente Instagram a lunga durata ottenuto dalla tua app.
3. Indirizzi il webhook di messaggistica Instagram della tua app verso di noi. Gli eventi per gli account che non hai mai inviato vengono riconosciuti e ignorati.
4. Gestisci tu il ciclo di vita del token: aggiorna i token nel tuo sistema e invia ogni token aggiornato con la stessa chiamata. Noi non aggiorniamo mai un token inviato.

Di cosa ha bisogno la tua app per iniziare #

• Il prodotto Instagram (“API setup with Instagram login”) aggiunto alla tua app Meta. Quel prodotto ha la sua coppia di App ID e App Secret, distinta dall’App ID/Secret di Facebook: li trovi nel pannello di configurazione del prodotto.
• Accesso avanzato (tramite Meta App Review) per instagram_business_basic e instagram_business_manage_messages (aggiungi instagram_business_manage_comments se utilizzi l’automazione dei commenti). Senza di esso, solo le persone con un ruolo nella tua app possono autorizzarla.

Passaggio 1 - Salva le credenziali della tua app Instagram #

Stesso endpoint di cui sopra: invia la coppia Instagram a PUT /account-config/meta-app. I campi Facebook non sono necessari per questa corsia: invia la coppia da sola se esegui solo l’accesso a Instagram, oppure insieme ai campi Facebook se li esegui entrambi. Un salvataggio descrive sempre l’intera impostazione, quindi qualsiasi set tu ometta verrà rimosso.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Risposta — contiene l’URL del webhook di accesso a Instagram (gli URL instagram e messenger appaiono solo quando vengono archiviati anche i campi Facebook):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

Nel pannello Webhooks della tua app per il prodotto Instagram, imposta il Callback URL su webhook_urls.instagram_login, il Verify token su verify_token e iscriviti ai campi messages e comments.

Passaggio 2 - Invia un token per account #

PUT /channels/instagram-login/token

Funziona con sub_account_id come ogni altro percorso, quindi una chiave di agenzia può eseguire il provisioning dell’intera flotta.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Risposta

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Come parte dell’invio, iscriviamo la tua app ai webhook di quell’account (subscribed_apps con il token inviato), in modo che i messaggi inizino a fluire senza alcuna chiamata aggiuntiva da parte tua.

Aggiornamento - invia il token aggiornato allo stesso endpoint con lo stesso ig_user_id; aggiorna il token memorizzato e la scadenza sul posto.

Conflitti - un account Instagram non è mai attivo su due connessioni. Se l’account è già connesso altrove, o su questo stesso account tramite il flusso della Pagina Facebook, il push restituisce un 409 che indica quale connessione disconnettere per prima. Una connessione tramite flusso Facebook non viene mai sostituita automaticamente, poiché potrebbe servire anche Messenger.

Passaggio 3 - Disconnetti quando un client esce #

DELETE /channels/instagram-login/token (stessa autenticazione e sub_account_id) annulla l’iscrizione ai webhook al meglio delle possibilità e rimuove la credenziale memorizzata. Ha sempre successo, anche quando il token è già scaduto — e una volta rimossa la credenziale, gli eventi webhook di quell’account vengono ignorati.

Suggerimenti per creare un wrapper affidabile #

• Esegui il polling con moderazione. Ogni pochi secondi è sufficiente. Fermati una volta raggiunto uno stato terminale (connected / ONLINE, o uno stato di errore) e imposta un timeout complessivo sensato sul ciclo (i passaggi del browser/QR scadono, vedi ogni expires_at).
• Codifica URL i numeri di telefono nel percorso. Il + iniziale deve essere inviato come %2B. Gli endpoint recuperano anche le cifre nude, ma la codifica è l’impostazione predefinita sicura.
• Non aspettarti mai di ricevere segreti. I token di accesso, i segreti del canale e i token di pagina vengono accettati o archiviati, ma non vengono mai restituiti in alcuna risposta.
• Gestisci il blocco di autenticazione. Un 403 significa che l’accesso API non è incluso nel piano, o che il canale che stai collegando non è incluso nel piano dell’account. Vedi Accesso API.
• Rispetta il limite di frequenza. Le richieste autenticate sono limitate a 300 al minuto; un 429 significa attendere e riprovare. Vedi Autenticazione.

Passaggi successivi #

• Autenticazione - le quattro forme di autenticazione accettate e il formato di errore.
• Accesso API - generazione e gestione della tua chiave API.