Crea su Conecto

Concetti di base

Base URL https://conecto.chat/api/v1. Create a credential in Impostazioni → Sviluppatori , ottieni un ID client e un segreto (shown once, stored hashed). Authenticate with HTTP Basic — client ID as username, secret as password — or Authorization: Bearer <client_id>:<secret>. A credential can cover the whole workspace or be scoped to a single widget.

curl https://conecto.chat/api/v1/me/ -u "ck_your_client_id:cs_your_secret"

Usi Python? Il SDK ufficiale (pip install conecto) wraps all of this, and does the parts that are easy to get subtly wrong for you: webhook signature verification, delivery deduplication, idempotent writes, retries, and block validation that fires before a request leaves your process. Everything below still applies — it is the same API underneath.

Limite di frequenza 300 richieste/min per credential (429 + Retry-After beyond it). Errors are always {"error": {"code", "message"}}. List endpoints paginate with limit e before_id, returning next_before_id. Write endpoints accept an Idempotency-Key header (any UUID): retry the same key and you get the message that was already created, with a 200 instead of a 201, rather than a second copy in front of the visitor.

Un endpoint descrive tutti gli altri

GET /schema/ restituisce l’intera superficie come JSON: ogni endpoint, evento, tipo di blocco, azione riservata, codice di errore e limite numerico. È servito dallo stesso codice che applica questi limiti, quindi non può divergere dal server in esecuzione come una pagina di documentazione. Genera il client da qui o verifica all’avvio che la funzione necessaria sia distribuita.

curl https://conecto.chat/api/v1/schema/ -u "ck_...:cs_..." | jq '.limits, .events[].name'

Every response carries X-Conecto-Api-Version. Pin it in your client and log a warning when it changes — that header is how you find out a field moved before your users do.

Contenuti avanzati: immagini, GIF, video e schede

Any message you send can carry blocks — an ordered list of typed content rendered under the bubble in the widget, and in the agent's inbox exactly as the visitor saw it. Up to 10 per message, and every field is validated and re-projected server-side, so you never hand us markup and we never hand the browser a string.

curl -X POST https://conecto.chat/api/v1/conversations/42/messages/ \
  -u "ck_...:cs_..." -H "Content-Type: application/json" \
  -d '{
    "body": "Here is how to reset it — takes about 20 seconds:",
    "blocks": [
      {"type": "image", "url": "https://cdn.you.com/reset.gif", "alt": "Reset flow"},
      {"type": "buttons", "items": [
        {"label": "That worked"},
        {"label": "Full guide", "url": "https://docs.you.com/reset"}
      ]}
    ]
  }'

Tipi di blocchi

URLs must be https. A block that can't be built is a 400 naming the block and the reason, never a silent drop — an image that vanishes without explanation costs an afternoon to track down.

Inviare una GIF senza un posto in cui ospitarla

POST /media/ takes a multipart file (≤10 MB) and hands back a URL you can drop straight into a block. Use the returned url — it is a path, resolved against the widget's own origin, so the same message works in development and in production.

URL=$(curl -s -X POST https://conecto.chat/api/v1/media/ -u "ck_...:cs_..." \
       -F "file=@celebrate.gif" | jq -r .media.url)

curl -X POST https://conecto.chat/api/v1/conversations/42/messages/ \
  -u "ck_...:cs_..." -H "Content-Type: application/json" \
  -d "{\"body\": \"All set!\", \"blocks\": [{\"type\": \"image\", \"url\": \"$URL\"}]}"

Shipping a GIF as a muted, looping video block is usually the better trade: a tenth of the bytes, and the visitor cannot tell the difference.

Un carosello di schede

{"blocks": [{
  "type": "cards",
  "items": [
    {"title": "Trail Runner 2", "subtitle": "Road · Neutral",
     "price": "89.00 USD", "badge": "Back in stock",
     "image": "https://cdn.you.com/tr2.jpg",
     "url": "https://shop.you.com/p/tr2",
     "buttons": [{"label": "Add to cart", "url": "https://shop.you.com/cart/add/tr2"}]}
  ]
}]}

