Gateway Integration

UniMsg utilizza un sistema di gateway configurabili per l'invio dei messaggi. Ogni canale può avere uno o più provider disponibili.

Architettura Gateway

Il sistema utilizza il pattern Factory per istanziare il gateway corretto:

// Flusso semplificato
Client Request
    → API Controller
        → Service Layer
            → GatewayFactory::create($channel, $provider)
                → Gateway Instance (Twilio, SendGrid, etc.)
                    → External API Call
                        → Response/Status Update

Gateway Supportati

SMS

Provider	Copertura	Note
Twilio	Globale	Default per alta affidabilità
Nexmo/Vonage	Globale	Fallback primario
Skebby	Italia	Migliori tariffe Italia
SMPP Custom	Custom	Enterprise only

WhatsApp

Provider	Tipo	Note
Meta Cloud API	Ufficiale	API diretta Meta
Twilio WhatsApp	BSP	Via Twilio Business API

Email

Provider	Tipo	Note
SendGrid	API	Alta deliverability
Mailgun	API	Fallback
SMTP Custom	SMTP	Per server propri

Telegram

Provider	Note
Telegram Bot API	API ufficiale Telegram

Configurazione per Client

Ogni client può avere gateway specifici configurati. La configurazione è gestita a livello admin:

// Esempio configurazione client
{
    "client_id": "demo_xxxxxxxxxxxx",
    "gateways": {
        "sms": {
            "primary": "twilio",
            "fallback": ["nexmo", "skebby"],
            "routing": {
                "+39": "skebby",  // Italia via Skebby
                "*": "twilio"     // Default Twilio
            }
        },
        "email": {
            "primary": "sendgrid",
            "fallback": ["mailgun"]
        },
        "whatsapp": {
            "primary": "meta_cloud"
        },
        "telegram": {
            "primary": "telegram_bot",
            "bot_token": "encrypted_token"
        }
    }
}

Fallback Automatico

Se il gateway primario fallisce, il sistema tenta automaticamente i fallback:

// Logica fallback semplificata
public function send(Message $message): Result
{
    $gateways = $this->getGatewaysFor($message->client, $message->channel);

    foreach ($gateways as $gateway) {
        try {
            $result = $gateway->send($message);

            if ($result->isSuccess()) {
                return $result;
            }
        } catch (GatewayException $e) {
            $this->logGatewayError($gateway, $e);
            continue; // Try next gateway
        }
    }

    throw new AllGatewaysFailedException();
}

Gateway Interface

Tutti i gateway implementano un'interfaccia comune:

interface GatewayInterface
{
    /**
     * Send a message through this gateway
     */
    public function send(Message $message): SendResult;

    /**
     * Check delivery status
     */
    public function getStatus(string $externalId): StatusResult;

    /**
     * Validate message before sending
     */
    public function validate(Message $message): ValidationResult;

    /**
     * Get gateway health status
     */
    public function healthCheck(): bool;
}

Webhook di Status

I gateway inviano callback di status a UniMsg, che vengono normalizzati e inoltrati ai client:

// Callback da Twilio
POST /webhook/twilio/status

{
    "MessageSid": "SMxxxxx",
    "MessageStatus": "delivered",
    "To": "+39123456789"
}

// Normalizzato e inoltrato al client come
POST https://client-webhook.com/

{
    "event": "message.delivered",
    "data": {
        "message_id": "msg_xxxxxxxxxxxx",
        "status": "delivered"
    }
}

Testing Gateway

Per testare senza inviare messaggi reali:

// Modalità sandbox
POST /v1/sms/send
{
    "to": "+39123456789",
    "message": "Test message",
    "sandbox": true
}

// Response (messaggio NON inviato)
{
    "success": true,
    "data": {
        "message_id": "msg_test_xxxxxxxxxxxx",
        "status": "simulated",
        "would_use_gateway": "twilio"
    }
}