Chat API: invio messaggi programmatico

Introduzione

La Chat API di Chat G Tech Group permette di inviare messaggi, creare conversazioni, gestire contatti e operatori da codice esterno. Indispensabile per automazioni avanzate, bot custom, integrazioni bidirezionali con sistemi proprietari.

Autenticazione

L'API usa autenticazione Bearer Token. Genera la chiave da Impostazioni > API > Nuovo token. Specifica scope (read, write, admin) e durata (30 giorni, 1 anno, no scadenza). Conserva il token in modo sicuro: non viene mostrato di nuovo dopo la creazione.

Base URL

Endpoint base: https://chat.gtechgroup.it/api/v1. Tutte le richieste devono includere header:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Inviare un messaggio

Endpoint POST /conversations/{id}/messages:

{
  "content": "Ciao, abbiamo ricevuto il tuo ordine",
  "sender_type": "operator",
  "sender_id": 42,
  "private": false
}

Restituisce 201 con l'oggetto messaggio creato.

Creare nuova conversazione

Endpoint POST /conversations:

{
  "channel": "api",
  "contact_email": "mario@example.com",
  "contact_name": "Mario Rossi",
  "team_id": 5,
  "first_message": "Avviso automatico: spedizione in corso"
}

Recuperare conversazioni

Endpoint GET /conversations con query params:

• status: open, closed, pending
• team_id: ID team
• from_date: data inizio (ISO 8601)
• to_date: data fine
• limit: max 100 per pagina
• page: paginazione

Gestire contatti

Endpoints contatti:

• GET /contacts: lista contatti
• POST /contacts: crea contatto
• GET /contacts/{id}: dettaglio
• PUT /contacts/{id}: aggiorna
• DELETE /contacts/{id}: cancella (GDPR)

Allegati

Per inviare file, prima caricalo su POST /uploads (multipart form), ottieni l'URL e includilo nel messaggio con campo attachments. Max 25MB per file, formati supportati: immagini, PDF, DOCX, XLSX, audio.

Rate limiting

Limiti:

• 1000 richieste/minuto per token
• 5000 richieste/ora per token
• 50.000 richieste/giorno per token

Eccesso restituisce HTTP 429 con header Retry-After. Implementa backoff esponenziale.

Errori

Codici risposta principali:

• 200/201: successo
• 400: payload malformato
• 401: token mancante o invalido
• 403: scope insufficiente
• 404: risorsa non trovata
• 429: rate limit
• 500: errore server (riprova)

SDK ufficiali

Disponibili SDK per: PHP, Node.js, Python, Ruby. Scaricabili da API > SDK. Esempio PHP:

$client = new GTGChat\Client('YOUR_TOKEN');
$client->messages->send($convId, 'Ciao!');

Webhook + API

Pattern comune: webhook notifica nuovo messaggio cliente, il tuo backend processa con AI/business logic, API risponde via chat con messaggio operatore (anche bot). Combina i due strumenti per automazioni complesse.

Hai bisogno di aiuto?

Se vuoi attivare Chat G Tech Group sul tuo sito, scrivici tramite il modulo di contatto.