KeyInteractive.Messivo 1.0.0

Key Interactive.Messivo

KeyInteractive.Messivo is the .NET client for the Messivo WhatsApp Business Cloud API integration platform (Key Interactive). It gives you a ready-to-use IMessivoApiConsumer/MessivoApiConsumer service wrapping message sending, conversation and message history reading, and template/phone number/contact management behind simple method calls.

It's built on KeyInteractive.Common.Api, which provides the generic API-consuming plumbing (retry, HttpClient lifecycle) that MessivoApiConsumer inherits — but note Messivo's own response/auth conventions differ from the rest of the Key Interactive family (see below), so this package is deliberately named KeyInteractive.Messivo, not KeyInteractive.Common.Api.Messivo.

Requirements

Targets .NET 8.0 or later (net8.0, net10.0).

Installation

dotnet add package KeyInteractive.Messivo

Configuration and dependency injection (ASP.NET Core backend)

Messivo authenticates with a single opaque API key (X-Api-Key), not the ApiKey/ApplicationKey pair used elsewhere in the Key Interactive family — one key identifies both the caller and the fixed Tenant it operates on. There's no static configuration facade; pass MessivoApiConsumerOptions directly when registering the typed client:

// Program.cs
builder.Services.AddHttpClient<IMessivoApiConsumer, MessivoApiConsumer>();
builder.Services.AddSingleton(new MessivoApiConsumerOptions
{
    BaseUri = "https://messivo.api.keyinteractive.it/",
    ApiKey = "ms_...", // obtained out-of-band from whoever administers Messivo
});

Usage examples

Check the service window before sending

WhatsApp only allows free-form text within 24h of the contact's last message; outside that window (including the very first contact) only an approved template can be sent:

var window = await messivoApiConsumer.GetServiceWindowStatus(phoneNumberId, contact: "+391234567890");

if (window.IsOpen)
{
    await messivoApiConsumer.SendText(new SendTextMessageRequest(
        phoneNumberId, Recipient: "+391234567890", Text: "Ciao!", ClientRequestId: myEventId, RepliedToProviderMessageId: null));
}
else
{
    await messivoApiConsumer.SendTemplate(new SendTemplateMessageRequest(
        phoneNumberId, Recipient: "+391234567890", TemplateName: "welcome", LanguageCode: "it",
        BodyParameters: null, ClientRequestId: myEventId));
}

Read conversations and messages

var conversations = await messivoApiConsumer.GetConversations();
if (conversations.Success)
{
    foreach (var c in conversations.Conversations)
        Console.WriteLine($"{c.Contact}: {c.LastContent} ({c.LastStatus})");
}

var messages = await messivoApiConsumer.GetMessages(take: 50);

Idempotency

SendText/SendTemplate/SendMedia/UploadAndSendMedia/CreateTemplate all pass through without automatic retry (isIdempotent: false, same convention as every other non-idempotent POST in the Key Interactive family) — a lost response after the server already sent a WhatsApp message would otherwise risk sending it twice on retry. Always pass a stable ClientRequestId (max 100 characters) on every send: if the same value was already used for that Tenant, a duplicate request (e.g. from your own retry logic) gets a 409 Conflict instead of sending the message again. Generate it deterministically from your own originating event (e.g. a GUID derived from your event id), not randomly per attempt.

Known limitations

• No outbound webhooks: Messivo does not push new inbound messages to your application. To "react" to incoming messages, poll GetMessages/GetConversations at an interval of your choosing — this package offers no built-in real-time listener.
• Effectively one phone number per Tenant today: the data model supports several, but Messivo's guided onboarding assumes one. Sending/reading is already multi-number via PhoneNumberId regardless.
• No documented rate limiting/retry policy on Messivo's side — this package retries network errors and 408/429/502/503/504 with backoff, but a caller doing high-volume sending should still expect and handle 502 (Meta-side errors) gracefully.

See IMessivoApiConsumer for the full list of available operations.