RCSZilla Versione 1.0

API Messaggi in Arrivo

Leggi i messaggi SMS, WhatsApp ed Email ricevuti tramite l'API REST.

Panoramica

Questi endpoint ti permettono di recuperare i messaggi in arrivo ricevuti da RCSZilla โ€” SMS e WhatsApp tramite dispositivi Android, ed Email tramite polling IMAP. Usali per letture in blocco, sincronizzazione con un CRM o come alternativa ai webhook.

EndpointMetodoDescrizione
incoming_messagesGETElenco messaggi SMS e WhatsApp ricevuti.
incoming_emailsGETElenco email ricevute dalle caselle IMAP.
*
Per un polling efficiente, usa after_id invece di intervalli di date. Salva l'id piรน alto dall'ultima risposta e passalo alla chiamata successiva โ€” otterrai solo messaggi nuovi, senza duplicati.

Elenco SMS / WhatsApp in arrivo

GET /?endpoint=incoming_messages

Restituisce un elenco paginato di messaggi SMS e WhatsApp ricevuti dai tuoi dispositivi Android. Include informazioni su contatto e dispositivo.

Parametri di query

CampoTipoDescrizione
sincestring opzionale Data-ora ISO 8601. Solo messaggi ricevuti a o dopo questo momento.
untilstring opzionale Data-ora ISO 8601. Solo messaggi ricevuti a o prima di questo momento.
channelstring opzionale Filtra per canale: sms o whatsapp.
device_idint opzionale Filtra per ID dispositivo.
from_phonestring opzionale Filtra per numero di telefono del mittente (corrispondenza esatta).
after_idint opzionale Restituisci solo messaggi con ID maggiore di questo valore. Ideale per il polling incrementale.
limitint opzionale Risultati per pagina (1โ€“100). Predefinito: 50.
offsetint opzionale Offset di paginazione. Predefinito: 0.

Esempio di richiesta

curl "https://api.rcszilla.com/?endpoint=incoming_messages&after_id=208&limit=50" \
  -H "Authorization: Bearer YOUR-API-TOKEN"
curl "https://api.rcszilla.com/?endpoint=incoming_messages&since=2026-05-27T00:00:00Z&channel=sms&limit=20" \
  -H "Authorization: Bearer YOUR-API-TOKEN"
curl "https://api.rcszilla.com/?endpoint=incoming_messages&from_phone=%2B40712345678&limit=10" \
  -H "Authorization: Bearer YOUR-API-TOKEN"

Risposta

JSON
{
  "success": true,
  "total": 142,
  "limit": 50,
  "offset": 0,
  "messages": [
    {
      "id": 209,
      "channel": "sms",
      "from_phone": "+40712345678",
      "message": "Yes, I want to book an appointment for Monday",
      "received_at": "2026-05-27 14:30:05",
      "contact": {
        "id": 42,
        "name": "John Doe",
        "phone": "+40712345678"
      },
      "device": {
        "id": 6,
        "name": "Office Samsung"
      }
    },
    {
      "id": 208,
      "channel": "whatsapp",
      "from_phone": "+40798765432",
      "message": "Hello, do you have availability this week?",
      "received_at": "2026-05-27 14:25:12",
      "contact": null,
      "device": {
        "id": 6,
        "name": "Office Samsung"
      }
    }
  ]
}

Campi di risposta

CampoTipoDescrizione
idintID univoco del messaggio. Usa il valore piรน alto come after_id per il polling incrementale.
channelstringsms or whatsapp
from_phonestringNumero di telefono del mittente.
messagestringTesto del messaggio.
received_atstringQuando il messaggio รจ stato ricevuto.
contactobject|nullContatto corrispondente (id, nome, telefono) o null se il mittente รจ sconosciuto.
deviceobject|nullDispositivo che ha ricevuto il messaggio (id, nome).

Elenco email in arrivo

GET /?endpoint=incoming_emails

Restituisce un elenco paginato di email ricevute dalle caselle IMAP collegate ai tuoi server SMTP. Include sia il corpo in testo semplice che HTML.

Parametri di query

CampoTipoDescrizione
sincestring opzionale Data-ora ISO 8601. Solo messaggi ricevuti a o dopo questo momento.
untilstring opzionale Data-ora ISO 8601. Solo messaggi ricevuti a o prima di questo momento.
smtp_server_idint opzionale Filtra per ID server SMTP/IMAP.
from_emailstring opzionale Filtra per indirizzo email del mittente (corrispondenza esatta).
searchstring opzionale Cerca in oggetto, from_email e from_name (corrispondenza parziale).
after_idint opzionale Restituisci solo messaggi con ID maggiore di questo valore. Ideale per il polling incrementale.
limitint opzionale Risultati per pagina (1โ€“100). Predefinito: 50.
offsetint opzionale Offset di paginazione. Predefinito: 0.