Ricettario per bot

Ricette realmente portate in produzione. Ciascuna comprende un gestore di webhook e poche chiamate API.

1 · Il bot di azione, modifica elementi in tuo software

Poiché il webhook raggiunge tuo può fare sul tuo server tutto ciò che può fare il backend: scrivere nel database, chiamare il sistema di fatturazione o aggiornare una voce nel software di contabilità. Insieme a identità attestata sai esattamente chi sta chiedendo. Perciò «archivia questa ricevuta da 250 $ in Marketing» può essere eseguito in sicurezza:

async function handle({ conversation, visitor, message }) {
  const convo = conversation.id

  // "file 250 under Marketing" — your parsing, your rules
  const cmd = parseAccountingCommand(message.body)
  if (!cmd) return reply(convo, "Tell me e.g. 'file 250 under Marketing'.")

  // Only act for users YOUR backend has vouched for (logged in on your site)
  if (!visitor.verified)
    return reply(convo, "Please sign in first, then ask me again.", ["Log in"])

  await ledger.addEntry({            // <- YOUR accounting system
    account: cmd.account,
    amount:  cmd.amount,
    user:    visitor.verified_email, // identity Conecto guarantees
  })
  await reply(convo,
    `Done — $${cmd.amount} filed under ${cmd.account}. Anything else?`,
    ["Show this month's entries", "Undo that"])
}

Lo stesso schema vale per «aggiungi una postazione al mio piano», «rinomina il mio progetto» o «prenota un appuntamento giovedì». Il bot è un sottile livello conversazionale sopra la tua API. Preferisci usare l’IA integrata invece di scrivere un bot? Registra gli stessi endpoint come integrazione e l’IA di Conecto le chiama durante la conversazione con la stessa verifica dell’identità, senza una macchina a stati da mantenere. Se usi già MCP, funziona anche un server remoto di strumenti MCP: Dashboard → Agenti IA → Integrazioni.

2 · Bot sullo stato degli ordini

if (/where.*order|track/i.test(message.body)) {
  await typing(convo, 'OrderBot', true)
  const order = await shop.lastOrder(visitor.email)     // your store
  await reply(convo, order
    ? `Order #${order.id} is ${order.state} — arriving ${order.eta}.`
    : "I couldn't find an order for this email.",
    order ? [`Track #${order.id}`] : undefined)
}

3 · Bot per ridurre i ticket

Cerca prima nel centro assistenza; apri un ticket solo se non trovi corrispondenze:

const { articles } = await api('GET', '/articles/?q=' + q + '&published=true')
if (articles.length)
  await reply(convo, `This might help: “${articles[0].title}”. Did that solve it?`,
              ["Solved it", "Open a ticket"])
else
  await api('POST', `/conversations/${convo}/messages/`,
            { body: "Let's get this to the team.", ticket_form: true })

4 · Bot per la qualificazione dei lead

// no email yet? capture it natively, then enrich + route
if (!visitor.email)
  return api('POST', `/conversations/${convo}/messages/`,
             { body: "Happy to help — what's your work email?", ask_email: true })

await api('POST', '/contacts/', { email: visitor.email,
  custom_fields: { lead_source: 'chat', intent: classify(message.body) } })
await api('POST', `/conversations/${convo}/messages/`,
          { body: "Routing you to sales…", internal: true })
await api('POST', `/conversations/${convo}/assign/`, { user_id: SALES_USER_ID })
await api('POST', `/conversations/${convo}/handoff/`)

5 · Messaggi proattivi sul ciclo di vita

Invia a una sessione del visitatore senza attendere un messaggio, ad esempio aggiornamenti di spedizione, promemoria di prova o recupero del carrello:

