Construire sur Conecto

Les bases

Base URL https://conecto.chat/api/v1. Create a credential in Paramètres → Développeurs , vous obtenez un identifiant client et un 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"

Vous utilisez Python? Le SDK officiel (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 de débit 300 requêtes/min per credential (429 + Retry-After beyond it). Errors are always {"error": {"code", "message"}}. List endpoints paginate with limit et 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 point de terminaison décrit tous les autres

GET /schema/ renvoie toute la surface sous forme de JSON: chaque point de terminaison, événement, type de bloc, action réservée, code d’erreur et limite numérique. La réponse est servie par le même code qui applique ces limites; elle ne peut donc pas s’écarter du serveur en cours d’exécution comme une page de documentation. Générez votre client à partir de cette réponse ou vérifiez au démarrage que la fonctionnalité requise est déployée.

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.

Contenu enrichi: images, GIF, vidéos et cartes

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

Les types de blocs

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.

Envoyer un GIF sans emplacement d’hébergement

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 carrousel de cartes

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

Livre de recettes des bots

Des recettes réellement utilisées en production. Chacune comprend un gestionnaire de webhook et quelques appels API.

1 · Le bot d’action, modifie des données dans votre logiciel

Comme le webhook atteint votre peut tout faire sur votre serveur que votre backend sait faire: écrire dans votre base de données, appeler votre système de facturation ou modifier une entrée dans votre logiciel comptable. Combiné à identité attestée vous savez exactement qui pose la question. «Classer ce reçu de 250 $ dans Marketing» peut donc être exécuté en toute sécurité:

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

Le même modèle couvre «ajouter une place à mon offre», «renommer mon projet» ou «réserver un créneau jeudi». Le bot n’est qu’une fine couche conversationnelle sur votre propre API. Vous préférez utiliser l’IA intégrée plutôt que créer un bot? Enregistrer les mêmes points de terminaison comme intégration et l’IA de Conecto les appelle en cours de conversation, derrière la même vérification d’identité, sans machine à états à maintenir. Si vous utilisez déjà MCP, un serveur d’outils MCP distant fonctionne aussi: Tableau de bord → Agents IA → Intégrations.

2 · Bot de suivi de commande

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 de déviation des tickets

Rechercher d’abord dans votre centre d’aide; ouvrir un ticket seulement si aucun résultat ne correspond:

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 de qualification des prospects

// 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 · Messages proactifs du cycle de vie

Envoyer à une session de visiteur sans attendre son message, par exemple mises à jour d’expédition, rappels d’essai ou récupération de panier:

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 · Une boutique inconnue, connectée à l’IA

Aucun webhook ni machine à états: déclarez l’action de catalogue réservée, dirigez-la vers votre point de terminaison de recherche, et l’IA recommande des articles de votre catalogue avec de véritables cartes produit.

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

Voilà toute l’intégration. Les cartes, la sélection Accueil, la règle «appeler à nouveau avant de mentionner un produit» et l’interdiction pour le modèle de coller des URL brutes accompagnent automatiquement le nom réservé.

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

Référence des points de terminaison

Conversations et messages

Intégrations, votre propre logiciel comme intégration de premier ordre

Médias

Tickets

Contacts, synchronisez votre base d’utilisateurs

Visiteurs, identité et personnalisation

Base de connaissances

Configuration et métadonnées

Webhooks

Manage in the dashboard or via GET/POST /webhooks/ et 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 livraison est au moins une fois et sans ordre garanti. 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? Parlez-nous , nous voulons que les développeurs construisent sur Conecto et nous donnons la priorité à leurs demandes.