Documentazione per sviluppatori

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.

html
<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():

javascript
// 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

MetodoParametriDescrizione
chat33.track(event, metadata?)event: string, metadata: objectInvia un evento personalizzato
chat33.identify(contactId)contactId: stringImposta 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

http
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

CampoTipoObbligatorioDescrizione
eventstringSìNome dell’evento (purchase, signup, lead e così via)
contactIdstringNoID del contatto Chat33 per l’attribuzione
valuenumberNoValore monetario dell’evento
currencystringNoCodice della valuta (USD, EUR e così via)
metadataobjectNoQualsiasi dato aggiuntivo

Esempi

bash
# 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"}'
javascript
// 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.

bash
# All API requests require this header:
x-api-key: sk_live_your_api_key_here

Piattaforme supportate

Instagram

Foto, reel, caroselli (tramite IG Graph API)

Facebook

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)

LinkedIn

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

bash
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.

json
{
  "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.
  • articleUrl vale 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

bash
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.

bash
# 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 post

Riferimento API

MetodoEndpointDescrizione
POST
/api/v1/postsCrea e metti in coda uno o più post
GET
/api/v1/postsElenca i post (paginati, filtrabili)
GET
/api/v1/posts/:idOttieni i dettagli di un post
PATCH
/api/v1/posts/:idModifica una bozza o un post in coda, oppure annullalo
DELETE
/api/v1/posts/:idElimina una bozza o annulla un post
POST
/api/v1/posts/:id/duplicateDuplica un post
POST
/api/v1/media/uploadCarica un file multimediale (file sotto i 4,5 MB, oppure URL pubblico)
POST
/api/v1/media/upload-urlURL prefirmato per caricare direttamente un file locale di grandi dimensioni

Corpo della richiesta: crea un post

CampoTipoObbligatorioDescrizione
accountIdsstring[]SìID dei canali su cui pubblicare (massimo 10)
textstringNoDidascalia / descrizione del post
mediaUrlsstring[]NoURL dei file multimediali (caricati con /media/upload)
mediaTypestringNoimage, video, reel o carousel
scheduledAtstringNoData e ora in formato ISO 8601 per la programmazione
callbackUrlstringNoURL del webhook per le notifiche di pubblicazione
platformConfigobjectNoOpzioni specifiche della piattaforma (titolo YouTube, privacy e così via)
coverImageUrlstringNoImmagine 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

  1. Crea un profilo per l’utente (POST /v1/profiles), oppure riusane uno, identificato dal tuo externalId.
  2. Richiedi un link di connessione per quel profilo e una piattaforma (POST /v1/connect). Vale una sola volta, per 15 minuti.
  3. Manda l’utente all’url restituito. Approva nella schermata della piattaforma, che indica Chat33 come l’app che chiede l’accesso: è previsto, e nessuno vede la sua password.
  4. Torna al tuo redirectUrl con status, profileId e accountIds (oppure status=error&code=… se ha annullato o qualcosa è andato storto: un consenso annullato non consuma il link).

Crea un profilo

bash
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

bash
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 screen

Cosa 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.

json
// 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

MetodoEndpointDescrizione
GET
/api/v1/profilesElenca i tuoi utenti finali
POST
/api/v1/profilesCrea (o trova, tramite externalId) un utente finale
GET
/api/v1/profiles/:idOttieni un profilo e i suoi account
PATCH
/api/v1/profiles/:idAggiorna il nome o l’externalId di un profilo
DELETE
/api/v1/profiles/:idScollega i suoi account ed elimina il profilo
POST
/api/v1/connectCrea un link di connessione monouso per un profilo
GET
/api/v1/accounts?source=apiElenca 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/:idScollega 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/connectionsSaldo crediti, importo da saldare e storico degli slot
POST
/api/v1/billing/slotsAcquista 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.

text
https://chat33.io/api/webhooks/mmp?secret=YOUR_SECRET

MMP 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.

1

Aggiungi il passaggio di download

Nella tua automazione, aggiungi Invia un link di download dell’app con i link di tracciamento del tuo MMP

2

Configura l’MMP

Imposta l’URL del postback in AppsFlyer, Adjust, Branch (un webhook per l’evento Install), Tenjin o Singular

3

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

text
https://apps.apple.com/app/apple-store/id<APP_ID>?pt=<PROVIDER_TOKEN>&ct=<campaign_name>&mt=8

Google Play: i tag UTM vanno dentro referrer, codificati come URL

text
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.

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.

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.