curl -X POST https://conecto.chat/api/v1/widgets/7/visitors/$SESSION/message/ \
  -u "ck_...:cs_..." -H "Content-Type: application/json" \
  -d '{"body": "Your order shipped — want live tracking?",
       "buttons": ["Track my order"]}'

Cart recovery works the same way, with products putting the item itself back in front of them as a tappable card:

-d '{"body": "Still thinking it over? Your cart is saved:",
     "products": [{"title": "Trail Runner 2", "price_from": "89.00",
                   "currency": "USD", "image": "https://cdn.you.com/tr2.jpg",
                   "url": "https://shop.you.com/cart"}]}'

6 · Un negozio sconosciuto, collegato all’IA

Nessun webhook né macchina a stati: dichiara l’azione di catalogo riservata, indirizzala al tuo endpoint di ricerca e l’IA consiglia articoli del catalogo con vere schede prodotto.

// POST /conecto/search on your server
app.post('/conecto/search', verifyConectoSignature, async (req, res) => {
  const { query, limit = 4 } = req.body.arguments
  const hits = await catalog.search(query, { limit })     // <- YOUR catalog

  res.json({ ok: hits.length > 0, not_found: hits.length === 0,
    products: hits.map(p => ({
      title: p.name, url: p.permalink, image: p.thumbnail,
      price_from: p.price.toFixed(2), currency: p.currency,
      available: p.stock > 0,
    })) })
})

Questa è l’intera integrazione. Le schede, la selezione Home, la regola «richiamare prima di menzionare un prodotto» e il divieto per il modello di incollare URL non elaborate sono inclusi nel nome riservato.

7 · Follow-up CSAT

Subscribe to conversation.rated; thank promoters, rescue detractors:

if (event === 'conversation.rated') {
  if (data.rating.score <= 2)
    await api('POST', '/tickets/', { email: data.visitor.email,
      message: `Low CSAT (${data.rating.score}/5): ${data.rating.comment}`,
      priority: 'high' })
  else
    await push(data.widget.id, data.visitor.session,
               "Glad we could help! Here's 10% off your next order: THANKS10")
}

Guida agli endpoint

Conversazioni e messaggi

Integrazioni, il tuo software come integrazione di prima classe

Contenuti multimediali

Ticket

Contatti, sincronizza il database degli utenti

Visitatori, identità e personalizzazione

Base di conoscenza

Configurazione e metadati

Webhook

Manage in the dashboard or via GET/POST /webhooks/ e DELETE /webhooks/{id}/ (https only, ≤10 per workspace, optional per-widget scope). Deliveries carry X-Conecto-Event, X-Conecto-Delivery, X-Conecto-Timestamp and the HMAC signature, and time out after 2.5s — respond 200 fast, process async. Events:

La consegna è almeno una volta e senza ordine garantito. Every payload carries an id (also in X-Conecto-Delivery): store it, skip ids you have already handled, and both replays and duplicates stop being your problem. When your bot answers a delivery, pass that same id as the Idempotency-Key and a redelivery can never make it speak twice.

app.post('/conecto', express.raw({ type: '*/*' }), async (req, res) => {
  const sig = 'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body).digest('hex')
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(req.get('X-Conecto-Signature') || '')))
    return res.sendStatus(401)

  const { id, event, data } = JSON.parse(req.body)
  res.sendStatus(200)                        // ack first, work after
  if (await seen(id)) return                 // at-least-once: dedupe on the delivery id

  if (event === 'message.created' && data.message.sender === 'visitor') {
    await fetch(`https://conecto.chat/api/v1/conversations/${data.conversation.id}/messages/`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': id, ...auth },
      body: JSON.stringify({ body: await answer(data) }),
    })
  }
})

Everything here is designed to sit under an SDK: stable envelopes, slug-addressed integrations, typed errors, cursor pagination, idempotent writes, one signature scheme in both directions, and GET /schema/ to generate from. Building something? Parla con noi , vogliamo che gli sviluppatori creino su Conecto e diamo priorità alle loro richieste.