Esempio di richiesta

curl "https://api.rcszilla.com/?endpoint=incoming_emails&after_id=309&limit=20" \
  -H "Authorization: Bearer YOUR-API-TOKEN"
curl "https://api.rcszilla.com/?endpoint=incoming_emails&search=order&since=2026-05-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR-API-TOKEN"

Risposta

JSON
{
  "success": true,
  "total": 38,
  "limit": 20,
  "offset": 0,
  "emails": [
    {
      "id": 310,
      "from_email": "customer@example.com",
      "from_name": "John Doe",
      "to_email": "support@yourbusiness.com",
      "subject": "Re: Your order #1234",
      "body_text": "Hi, when will my order arrive?\n\nThanks,\nJohn",
      "body_html": "<p>Hi, when will my order arrive?</p>",
      "message_id": "<abc123@mail.example.com>",
      "received_at": "2026-05-27 14:28:00",
      "created_at": "2026-05-27 14:30:02",
      "server": {
        "id": 5,
        "label": "Support Mailbox"
      }
    }
  ]
}

Campi di risposta

CampoTipoDescrizione
idintID univoco dell'email. Usa il valore piรน alto come after_id per il polling incrementale.
from_emailstringIndirizzo email del mittente.
from_namestringNome visualizzato del mittente.
to_emailstringIndirizzo del destinatario (la tua casella).
subjectstringOggetto dell'email.
body_textstringCorpo in testo semplice.
body_htmlstringCorpo HTML (puรฒ essere vuoto se l'email era solo testo semplice).
message_idstringHeader Message-ID dell'email (per threading / deduplicazione).
received_atstringQuando il messaggio รจ stato ricevuto.
serverobjectServer SMTP/IMAP che ha ricevuto questa email (id, etichetta).

Modello di polling consigliato

Il modo piรน efficiente per leggere nuovi messaggi รจ il modello di cursore after_id. Ecco un esempio completo:

PHP
<?php
$token   = 'YOUR_API_TOKEN';
$api     = 'https://api.rcszilla.com';
$last_id = (int) file_get_contents('/tmp/last_sms_id.txt') ?: 0;

$url  = "$api/?endpoint=incoming_messages&after_id=$last_id&limit=100";
$resp = json_decode(file_get_contents($url, false, stream_context_create([
    'http' => ['header' => "Authorization: Bearer $token"]
])), true);

foreach ($resp['messages'] as $msg) {
    echo "[{$msg['channel']}] {$msg['from_phone']}: {$msg['message']}\n";
    if ((int)$msg['id'] > $last_id) $last_id = (int)$msg['id'];
}

file_put_contents('/tmp/last_sms_id.txt', $last_id);
Node.js
const fs = require('fs');
const TOKEN = 'YOUR_API_TOKEN';
const API   = 'https://api.rcszilla.com';

let lastId = 0;
try { lastId = parseInt(fs.readFileSync('/tmp/last_sms_id.txt', 'utf8')) || 0; } catch {}

const url = `${API}/?endpoint=incoming_messages&after_id=${lastId}&limit=100`;
const resp = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });
const data = await resp.json();

for (const msg of data.messages) {
  console.log(`[${msg.channel}] ${msg.from_phone}: ${msg.message}`);
  if (msg.id > lastId) lastId = msg.id;
}

fs.writeFileSync('/tmp/last_sms_id.txt', String(lastId));
Python
import requests, pathlib

TOKEN = 'YOUR_API_TOKEN'
API   = 'https://api.rcszilla.com'
STATE = pathlib.Path('/tmp/last_sms_id.txt')

last_id = int(STATE.read_text()) if STATE.exists() else 0
resp = requests.get(f'{API}/?endpoint=incoming_messages&after_id={last_id}&limit=100',
                    headers={'Authorization': f'Bearer {TOKEN}'}).json()

for msg in resp['messages']:
    print(f"[{msg['channel']}] {msg['from_phone']}: {msg['message']}")
    last_id = max(last_id, msg['id'])

STATE.write_text(str(last_id))
*
Per la consegna in tempo reale invece del polling, configura un Webhook. Puoi usare entrambi: webhook per notifiche istantanee e l'API per letture in blocco o recupero dopo tempi di inattivitร .