Integra Chat33
con il tuo stack.
Pixel di tracciamento, eventi webhook, postback di installazione MMP e tracciamento delle entrate. Tutto ciò che ti serve per collegare Chat33 al tuo sito o alla tua app.
Per iniziare
Per usare le integrazioni per sviluppatori di Chat33 ti serve un token MMP. Lo trovi nella dashboard, in Impostazioni → Integrazioni.
1. Prendi il tuo token
Vai in Impostazioni → Integrazioni → Token MMP. Clicca "Genera token" se non ne hai uno.
2. Scegli la tua integrazione
Sito web / web app
Usa il pixel di tracciamento per tracciare visualizzazioni di pagina, iscrizioni e acquisti.
App mobile
Usa i postback MMP (AppsFlyer, Adjust, Branch, Tenjin, Singular) per tracciare le installazioni.
Pixel di tracciamento
Traccia gli eventi del sito e attribuiscili alle conversazioni in DM
Installazione
Aggiungi questo tag script al <head> del tuo sito o prima di </body>. Sostituisci YOUR_PIXEL_KEY con la chiave del pixel che trovi in Impostazioni, Integrazioni. Non usare mai qui il tuo token MMP: è un segreto.
<script src="https://chat33.io/pixel.js" data-token="YOUR_PIXEL_KEY"></script>Traccia gli eventi
Il pixel traccia in automatico le visualizzazioni di pagina. Per tracciare eventi personalizzati (acquisti, iscrizioni e così via) usa il metodo chat33.track():
// Track a purchase with value
chat33.track("purchase", {
value: 49.99,
currency: "USD",
product: "Pro Plan"
});
// Track a signup
chat33.track("signup");
// Track a lead
chat33.track("lead", { source: "landing_page" });
// Track any custom event
chat33.track("tutorial_complete", { step: 5 });Come funziona
Smart Link
Chat33 aggiunge ?cid=xxx ai link tracciati nei DM
Attribuzione automatica
Il pixel legge l’ID del contatto dall’URL e lo conserva tra le pagine
Etichettatura automatica
Eventi come “purchase” assegnano in automatico un’etichetta al contatto nel tuo CRM
Riferimento API
| Metodo | Parametri | Descrizione |
|---|---|---|
| chat33.track(event, metadata?) | event: string, metadata: object | Invia un evento personalizzato |
| chat33.identify(contactId) | contactId: string | Imposta manualmente l’ID del contatto |
| chat33.getContactId() | — | Restituisce l’ID del contatto corrente |
API degli eventi webhook
Invia eventi personalizzati dal tuo server a Chat33
Endpoint
POST https://chat33.io/api/webhooks/events?token=YOUR_TOKEN
Content-Type: application/json
{
"event": "purchase",
"contactId": "cm1abc123...",
"value": 49.99,
"currency": "USD",
"metadata": {
"product": "Pro Plan",
"source": "checkout"
}
}Corpo della richiesta
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| event | string | Sì | Nome dell’evento (purchase, signup, lead e così via) |
| contactId | string | No | ID del contatto Chat33 per l’attribuzione |
| value | number | No | Valore monetario dell’evento |
| currency | string | No | Codice della valuta (USD, EUR e così via) |
| metadata | object | No | Qualsiasi dato aggiuntivo |
Esempi
# cURL
curl -X POST "https://chat33.io/api/webhooks/events?token=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event":"purchase","value":29.99,"currency":"USD"}'// Node.js / fetch
await fetch("https://chat33.io/api/webhooks/events?token=YOUR_TOKEN", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
event: "purchase",
contactId: "cm1abc123...",
value: 29.99,
currency: "USD",
}),
});Limite di frequenza: 100 eventi al minuto per token. Gli eventi vengono salvati come eventi di analisi e i contatti ricevono automaticamente un’etichetta in base al nome dell’evento (ad esempio "purchase" → etichetta "Purchased").
API di pubblicazione social
Programma e pubblica contenuti su Instagram, Facebook, TikTok, YouTube, X (Twitter), LinkedIn, Bluesky e Threads
Autenticazione
Genera una chiave API in Impostazioni → Chiavi API. Includila come header x-api-key in tutte le richieste.
# All API requests require this header:
x-api-key: sk_live_your_api_key_herePiattaforme supportate
Foto, reel, caroselli (tramite IG Graph API)
Testo, foto e video con programmazione nativa
TikTok
Video e post di foto tramite Content Posting API
YouTube
Caricamento di video con pubblicazione programmata nativa
X (Twitter)
Testo, foto, video e thread tramite X API v2 (usa i crediti)
Testo, anteprime di link, fino a 9 immagini o un video, pubblicati sul profilo personale del membro
Bluesky
Testo, anteprime di link, fino a 4 immagini o un video, tramite AT Protocol
Threads
Testo, immagini, video, caroselli fino a 20 elementi, sondaggi e tag di argomento
Crea un post
curl -X POST "https://chat33.io/api/v1/posts" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"accountIds": ["channel_id_here"],
"text": "Check out our new product! #launch",
"mediaUrls": ["https://your-blob-url.com/image.jpg"],
"mediaType": "image"
}'Opzioni per piattaforma (platformConfig)
Le impostazioni di ogni piattaforma vanno sotto una chiave con il nome della piattaforma. Vengono lette solo le chiavi delle piattaforme presenti in accountIds, quindi una sola richiesta può contenere le opzioni di più piattaforme. Ogni piattaforma accetta un override di text, così lo stesso post può avere un testo diverso su ciascun social.
Due comportamenti da conoscere prima della prima chiamata: youtube.madeForKids viene rifiutato se manca, invece di avere un valore predefinito, perché YouTube richiede la dichiarazione a ogni caricamento. E un post TikTok senza oggetto consent finisce nelle bozze dell’account invece di essere pubblicato.
{
"instagram": {
"text": "...", // caption for this platform only
"firstComment": "#tags #here" // posted right after publish
},
"facebook": {
"text": "..."
},
"linkedin": {
"text": "...",
"visibility": "PUBLIC", // or "CONNECTIONS" (1st-degree only)
"articleUrl": "https://...", // link card, ignored when the post has media
"mediaTitle": "...",
"mediaDescription": "..."
},
"youtube": {
"madeForKids": false, // REQUIRED for any YouTube channel
"privacyStatus": "public", // or "unlisted" / "private"
"title": "...",
"description": "...",
"tags": ["one", "two"], // up to 30
"categoryId": "22", // default: People & Blogs
"notifySubscribers": true
},
"x": {
"text": "...",
"thread": true, // split text into a thread
"splitOn": "---",
"replyControl": "everyone" // or "following" / "mentionedUsers"
},
"tiktok": {
"text": "...",
"consent": {
"publishMode": "DIRECT_POST", // or "MEDIA_UPLOAD" (drafts)
"privacyLevel": "SELF_ONLY", // required for DIRECT_POST
"disableComment": false,
"disableDuet": false,
"disableStitch": false,
"aiGenerated": false
}
}
}Particolarità di LinkedIn
- I post vengono pubblicati sul profilo personale del membro autenticato. Le Pagine aziendali richiedono la Community Management API di LinkedIn, che è una revisione separata e non è ancora supportata.
- Un post contiene fino a 9 immagini oppure 1 video, mai entrambi. Se superi il limite, la richiesta viene rifiutata e non tagliata in silenzio.
- La didascalia arriva a un massimo di 3000 caratteri. Video fino a 200 MB, immagini fino a 10 MB ciascuna.
articleUrlvale solo per i post di testo. I contenuti multimediali hanno la precedenza e il link viene ignorato.- L’accesso scade dopo 60 giorni e LinkedIn non rilascia un token di aggiornamento, quindi l’account va ricollegato a mano. Alla scadenza, la pubblicazione restituisce un chiaro errore di riconnessione.
- LinkedIn limita a 150 richieste API per membro al giorno e ogni immagine costa due chiamate in più, quindi il tetto riguarda le richieste, non il numero di post.
Programma un post
curl -X POST "https://chat33.io/api/v1/posts" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"accountIds": ["ig_channel_id", "fb_channel_id"],
"text": "Coming soon!",
"mediaUrls": ["https://your-blob-url.com/video.mp4"],
"mediaType": "video",
"scheduledAt": "2026-04-15T14:00:00Z",
"callbackUrl": "https://your-server.com/webhook"
}'Carica contenuti multimediali
Il caricamento multipart ha un limite rigido di 4,5 MB. I corpi più grandi vengono rifiutati con 413 FUNCTION_PAYLOAD_TOO_LARGE prima di arrivare all’API. Per file più grandi, importa da un URL pubblico oppure ottieni un URL prefirmato e carica direttamente nello storage.
# Small files (< 4.5MB): multipart upload
curl -X POST "https://chat33.io/api/v1/media/upload" \
-H "x-api-key: sk_live_your_key" \
-F "file=@photo.jpg"
# Large files, already on a public URL: URL ingestion (up to 4GB)
curl -X POST "https://chat33.io/api/v1/media/upload" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/large-video.mp4", "filename": "video.mp4"}'
# Large LOCAL file: presigned direct upload (up to 500MB per PUT)
# 1. ask for an upload URL
curl -X POST "https://chat33.io/api/v1/media/upload-url" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"filename": "video.mp4", "contentType": "video/mp4", "size": 16352652}'
# -> {"uploadUrl": "https://...", "headers": {"content-type": "video/mp4"}, ...}
# 2. PUT the bytes straight to storage (never touches the API)
curl -X PUT "<uploadUrl>" \
-H "Content-Type: video/mp4" \
--data-binary @video.mp4
# -> {"url": "https://....public.blob.vercel-storage.com/...", ...}
# pass that url in mediaUrls when creating the postRiferimento API
| Metodo | Endpoint | Descrizione |
|---|---|---|
POST | /api/v1/posts | Crea e metti in coda uno o più post |
GET | /api/v1/posts | Elenca i post (paginati, filtrabili) |
GET | /api/v1/posts/:id | Ottieni i dettagli di un post |
PATCH | /api/v1/posts/:id | Modifica una bozza o un post in coda, oppure annullalo |
DELETE | /api/v1/posts/:id | Elimina una bozza o annulla un post |
POST | /api/v1/posts/:id/duplicate | Duplica un post |
POST | /api/v1/media/upload | Carica un file multimediale (file sotto i 4,5 MB, oppure URL pubblico) |
POST | /api/v1/media/upload-url | URL prefirmato per caricare direttamente un file locale di grandi dimensioni |
Corpo della richiesta: crea un post
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| accountIds | string[] | Sì | ID dei canali su cui pubblicare (massimo 10) |
| text | string | No | Didascalia / descrizione del post |
| mediaUrls | string[] | No | URL dei file multimediali (caricati con /media/upload) |
| mediaType | string | No | image, video, reel o carousel |
| scheduledAt | string | No | Data e ora in formato ISO 8601 per la programmazione |
| callbackUrl | string | No | URL del webhook per le notifiche di pubblicazione |
| platformConfig | object | No | Opzioni specifiche della piattaforma (titolo YouTube, privacy e così via) |
| coverImageUrl | string | No | Immagine di copertina/anteprima per i video |
Limiti di frequenza: 50 post al minuto per organizzazione. Limiti giornalieri per canale: Instagram (25), Facebook (50), TikTok (20), YouTube (100), X (300).
Callback: quando un post viene pubblicato o non riesce, viene inviata una richiesta POST al tuo callbackUrl con l’ID del post, lo stato e l’URL del post esterno.
Specifica OpenAPI 3.1
Esplora gli endpoint in modo interattivo, più JSON leggibile dalle macchine per codegen, n8n e MCP.
Documentazione per AI · llms.txt
Documentazione in markdown per Claude, ChatGPT e Cursor. Copia e incolla, così l’AI genera chiamate API corrette.
Nodo n8n · nodo della community
Nodo ufficiale della community di n8n. Elenca gli account, crea e programma post, carica contenuti multimediali da qualsiasi workflow n8n. Installa n8n-nodes-chat33 da Impostazioni → Nodi della community.
Server MCP
Collega Claude, Cursor o qualsiasi client MCP a Chat33. Pubblica, estrai le statistiche e crea automazioni DM con il linguaggio naturale.
Collega gli account dei tuoi utenti
Fai collegare ai tuoi utenti i loro account Instagram, Facebook, TikTok, YouTube, X, LinkedIn, Bluesky o Threads tramite Chat33, poi pubblica per loro con l’API
L’API Connect per sviluppatori emette un link monouso che porta uno dei tuoi utenti alla schermata di consenso OAuth della piattaforma, per tuo conto, senza mai toccare la sua password. Dopo l’approvazione, l’account collegato si comporta come qualsiasi altro nell’API di pubblicazione social qui sopra: ci pubblichi, leggi le sue statistiche dove la piattaforma le fornisce e lo scolleghi, sempre limitatamente all’utente finale ("profilo") a cui appartiene.
Come funziona
- Crea un profilo per l’utente (
POST /v1/profiles), oppure riusane uno, identificato dal tuoexternalId. - Richiedi un link di connessione per quel profilo e una piattaforma (
POST /v1/connect). Vale una sola volta, per 15 minuti. - Manda l’utente all’
urlrestituito. Approva nella schermata della piattaforma, che indica Chat33 come l’app che chiede l’accesso: è previsto, e nessuno vede la sua password. - Torna al tuo
redirectUrlconstatus,profileIdeaccountIds(oppurestatus=error&code=…se ha annullato o qualcosa è andato storto: un consenso annullato non consuma il link).
Crea un profilo
curl -X POST "https://chat33.io/api/v1/profiles" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Fitness",
"externalId": "user_482"
}'Crea un link di connessione
curl -X POST "https://chat33.io/api/v1/connect" \
-H "x-api-key: sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"profileId": "prof_abc123",
"platform": "instagram",
"redirectUrl": "https://yourapp.com/oauth/done",
"skipIntro": false
}'
# -> {"url": "https://chat33.io/connect/...", "expiresAt": "...", "platform": "instagram", "profileId": "prof_abc123"}
# send your user to that url
# skipIntro: true returns a url that goes straight to the platform's consent screenCosa vede il tuo utente
Una pagina ospitata da Chat33 che nomina la tua app, seguita dalla schermata di accesso e consenso della piattaforma, che indica Chat33 come app che chiede l’accesso, non la tua. Così funziona OAuth ed è previsto. Può revocare l’accesso dalla piattaforma in qualsiasi momento.
Per saltare la pagina introduttiva e portare l’utente direttamente alla schermata di consenso della piattaforma, passa "skipIntro": true quando crei il link. Il link diventa un reindirizzamento immediato: stesso token, stessa scadenza di 15 minuti, stesso ritorno al tuo redirectUrl. Se lo salti, avvisa il tuo utente nella tua schermata che la pagina di consenso indicherà Chat33, e preferisci mandarlo con il clic su un pulsante piuttosto che con un link in un’email: i client di posta e le app di chat caricano i link in anticipo, e il precaricamento di un link skipIntro apre la finestra della piattaforma nello scanner (non consuma il token).
$1 per slot di connessione ogni 30 giorni. Uno slot viene acquistato dai tuoi crediti prepagati nel momento in cui un account si collega (o in anticipo con Acquista slot) e viene rinnovato ogni 30 giorni finché l’account resta collegato. Nessun calcolo proporzionale e nessun rimborso, ma uno slot liberato da una disconnessione resta tuo fino alla scadenza e lo prende il prossimo account che colleghi. Se il saldo non copre un rinnovo, l’account continua a funzionare per 7 giorni mentre l’importo risulta da saldare; dopo, viene messo in pausa finché non ricarichi. Gli account in pausa non vengono fatturati.
Regole
- Un account reale esiste una sola volta in tutto Chat33: non può essere collegato una seconda volta, né da te né da altri, né tramite l’API né dalla dashboard di Chat33.
- Gli account collegati tramite API non contano mai nel limite di canali del piano della tua organizzazione.
- I messaggi in arrivo e i commenti su questi account non vengono salvati né automatizzati da Chat33 (la v1 è solo per la pubblicazione).
- Facebook collega ogni Pagina a cui l’utente concede l’accesso; ogni Pagina è un account a sé e uno slot a sé.
- Instagram si collega tramite Instagram Login, per account business o creator.
- I post su X tramite account collegati attingono anch’essi al tuo saldo crediti, come i post degli account della tua dashboard.
Account in pausa
Un account il cui slot è rimasto non pagato per 7 giorni viene messo in pausa: la pubblicazione restituisce 402 account_paused con gli accountIds interessati; riprende in automatico quando ricarichi. POST /v1/posts, POST /v1/posts/validate e POST /v1/posts/:id/duplicate lo controllano subito, prima di mettere in coda qualsiasi cosa.
// 402
{
"error": "ACCOUNT_PAUSED",
"code": "account_paused",
"message": "These accounts are paused until outstanding connection charges are paid. Top up credits.",
"accountIds": ["chan_abc123"]
}Riferimento API
| Metodo | Endpoint | Descrizione |
|---|---|---|
GET | /api/v1/profiles | Elenca i tuoi utenti finali |
POST | /api/v1/profiles | Crea (o trova, tramite externalId) un utente finale |
GET | /api/v1/profiles/:id | Ottieni un profilo e i suoi account |
PATCH | /api/v1/profiles/:id | Aggiorna il nome o l’externalId di un profilo |
DELETE | /api/v1/profiles/:id | Scollega i suoi account ed elimina il profilo |
POST | /api/v1/connect | Crea un link di connessione monouso per un profilo |
GET | /api/v1/accounts?source=api | Elenca ogni account collegato dai tuoi utenti, in tutti i profili |
GET | /api/v1/accounts?profileId= | Elenca gli account collegati di un profilo |
DELETE | /api/v1/accounts/:id | Scollega un account |
GET | /api/v1/posts?profileId= | Elenca i post di un profilo |
GET | /api/v1/analytics/posts?profileId= | Statistiche aggregate dei post di un profilo |
GET | /api/v1/billing/connections | Saldo crediti, importo da saldare e storico degli slot |
POST | /api/v1/billing/slots | Acquista in anticipo slot di connessione |
Sei responsabile dei contenuti che pubblichi tramite gli account dei tuoi utenti e di avere il loro consenso. Chat33 può disattivare le chiavi API che mettono a rischio le sue app sulle piattaforme.
Attiva il permesso
Ottieni il permesso connect:write: crea una chiave in Impostazioni → Chiavi API e spunta Collega gli account dei tuoi utenti. È disattivato per impostazione predefinita su ogni chiave.
Postback di installazione MMP
Traccia le installazioni dell’app da AppsFlyer, Adjust, Branch, Tenjin o Singular
URL del postback
Configura questo URL nella dashboard del tuo MMP come endpoint del postback. Sostituisci YOUR_SECRET con il segreto webhook MMP che trovi in Impostazioni.
https://chat33.io/api/webhooks/mmp?secret=YOUR_SECRETMMP supportati
AppsFlyer
Legge event_type, app_id, appsflyer_id, af_sub1/af_sub2 per l’attribuzione
Adjust
Legge activity_kind (install, rejected_install, event), label e adid dalla callback, GET o POST. Per le entrate degli acquisti aggiungi il segnaposto revenue_float (non revenue, che è in centesimi) e currency
Branch
Legge gli eventi webhook (INSTALL, PURCHASE), gli ID dei dispositivi in user_data e il creator e il post che Chat33 aggiunge ai dati del link
Tenjin
Legge campaign_id, site_id per l’attribuzione
Singular
Legge network, source per l’attribuzione
Configurazione dello Smart Link
Usa il passaggio Invia un link di download dell’app nelle tue automazioni. Manda gli utenti iPhone al link dell’App Store e quelli Android al link di Google Play, e conta ogni tocco nella dashboard, per automazione. Incolla il link di tracciamento del tuo MMP (OneLink, Adjust, Branch, Singular o Tenjin) con un nome di campagna per ogni post, e il tuo MMP riporta le installazioni per post. Per le campagne con creator di Chat33, gli ID del contatto e del creator vengono aggiunti al link in automatico.
Aggiungi il passaggio di download
Nella tua automazione, aggiungi Invia un link di download dell’app con i link di tracciamento del tuo MMP
Configura l’MMP
Imposta l’URL del postback in AppsFlyer, Adjust, Branch (un webhook per l’evento Install), Tenjin o Singular
Traccia le installazioni
Tocchi per automazione in Chat33, installazioni per campagna nel tuo MMP, totali delle installazioni nella dashboard
Non hai un MMP? Usa i link di campagna degli store
Apple e Google contano gratis le installazioni per campagna. Metti un nome di campagna in ogni link dello store, uno per post, e incolla i link nel passaggio di download. Le installazioni compaiono in App Store Connect (App Analytics, Sources, Campaigns) e nella Play Console (report di acquisizione per campagna UTM), circa un giorno dopo e in forma aggregata.
App Store: generalo in App Store Connect, oppure costruiscilo
https://apps.apple.com/app/apple-store/id<APP_ID>?pt=<PROVIDER_TOKEN>&ct=<campaign_name>&mt=8Google Play: i tag UTM vanno dentro referrer, codificati come URL
https://play.google.com/store/apps/details?id=<PACKAGE>&referrer=utm_source%3Dchat33%26utm_medium%3Ddm%26utm_campaign%3D<campaign_name>Passo dopo passo: tracciamento gratuito delle installazioni senza un MMP.
Tracciamento dei link
Traccia i clic sui link inviati con le automazioni DM
Come funziona
Quando usi link tracciati nelle tue automazioni, Chat33 li racchiude in un URL di reindirizzamento che registra il clic prima di inoltrare alla destinazione. L’ID del contatto viene aggiunto come parametro della query, così le pagine successive possono riconoscere chi visita.
# Original URL in your flow:
https://yoursite.com/signup
# What gets sent to the user:
https://chat33.io/api/t?url=https://yoursite.com/signup&cid=cm1abc...&fid=flow123
# User is redirected to:
https://yoursite.com/signup?cid=cm1abc...&fid=flow123Parametri URL aggiunti
| Parametro | Descrizione |
|---|---|
| cid | ID del contatto Chat33 |
| fid | ID dell’automazione che ha generato il link |
| ch | ID del canale |
Consiglio: abbina il tracciamento dei link al pixel di tracciamento. Quando un utente clicca un link tracciato e arriva sul tuo sito, il pixel legge in automatico il parametro cid e attribuisce a quel contatto tutti gli eventi successivi.
Generatore di link di campagna UTM
Genera URL tracciati con parametri UTM per Google Analytics
Consiglio: usa i link UTM nei messaggi delle tue automazioni Chat33. Insieme al pixel di tracciamento vedrai in Google Analytics il percorso completo dal DM alla conversione.
Link di campagna per gli store
Genera link di download tracciati per l’App Store di Apple e Google Play
Lo trovi nell’URL di App Store Connect: apps.apple.com/app/id[QUESTO_NUMERO]
Per le campagne di Chat33: usa questi link nelle tue automazioni DM con il nodo Smart Link. Chat33 aggiunge in automatico l’ID del contatto e del creator, così le installazioni vengono attribuite alla tua campagna.
Integrazione con un MMP: se usi AppsFlyer, Adjust, Branch, Tenjin o Singular, usa invece i loro URL OneLink/di tracciamento e configura l’URL del postback di Chat33 nella dashboard del tuo MMP. Vedi la sezione Postback MMP.
Hai bisogno di aiuto con l’integrazione?
Il nostro team può aiutarti a configurare il tracciamento e a ottenere il massimo dagli strumenti per sviluppatori di Chat33.