API Reference

Documentazione completa di tutti gli endpoint API UniMsg. Base URL: https://api.unimsg.app

Autenticazione: Tutti gli endpoint (eccetto /oauth/token) richiedono header Authorization: Bearer TOKEN

SMS

Invia SMS

POST /v1/sms/send

Request Body

{
    "to": "+39123456789",
    "message": "Il tuo codice di verifica: 123456",
    "sender": "MyApp",
    "scheduled_at": "2024-01-16T09:00:00+01:00",
    "callback_url": "https://myapp.com/webhook"
}

Parametri

Nome	Tipo	Obbl.	Descrizione
`to`	string	Sì	Numero destinatario formato E.164
`message`	string	Sì	Testo messaggio (max 1600 char)
`sender`	string	No	Mittente (max 11 char alfanumerico)
`scheduled_at`	string	No	Data/ora invio (ISO 8601)
`callback_url`	string	No	URL webhook per questo messaggio

Response 200

{
    "success": true,
    "data": {
        "message_id": "msg_sms_xxxxxxxxxxxx",
        "to": "+39123456789",
        "status": "queued",
        "segments": 1,
        "credits_used": 1,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Invio SMS Bulk

POST /v1/sms/bulk

{
    "recipients": ["+39123456789", "+39123456790"],
    "message": "Messaggio per tutti",
    "sender": "MyApp"
}

Stato SMS

GET /v1/sms/{message_id}

{
    "success": true,
    "data": {
        "message_id": "msg_sms_xxxxxxxxxxxx",
        "channel": "sms",
        "to": "+39123456789",
        "message": "Il tuo codice: 123456",
        "sender": "MyApp",
        "status": "delivered",
        "segments": 1,
        "credits_used": 1,
        "created_at": "2024-01-15T10:30:00Z",
        "sent_at": "2024-01-15T10:30:01Z",
        "delivered_at": "2024-01-15T10:30:03Z"
    }
}

Invia Template Message

POST /v1/whatsapp/send

{
    "to": "+39123456789",
    "template": "order_confirmation",
    "language": "it",
    "components": [
        {
            "type": "body",
            "parameters": [
                {"type": "text", "text": "Mario Rossi"},
                {"type": "text", "text": "ORD-12345"}
            ]
        }
    ]
}

Invia Session Message

POST /v1/whatsapp/session

{
    "to": "+39123456789",
    "message": "Risposta alla tua richiesta..."
}

Lista Template

GET /v1/whatsapp/templates

Email

Invia Email

POST /v1/email/send

{
    "to": "test@example.com",
    "from": "noreply@mycompany.com",
    "from_name": "My Company",
    "subject": "Conferma ordine",
    "html": "<h1>Grazie!</h1><p>Ordine confermato.</p>",
    "text": "Grazie! Ordine confermato.",
    "reply_to": "support@mycompany.com",
    "cc": ["manager@mycompany.com"],
    "attachments": [
        {
            "filename": "invoice.pdf",
            "content": "base64_encoded_content",
            "content_type": "application/pdf"
        }
    ],
    "track_opens": true,
    "track_clicks": true
}

Eventi Email

GET /v1/email/{message_id}/events

Invia Messaggio

POST /v1/telegram/send

{
    "chat_id": "123456789",
    "message": "*Messaggio* con _formattazione_",
    "parse_mode": "Markdown",
    "disable_notification": false,
    "reply_markup": {
        "inline_keyboard": [
            [{"text": "OK", "callback_data": "confirm"}]
        ]
    }
}

Invia Foto

POST /v1/telegram/photo

{
    "chat_id": "123456789",
    "photo_url": "https://example.com/image.jpg",
    "caption": "Descrizione foto"
}

Messaggi

Stato Messaggio

GET /v1/messages/{message_id}

Endpoint universale per lo stato di qualsiasi messaggio.

Lista Messaggi

GET /v1/messages

Query Parameters

Nome	Tipo	Descrizione
`channel`	string	Filtra per canale (sms, whatsapp, email, telegram)
`status`	string	Filtra per stato
`from`	string	Data inizio (ISO 8601)
`to`	string	Data fine (ISO 8601)
`limit`	int	Numero risultati (default 20, max 100)
`offset`	int	Offset per paginazione

Account

Saldo Crediti

GET /v1/account/balance

{
    "success": true,
    "data": {
        "credits": 4523.5,
        "reserved": 10,
        "available": 4513.5
    }
}

Info Account

GET /v1/account

{
    "success": true,
    "data": {
        "client_id": "demo_xxxxxxxxxxxx",
        "name": "My Company",
        "email": "admin@mycompany.com",
        "plan": "pro",
        "created_at": "2024-01-01T00:00:00Z"
    }
}

Webhook

Lista Webhook

GET /v1/webhooks

Crea Webhook

POST /v1/webhooks

{
    "url": "https://myapp.com/webhook",
    "events": ["message.sent", "message.delivered", "message.failed"]
}

Elimina Webhook

DELETE /v1/webhooks/{webhook_id}

HTTP Status Codes

Codice	Significato
`200`	OK - Richiesta completata
`201`	Created - Risorsa creata
`400`	Bad Request - Parametri non validi
`401`	Unauthorized - Token mancante/invalido
`403`	Forbidden - Permessi insufficienti
`404`	Not Found - Risorsa non trovata
`422`	Unprocessable Entity - Validazione fallita
`429`	Too Many Requests - Rate limit superato
`500`	Internal Server Error - Errore server

Autenticazione Errori