Get in Touch

Have a question about the platform, need help with your integration, or want to discuss partnership opportunities and enterprise pricing? Drop us an email — we’ll do our best to get back to you within 3–4 hours.

contact@fiwano.com
Documentation menu

Working with an AI agent? Download the full documentation as a Markdown file to use as context.

Download full .md

Quickstart

The fast path connects your own WhatsApp, Instagram or Facebook account through the portal — if you are building a service that connects your client's accounts, see the note in step 3.

1. Create an account

Every new account gets a 7-day free trial with full functionality — every channel type, media and templates, no card required.

2. Create an API key

Open API Keys in the portal and create a key. The full key (it starts with mip_live_) is shown only once — save it somewhere safe. Every request carries it in the X-API-Key header.

3. Connect a channel

In the portal go to Channels → Connect Channel, pick WhatsApp, Instagram or Facebook Messenger, and complete the Meta sign-in popup. You get back a channel_id — store it, every send and receive call uses it. The prerequisites (the asset must belong to a Meta Business Portfolio, and you must be its admin) are spelled out in Channels.

Building a platform for your clients? Your app drives the connection itself instead of the portal: whitelist a redirect URI, request a setup URL, then exchange the returned code for a channel_id. That is the API flow in Channels → Via API. Steps 1, 2, 4 and 5 are identical.

4. Receive a message

When a user writes to your channel, Fiwano POSTs a signed payload to your Webhook URL. Set the URL and choose Webhook Events on the channel (portal channel settings, or webhook_url / webhook_events via the API) — by default no events are delivered, so opt in to message.received. Verify the X-Webhook-Signature (HMAC-SHA256 with the channel's webhook_secret) before trusting a payload.

An inbound message.received carries the two identifiers you need to reply (marked below):

{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",   // ← which of your channels received it
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",              // ← who sent it — reply to this
    "from_name": "John Doe",
    "type": "text",
    "text": "Hello!"
  }
}
  • channel_id (top level) — the channel the message arrived on.
  • data.from — the sender's id: phone number (WhatsApp), IGSID (Instagram), or PSID (Facebook). This is exactly what you pass back as recipient.

The full event list, per-channel payloads and the signature check are in Receiving Messages.

5. Reply to it

This is the core move: answer the sender by feeding the same identifiers straight back — the webhook's channel_id as channel_id, and data.from as recipient:

curl -X POST https://fiwano.com/api/v1/messages/send \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel_id": "a1b2c3d4e5f67890", "recipient": "1234567890", "text": "Thanks for your message!"}'

The response carries a message_id you can track via delivery-status webhooks. Replying within 24 hours of the user's last message is always free-form. To open a conversation cold (outside that window, WhatsApp only) you use an approved template — see Sending Messages and the 24-hour window in Capabilities.

Next steps

Fiwano API Documentation