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.
| Endpoint | Metodo | Descrizione |
|---|---|---|
incoming_messages | GET | Elenco messaggi SMS e WhatsApp ricevuti. |
incoming_emails | GET | Elenco 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
Restituisce un elenco paginato di messaggi SMS e WhatsApp ricevuti dai tuoi dispositivi Android. Include informazioni su contatto e dispositivo.
Parametri di query
| Campo | Tipo | Descrizione | |
|---|---|---|---|
since | string | opzionale | Data-ora ISO 8601. Solo messaggi ricevuti a o dopo questo momento. |
until | string | opzionale | Data-ora ISO 8601. Solo messaggi ricevuti a o prima di questo momento. |
channel | string | opzionale | Filtra per canale: sms o whatsapp. |
device_id | int | opzionale | Filtra per ID dispositivo. |
from_phone | string | opzionale | Filtra per numero di telefono del mittente (corrispondenza esatta). |
after_id | int | opzionale | Restituisci solo messaggi con ID maggiore di questo valore. Ideale per il polling incrementale. |
limit | int | opzionale | Risultati per pagina (1โ100). Predefinito: 50. |
offset | int | 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
| Campo | Tipo | Descrizione |
|---|---|---|
id | int | ID univoco del messaggio. Usa il valore piรน alto come after_id per il polling incrementale. |
channel | string | sms or whatsapp |
from_phone | string | Numero di telefono del mittente. |
message | string | Testo del messaggio. |
received_at | string | Quando il messaggio รจ stato ricevuto. |
contact | object|null | Contatto corrispondente (id, nome, telefono) o null se il mittente รจ sconosciuto. |
device | object|null | Dispositivo che ha ricevuto il messaggio (id, nome). |
Elenco email in arrivo
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
| Campo | Tipo | Descrizione | |
|---|---|---|---|
since | string | opzionale | Data-ora ISO 8601. Solo messaggi ricevuti a o dopo questo momento. |
until | string | opzionale | Data-ora ISO 8601. Solo messaggi ricevuti a o prima di questo momento. |
smtp_server_id | int | opzionale | Filtra per ID server SMTP/IMAP. |
from_email | string | opzionale | Filtra per indirizzo email del mittente (corrispondenza esatta). |
search | string | opzionale | Cerca in oggetto, from_email e from_name (corrispondenza parziale). |
after_id | int | opzionale | Restituisci solo messaggi con ID maggiore di questo valore. Ideale per il polling incrementale. |
limit | int | opzionale | Risultati per pagina (1โ100). Predefinito: 50. |
offset | int | 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
| Campo | Tipo | Descrizione |
|---|---|---|
id | int | ID univoco dell'email. Usa il valore piรน alto come after_id per il polling incrementale. |
from_email | string | Indirizzo email del mittente. |
from_name | string | Nome visualizzato del mittente. |
to_email | string | Indirizzo del destinatario (la tua casella). |
subject | string | Oggetto dell'email. |
body_text | string | Corpo in testo semplice. |
body_html | string | Corpo HTML (puรฒ essere vuoto se l'email era solo testo semplice). |
message_id | string | Header Message-ID dell'email (per threading / deduplicazione). |
received_at | string | Quando il messaggio รจ stato ricevuto. |
server | object | Server 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ร .