Aufbauen auf Conecto

Grundlagen

Base URL https://conecto.chat/api/v1. Create a credential in Einstellungen → Entwickler , Sie erhalten eine Client-ID und eine Secret (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"

Arbeiten Sie mit Python? Die offizielles SDK (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.

Ratenbegrenzung 300 Anfragen/Min. per credential (429 + Retry-After beyond it). Errors are always {"error": {"code", "message"}}. List endpoints paginate with limit und 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.

Ein Endpunkt beschreibt alle anderen

GET /schema/ gibt die gesamte Oberfläche als JSON zurück, jeden Endpunkt, jedes Ereignis, jeden Blocktyp, jede reservierte Aktion, jeden Fehlercode und jedes numerische Limit. Die Antwort wird von demselben Code bereitgestellt, der diese Grenzen durchsetzt, und kann daher nicht wie eine Dokumentationsseite vom laufenden Server abweichen. Generieren Sie Ihren Client daraus oder prüfen Sie beim Start, ob die benötigte Funktion bereitgestellt ist.

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.

Rich Content: Bilder, GIFs, Videos, Karten

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"}
      ]}
    ]
  }'

Blocktypen

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.

Ein GIF ohne vorhandenen Speicherort senden

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.

Ein Kartenkarussell

{"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"}]}
  ]
}]}

Bot-Kochbuch

Rezepte, die tatsächlich produktiv eingesetzt werden. Jedes besteht aus einem Webhook-Handler und einigen API-Aufrufen.

1 · Der Aktions-Bot, ändert Dinge in Ihr Software

Da der Webhook trifft Ihr -Server kann Ihr Bot alles tun, was Ihr Backend kann: in Ihre Datenbank schreiben, Ihr Abrechnungssystem aufrufen und einen Datensatz in Ihrer Buchhaltungssoftware aktualisieren. In Verbindung mit bestätigte Identität Sie genau wissen, wer fragt. Daher kann „Diese 250-Dollar-Quittung unter Marketing ablegen“ sicher ausgeführt werden:

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"])
}

Dasselbe Muster gilt für „meinem Plan einen Platz hinzufügen“, „mein Projekt umbenennen“ oder „Donnerstag einen Termin buchen“. Der Bot ist eine schlanke Konversationsschicht über Ihrer eigenen API. Möchten Sie lieber die integrierte KI statt eines eigenen Bots verwenden? Dieselben Endpunkte als Integration registrieren und die Conecto-KI ruft sie während der Unterhaltung mit derselben Identitätsprüfung auf, ohne dass Sie eine Zustandsmaschine pflegen müssen. Wenn Sie bereits MCP verwenden, funktioniert auch ein entfernter MCP-Toolserver: Dashboard → KI-Agenten → Integrationen.

2 · Bestellstatus-Bot

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 zur Ticketvermeidung

Zuerst das Hilfe-Center durchsuchen; nur ein Ticket öffnen, wenn nichts passt:

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 zur Leadqualifizierung

// 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 · Proaktive Lifecycle-Nachrichten

An eine Besuchersitzung senden, ohne auf eine Nachricht zu warten, etwa Versandupdates, Testhinweise oder Warenkorbwiederherstellung:

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 · Ein unbekannter Shop, mit der KI verbunden

Kein Webhook, keine Zustandsmaschine: Deklarieren Sie die reservierte Katalogaktion, verweisen Sie auf Ihren Suchendpunkt, und die KI empfiehlt Artikel aus Ihrem Katalog mit echten Produktkarten.

// 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,
    })) })
})

Das ist die gesamte Integration. Die Karten, die Home-Auswahl, die Vorgabe „vor dem Erwähnen eines Produkts erneut aufrufen“ und die Regel gegen rohe URLs aus dem Modell gehören automatisch zum reservierten Namen.

7 · CSAT-Nachverfolgung

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")
}

Endpunktreferenz

Gespräche und Nachrichten

Integrationen, Ihre eigene Software als vollwertige Integration

Medien

Tickets

Kontakte, Ihre Benutzerdatenbank synchronisieren

Besucher, Identität und Personalisierung

Wissensdatenbank

Konfiguration und Metadaten

Webhooks

Manage in the dashboard or via GET/POST /webhooks/ und 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:

Die Zustellung erfolgt mindestens einmal und ungeordnet. 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? Sprechen Sie mit uns , wir möchten, dass Entwickler auf Conecto aufbauen, und priorisieren ihre Wünsche.