API documentation

Sends a free-text message (window open only).

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)

Starts/continues a conversation with an approved template — works even with the window closed, it's the only way to start a contact.

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

Sends an image or document already hosted elsewhere — Messivo downloads it from the given URL and forwards it to 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

Same as above, but the file is included as base64 in the request — useful when you don't have a public URL to give. 5MB decoded limit; 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

Latest messages for the Tenant (all numbers/contacts together), most recent first. take is clamped between 1 and 100.

A single message by id. 404 if not found (or not owned by the current Tenant).

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);

Status transition history for a message (Accepted → Sent → Delivered → Read, or → Failed).

Downloads the binary content of an attachment (proxied from Meta). 404 if no longer available, 502 if Meta refuses the download.

All of the Tenant's conversations (one per number+contact pair), most recent first, 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);

All messages of a specific conversation, in chronological order.

Service window status for a specific contact, without downloading the whole conversation list. Works even for a contact who never wrote (no 404: isOpen false).

record ServiceWindowStatus(bool IsOpen, DateTimeOffset? ExpiresAtUtc);

Hides the conversation (soft delete — it reappears on its own at the next message, inbound or outbound). 204 No Content.

Permanently deletes every message in the conversation — irreversible. 204 No Content.

Templates available for a number (local mirror, kept in sync with Meta only through synchronize — not always "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);

Creates a new template and submits it to Meta for approval.

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

Re-syncs the local mirror with the real state on Meta (approval status, category, etc.) — call periodically or after changes made elsewhere.

Configures how a template's variables are filled in when sending (from contacts, a fixed value, or manually on each send). 204 No Content.

WhatsApp numbers connected to the Tenant. Id is the PhoneNumberId to use in every other call.

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

Sets an internal text alias for a number (or null to remove it).

All of the Tenant's contacts.

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

Creates/updates only the display name — requires the number to already have a conversation.

Full contact record (first/last name, address, notes) — works even for a number never contacted.

204 No Content if deleted, 404 if it didn't exist.

The Tenant the current API key belongs to.

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

Name of the WhatsApp provider configured on the Messivo side (diagnostics only).