Guide

Panoramica API

Introduzione alle API REST e agli eventi webhook di Userbot
Visualizza come Markdown

Le API Userbot consentono di integrare conversazioni chatbot con sistemi esterni in modo programmatico: inviare messaggi, gestire sessioni, eseguire pipeline di automazione e ricevere eventi in tempo reale. Sono pensate per partner B2B che vogliono incorporare l’intelligenza conversazionale Userbot nei propri prodotti — CRM, portali, app — mantenendo controllo su UX e flussi di business.

L’integrazione si articola su due superfici complementari e obbligatorie: la REST API per inviare messaggi e gestire le sessioni, e i webhook in dashboard per ricevere le risposte dell’agente e tutti gli aggiornamenti di conversazione.

Base URL

Tutte le richieste REST vanno inviate a:

https://api.userbot.ai

Le chiamate usano HTTPS obbligatorio e payload JSON (Content-Type: application/json), salvo gli endpoint con upload file che accettano multipart/form-data. Non esiste un ambiente sandbox separato: usa isTestChat: true per conversazioni di prova senza impattare le statistiche.

Come funziona l’integrazione

Il flusso di integrazione corretto separa invio e consegna:

  1. Autenticazione — ogni richiesta REST include un Access Token Bearer nell’header Authorization. Il token si genera dalla dashboard (Autenticazione).
  2. Invio messaggi (REST) — il backend partner invia i messaggi utente con webhookOnly: true. La risposta REST restituisce ack e session ID, non il contenuto chat da mostrare in UI (REST API).
  3. Ricezione risposte (webhook) — registra un endpoint HTTPS in dashboard. Userbot consegna lì tutti i messaggi (message.added), i cambi di stato e le variabili aggiornate (Ricevere eventi webhook).

Salva sempre il session ID restituito dalla REST API: serve per continuare una conversazione e correlare gli eventi webhook. Aggiorna la UI chat solo dagli eventi message.added, non dal body della risposta REST.

Guide

Le guide sotto approfondiscono ogni aspetto dell’integrazione. Parti da Autenticazione e Quickstart se è la prima volta; usa le altre come riferimento durante lo sviluppo.

Autenticazione

Access Token, Secret Key e header Authorization — come ottenere e usare le credenziali

Ricevere eventi webhook

Setup endpoint, tipi di evento, struttura payload ed esempio server

Verifica firma HMAC

Autenticità e integrità dei webhook in ingresso — obbligatoria in produzione

Rate limiting

Limiti di frequenza, header informativi e gestione risposta 429

Codici di errore

Tabella degli status HTTP e come interpretarli

REST API

Reference interattiva di tutti gli endpoint con esempi di request e response

Buone pratiche

Prima di andare in produzione, verifica di aver coperto questi punti:

UI chat da webhook — Popola la chat solo con eventi message.added verificati HMAC, non dalla risposta REST

Verifica firma HMAC — Su ogni webhook in ingresso — vedi Verifica firma HMAC

Deduplicazione — Per eventId (e/o data.messageId per message.added) per evitare elaborazioni duplicate

Risposta 200 entro 5 secondi — Ai webhook; elaborazioni pesanti in modo asincrono dopo la conferma

Retry con backoff — In caso di risposta 429, rispettando Retry-After — vedi Rate limiting

Access Token solo lato server — Mai esposto in client-side (browser, app mobile)

Per una checklist completa su credenziali, ambienti e privacy: Sicurezza e best practice.