Fiwano API Documentation

Authentication

All API requests require an API key in the X-API-Key header.

Create a key from the API Keys page in the portal. The full key is shown only once — save it securely. Lost keys cannot be recovered; revoke and create a new one.

curl https://fiwano.com/api/v1/channels \
  -H "X-API-Key: YOUR_API_KEY"

All keys start with mip_live_. Keys are hashed on our side.

Errors

Every error response has a detail field. Most domain errors use a human-readable string:

{ "detail": "Human-readable error description" }

Schema validation (422) uses a list of field errors. Some domain validation errors instead use a structured detail object with a code field — for example text_too_long when sending overlong text, invalid_recipient (400) when recipient is empty, contains no digits, or is not a numeric PSID/IGSID on a Messenger/Instagram channel (reason says which; hint says what to send instead), or recipient_equals_sender (400) when a WhatsApp send is addressed to the channel's own number. The per-endpoint shapes are in the API Reference.

HTTP status codes

Send error codes

The three send endpoints answer 200 even when the send fails — the outcome is in success, status, and error_code. See Delivery and retries.

error_code is Meta's error code, passed through unchanged. It is present only when the failure came from Meta; a rejection by Fiwano itself uses an HTTP status code from the table above instead. error always carries a human-readable description, and for media sends a hint about the likely cause.

Codes outside this table are passed through as Meta returns them. Anything not recognised as permanent is treated as transient and retried.

Slow Meta responses

Occasionally Meta takes longer than 30 seconds — sometimes more than a minute — to answer a send, most often while it downloads a large media file. Fiwano does not fail the message: the call returns success: true, status: "queued", and the message_id is final. Fiwano then finishes the send with Meta on your behalf. What you see:

• The usual message.sent / message.delivered / message.read webhooks for that message_id, exactly as for a message that returned sent right away.
• In rare cases the message reaches the recipient twice: if Meta has not confirmed the send within a few minutes, Fiwano sends it once more, and the first attempt may have gone through after all. A duplicate is preferred to a lost message.
• If the message cannot be confirmed at all, it becomes failed and the channel owner receives the delivery digest email.

Do not resend on your side while the message is queued. The same applies if your own HTTP client times out — see Response time.

Compatibility

Fiwano has no version numbers. The API contract is v1 (https://fiwano.com/api/v1), and it has been stable since the public launch in March 2026. The service ships continuously; new capabilities are listed in the changelog (with an Atom feed).

Every change to v1 is additive:

• new endpoints;
• new optional request parameters and fields;
• new fields in responses and webhook payloads;
• new webhook event types and new values in open sets such as delivery statuses or error hints.

What stays fixed: existing endpoints, field names, types and meanings; the X-API-Key authentication; the webhook signature scheme. New webhook event types are never enabled on your channels without your action — you opt in per channel via webhook_events.

What your integration needs to do to stay compatible: ignore fields it does not know and ignore event types it did not enable. Do not treat an unknown field or a new value in an open set as an error.

If a breaking change ever becomes unavoidable, it ships as a new API version alongside v1, announced in the changelog and by email in advance. v1 keeps working.