Guida WhatsApp

UniMsg si integra con WhatsApp Business API per permetterti di inviare messaggi WhatsApp professionali. Supporta template pre-approvati, messaggi di sessione e media.

Caratteristiche

WhatsApp Business API ufficiale
Template messaggi pre-approvati
Messaggi di sessione (entro 24h dalla risposta utente)
Supporto media: immagini, documenti, video
Notifiche di lettura
Costo: 2 crediti per messaggio template, 1 credito per sessione

Tipi di Messaggio

WhatsApp Business distingue due tipi di messaggi:

1. Template Messages

Messaggi con template pre-approvati da Meta. Possono essere inviati in qualsiasi momento.

2. Session Messages

Messaggi liberi che possono essere inviati solo entro 24 ore dall'ultima risposta dell'utente.

Endpoint

Metodo	Endpoint	Descrizione
`POST`	`/v1/whatsapp/send`	Invia messaggio template
`POST`	`/v1/whatsapp/session`	Invia messaggio di sessione
`GET`	`/v1/whatsapp/templates`	Lista template disponibili
`GET`	`/v1/whatsapp/{id}`	Stato messaggio

Invio Template Message

Richiesta

POST /v1/whatsapp/send
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

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

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
`to`	string	Sì	Numero WhatsApp destinatario
`template`	string	Sì	Nome del template
`language`	string	Sì	Codice lingua (es: it, en)
`components`	array	No	Parametri variabili del template

Risposta

{
    "success": true,
    "data": {
        "message_id": "msg_wa_xxxxxxxxxxxx",
        "to": "+39123456789",
        "template": "order_confirmation",
        "status": "sent",
        "credits_used": 2,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Invio Messaggio di Sessione

Importante: I messaggi di sessione possono essere inviati solo entro 24 ore dall'ultimo messaggio ricevuto dall'utente.

POST /v1/whatsapp/session
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "to": "+39123456789",
    "message": "Grazie per averci contattato! Come possiamo aiutarti?"
}

Invio con Media

Puoi allegare media ai messaggi di sessione:

Immagine

{
    "to": "+39123456789",
    "type": "image",
    "media_url": "https://example.com/image.jpg",
    "caption": "Ecco il prodotto richiesto"
}

Documento

{
    "to": "+39123456789",
    "type": "document",
    "media_url": "https://example.com/invoice.pdf",
    "filename": "fattura.pdf"
}

Tipi Media Supportati

Tipo	Formati	Dimensione Max
image	JPEG, PNG	5 MB
document	PDF, DOC, DOCX, XLS, XLSX	100 MB
video	MP4, 3GPP	16 MB
audio	AAC, M4A, AMR, MP3, OGG	16 MB

Template Disponibili

Per vedere i template disponibili per il tuo account:

GET /v1/whatsapp/templates
Authorization: Bearer YOUR_ACCESS_TOKEN

Risposta:

{
    "success": true,
    "data": [
        {
            "name": "order_confirmation",
            "language": "it",
            "status": "APPROVED",
            "category": "TRANSACTIONAL",
            "components": [
                {
                    "type": "BODY",
                    "text": "Ciao {{1}}, il tuo ordine {{2}} è confermato. Totale: {{3}}"
                }
            ]
        },
        {
            "name": "shipping_update",
            "language": "it",
            "status": "APPROVED",
            "category": "TRANSACTIONAL"
        }
    ]
}

Stati del Messaggio

Stato	Descrizione
`sent`	Inviato ai server WhatsApp
`delivered`	Consegnato al dispositivo
`read`	Letto dall'utente
`failed`	Invio fallito

Errori Comuni

Codice	Descrizione	Soluzione
`TEMPLATE_NOT_FOUND`	Template non esistente	Verifica il nome del template
`SESSION_EXPIRED`	Sessione 24h scaduta	Usa un template message
`INVALID_WHATSAPP`	Numero non su WhatsApp	Verifica che il numero sia attivo
`BLOCKED_USER`	L'utente ha bloccato il numero	Non è possibile contattare

SMS Email