Documentazione API

Invia un messaggio di testo libero (solo a finestra aperta).

record SendTextMessageRequest(
    Guid PhoneNumberId,          // required
    string Recipient,            // required, 8-32 caratteri (E.164)
    string Text,                 // required, max 4096
    string? ClientRequestId,     // opzionale, max 100 — idempotenza
    string? RepliedToProviderMessageId);

// 200 OK: SendMessageResult(string ProviderMessageId, Guid MessageId, string Status)

Avvia/continua una conversazione con un template approvato — funziona anche a finestra chiusa, è l'unico modo per iniziare un contatto.

record SendTemplateMessageRequest(
    Guid PhoneNumberId,
    string Recipient,
    string TemplateName,                   // max 512
    string LanguageCode,                   // max 20 — codice lingua Meta
    IReadOnlyList<string>? BodyParameters, // max 10 — {{1}}, {{2}}, ...
    string? ClientRequestId);

// 200 OK: SendMessageResult

Invia un'immagine o un documento già ospitato altrove — Messivo lo scarica dall'URL indicato e lo inoltra a Meta.

record SendMediaMessageRequest(
    Guid PhoneNumberId,
    string Recipient,
    string MediaType,       // "image" o "document"
    string MediaUrl,        // required, HTTPS assoluto
    string? Caption,        // max 1024
    string? FileName,       // max 255
    string? ClientRequestId);

// 200 OK: SendMessageResult

Come sopra, ma il file è incluso in base64 nella richiesta — utile quando non hai un URL pubblico da dare. Limite 5MB decodificato; image/jpeg, image/png, application/pdf.

record SendUploadedMediaRequest(
    Guid PhoneNumberId,
    string Recipient,
    string ContentType,      // image/jpeg | image/png | application/pdf
    string FileName,
    string Base64Content,    // required, max 5MB decodificato
    string? Caption,
    string? ClientRequestId,
    string? RepliedToProviderMessageId);

// 200 OK: SendMessageResult

Ultimi messaggi del Tenant (tutti i numeri/contatti insieme), più recenti prima. take clampato tra 1 e 100.

Un singolo messaggio per id. 404 se non trovato (o non del Tenant corrente).

record MessageDetails(
    Guid Id, Guid PhoneNumberId, string ProviderMessageId,
    string Direction,        // "Inbound" | "Outbound"
    string Type,             // "Text" | "Image" | "Document" | "Template" | ...
    string Contact,          // E.164
    string? Content, string? ProviderMediaId, string? MediaUrl,
    string? MimeType, string? FileName, string? ClientRequestId,
    string Status,           // "Accepted" | "Sent" | "Delivered" | "Read" | "Failed" | ...
    string? ErrorCode, string? ErrorMessage,
    DateTimeOffset CreatedAtUtc, DateTimeOffset StatusUpdatedAtUtc,
    string? RepliedToProviderMessageId, RepliedToMessagePreview? RepliedToMessage);

Storico delle transizioni di stato di un messaggio (Accepted → Sent → Delivered → Read, o → Failed).

Scarica il contenuto binario di un allegato (proxato da Meta). 404 se non più disponibile, 502 se Meta rifiuta il download.

Tutte le conversazioni del Tenant (una per coppia numero+contatto), più recenti prima, max 100.

record ConversationDetails(
    Guid PhoneNumberId, string Contact, string? ContactDisplayName,
    string? LastContent, string LastMessageType, string LastDirection, string LastStatus,
    DateTimeOffset LastActivityAtUtc, int MessageCount,
    DateTimeOffset? LastInboundAtUtc, DateTimeOffset? ServiceWindowExpiresAtUtc,
    bool IsServiceWindowOpen);

Tutti i messaggi di una conversazione specifica, in ordine cronologico.

Stato della finestra di servizio per un contatto specifico, senza scaricare l'intera lista conversazioni. Funziona anche per un contatto mai scritto (nessun 404: isOpen false).

record ServiceWindowStatus(bool IsOpen, DateTimeOffset? ExpiresAtUtc);

Nasconde la conversazione (soft delete — ricompare da sola al prossimo messaggio, in entrata o in uscita). 204 No Content.

Cancella definitivamente tutti i messaggi della conversazione — irreversibile. 204 No Content.

Template disponibili per un numero (mirror locale, allineato a Meta solo tramite synchronize — non è sempre "live").

record TemplateDetails(
    Guid Id, Guid WhatsAppBusinessAccountId, string MetaTemplateId,
    string Name, string Language,
    string Status,      // "Approved" | "Pending" | "Rejected" | ...
    string Category,    // "UTILITY" | "MARKETING"
    string? BodyText, int BodyParameterCount, bool IsSupportedForSending,
    DateTimeOffset SyncedAtUtc,
    IReadOnlyDictionary<int, TemplateVariableSourceDetails> VariableSources);

Crea un nuovo template e lo sottopone a Meta per approvazione.

record CreateTemplateRequest(
    Guid PhoneNumberId,
    string Name,                          // solo minuscole/numeri/underscore
    string Language,
    string Category,                      // "UTILITY" o "MARKETING"
    string BodyText,                      // {{1}}, {{2}}, ... mai a inizio/fine testo
    IReadOnlyList<string> ExampleValues); // un esempio per ogni parametro

Riallinea il mirror locale con lo stato reale su Meta (approvazione, categoria, ecc.) — da chiamare periodicamente o dopo modifiche fatte altrove.

Configura come compilare le variabili di un template all'invio (da rubrica, valore fisso, o manuale a ogni invio). 204 No Content.

Numeri WhatsApp collegati al Tenant. Id è il PhoneNumberId da usare in tutte le altre chiamate.

record PhoneNumberDetails(Guid Id, string DisplayPhoneNumber, string? Alias, bool IsEnabled);

Imposta un alias interno testuale per un numero (o null per rimuoverlo).

Tutti i contatti del Tenant.

record ContactDetails(
    Guid Id, string PhoneNumber, string DisplayName,
    string? FirstName, string? LastName, string? Address, string? Notes,
    DateTimeOffset CreatedAtUtc, DateTimeOffset? UpdatedAtUtc);

Crea/aggiorna solo il nome visualizzato — richiede che il numero abbia già una conversazione.

Rubrica completa (nome, cognome, indirizzo, note) — funziona anche su un numero mai contattato.

204 No Content se cancellato, 404 se non esisteva.

Il Tenant a cui appartiene la chiave API corrente.

record TenantDetails(Guid Id, string Slug, string DisplayName, string Status);

Nome del provider WhatsApp configurato lato Messivo (utile solo per diagnostica).