RCSZilla Versão 1.0

API de Mensagens Recebidas

Leia as mensagens de SMS, WhatsApp e E-mail recebidas por meio da API REST.

Visão Geral

Estes endpoints permitem obter as mensagens recebidas pelo RCSZilla — SMS e WhatsApp via dispositivos Android, e E-mail via consulta IMAP. Use-os para leituras em lote, sincronização com um CRM ou como alternativa complementar aos webhooks.

EndpointMétodoDescrição
incoming_messagesGETListar mensagens de SMS e WhatsApp recebidas.
incoming_emailsGETListar e-mails recebidos de caixas de entrada consultadas via IMAP.
*
Para um polling eficiente, use after_id em vez de intervalos de datas. Armazene o maior id da última resposta e passe-o na próxima chamada — você receberá apenas mensagens novas, sem duplicatas e sem lacunas.

Listar SMS / WhatsApp Recebidos

GET /?endpoint=incoming_messages

Retorna uma lista paginada de mensagens de SMS e WhatsApp recebidas pelos seus dispositivos Android. Inclui informações do contato correspondente e detalhes do dispositivo.

Parâmetros de Consulta

CampoTipoDescrição
sincestring opcional Data e hora em ISO 8601. Apenas mensagens recebidas neste horário ou depois.
untilstring opcional Data e hora em ISO 8601. Apenas mensagens recebidas neste horário ou antes.
channelstring opcional Filtrar por canal: sms ou whatsapp.
device_idint opcional Filtrar por ID do dispositivo.
from_phonestring opcional Filtrar por número de telefone do remetente (correspondência exata).
after_idint opcional Retornar apenas mensagens com ID maior que este valor. Ideal para polling incremental.
limitint opcional Resultados por página (1–100). Padrão: 50.
offsetint opcional Deslocamento de paginação. Padrão: 0.

Exemplo de Requisição

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"

Resposta

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

Campos da Resposta

CampoTipoDescrição
idintID único da mensagem. Use o maior valor como after_id para polling incremental.
channelstringsms or whatsapp
from_phonestringNúmero de telefone do remetente.
messagestringTexto da mensagem.
received_atstringQuando a mensagem foi recebida.
contactobject|nullContato correspondente (id, nome, telefone) ou null se o remetente for desconhecido.
deviceobject|nullDispositivo que recebeu a mensagem (id, nome).

Listar E-mails Recebidos

GET /?endpoint=incoming_emails

Retorna uma lista paginada de e-mails recebidos por caixas de entrada consultadas via IMAP vinculadas aos seus servidores SMTP. Inclui o corpo em texto simples e em HTML.

Parâmetros de Consulta

CampoTipoDescrição
sincestring opcional Data e hora em ISO 8601. Apenas mensagens recebidas neste horário ou depois.
untilstring opcional Data e hora em ISO 8601. Apenas mensagens recebidas neste horário ou antes.
smtp_server_idint opcional Filtrar por ID do servidor SMTP/IMAP.
from_emailstring opcional Filtrar por endereço de e-mail do remetente (correspondência exata).
searchstring opcional Pesquisar no assunto, from_email e from_name (correspondência parcial).
after_idint opcional Retornar apenas mensagens com ID maior que este valor. Ideal para polling incremental.
limitint opcional Resultados por página (1–100). Padrão: 50.
offsetint opcional Deslocamento de paginação. Padrão: 0.

Exemplo de Requisição

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"

Resposta

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

Campos da Resposta

CampoTipoDescrição
idintID único do e-mail. Use o maior valor como after_id para polling incremental.
from_emailstringEndereço de e-mail do remetente.
from_namestringNome de exibição do remetente.
to_emailstringEndereço do destinatário (sua caixa de correio).
subjectstringLinha de assunto do e-mail.
body_textstringCorpo em texto simples.
body_htmlstringCorpo em HTML (pode estar vazio se o e-mail era apenas texto simples).
message_idstringCabeçalho Message-ID do e-mail (para encadeamento / deduplicação).
received_atstringQuando a mensagem foi recebida.
serverobjectServidor SMTP/IMAP que recebeu este e-mail (id, rótulo).

Padrão de Polling Recomendado

A forma mais eficiente de ler mensagens novas é o padrão de cursor after_id. Aqui está um exemplo 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))
*
Para entrega em tempo real em vez de polling, configure um Webhook. Você pode usar ambos: webhooks para notificação instantânea e a API para leituras em lote ou recuperação após indisponibilidade.