Fiwano

https://fiwano.com/documentation
Admin
Fiwano is a unified messaging platform and REST API that allows developers to connect, send, and...
Tokens:33,420
Snippets:224
Trust Score:3.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Fiwano via npm

Source: https://fiwano.com/documentation/n8n

Use this manual installation method for restricted self-hosted n8n environments where in-app installation is unavailable.

```bash
mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes
npm install n8n-nodes-fiwano
# Restart n8n
```

--------------------------------

### WhatsApp media audio example

Source: https://fiwano.com/documentation/webhooks

WhatsApp voice message example (Pro license). The `voice` flag is true for voice messages; use `download_url` to fetch the file before it expires.

```json
{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",
    "from_name": "John Doe",
    "type": "audio",
    "media": {
      "media_id": "m2b3c4d5e6f78901",
      "voice": true,
      "mime_type": "audio/ogg; codecs=opus",
      "file_size": 12345,
      "filename": null,
      "sha256": "def456...",
      "duration_ms": 5200,
      "download_url": "https://fiwano.com/api/v1/media/m2b3c4d5e6f78901",
      "expires_at": "2025-01-15T11:30:00Z"
    }
  }
}
```

--------------------------------

### WhatsApp media image example

Source: https://fiwano.com/documentation/webhooks

WhatsApp image message example (Pro license). The media file is downloaded from Meta and stored temporarily; use `download_url` to fetch the file before it expires.

```json
{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",
    "from_name": "John Doe",
    "type": "image",
    "caption": "Check this photo",
    "media": {
      "media_id": "m1b2c3d4e5f67890",
      "mime_type": "image/jpeg",
      "file_size": 245760,
      "filename": null,
      "sha256": "abc123...",
      "duration_ms": null,
      "download_url": "https://fiwano.com/api/v1/media/m1b2c3d4e5f67890",
      "expires_at": "2025-01-15T11:30:00Z"
    }
  }
}
```

--------------------------------

### POST /api/v1/channels/setup-url

Source: https://fiwano.com/documentation/quickstart

Creates a setup URL for the embedded OAuth flow to connect end-users' channels.

```APIDOC
## POST /api/v1/channels/setup-url

### Description
Creates a setup URL for the embedded OAuth flow to connect end-users' channels.

### Method
POST

### Endpoint
/api/v1/channels/setup-url

### Parameters
#### Request Body
- **redirect_uri** (string) - Required - The whitelisted redirect URI for the OAuth flow.

### Response
#### Success Response (200)
Returns a setup URL that the user can be directed to.

```

--------------------------------

### Request setup URL with POST /api/v1/channels/setup-url

Source: https://fiwano.com/documentation/channels

Requests a setup URL for a channel by passing a whitelisted redirect URI. The returned URL is valid until `expires_at`. The same endpoint also reconnects channels; if the Meta identity already belongs to an inactive channel, Fiwano reactivates that row and `exchange-code` returns the existing `channel_id`.

```bash
curl -X POST https://fiwano.com/api/v1/channels/setup-url \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_type": "whatsapp", "redirect_uri": "https://yourapp.com/callback"}'
Copy
```

--------------------------------

### Authenticate with X-API-Key

Source: https://fiwano.com/documentation

Include your API key in the X-API-Key header for all requests. Keys must start with mip_live_.

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

--------------------------------

### GET /api/v1/redirects

Source: https://fiwano.com/documentation/channels

Lists the whitelisted redirect URIs for your API key.

```APIDOC
## GET /api/v1/redirects

### Description
Returns the list of whitelisted redirect URIs.

### Method
GET

### Endpoint
https://fiwano.com/api/v1/redirects

### Parameters
No parameters documented.

### Response
No response schema provided in the source.

```

--------------------------------

### Create WhatsApp template with curl

Source: https://fiwano.com/documentation/templates

Creates a UTILITY template named 'order_confirmation' with a BODY component using positional variables. Requires a Pro license and a valid channel ID. The template is submitted to Meta and starts in PENDING status.

```bash
curl -X POST https://fiwano.com/api/v1/channels/a1b2c3d4e5f67890/templates \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {"type": "BODY", "text": "Hi {{1}}, your order {{2}} is confirmed.",
       "example": {"body_text": [["Pablo", "ORD-123"]]}}
    ],
    "parameter_format": "positional"
  }'
```

--------------------------------

### Empty channels response on fresh account

Source: https://fiwano.com/documentation/quickstart

Example of the successful response when the API key is valid but there are no channels yet. It serves as the success signal that authentication works.

```json
{ "channels": [], "total": 0 }
```

--------------------------------

### Failure redirect with error and message parameters

Source: https://fiwano.com/documentation/channels

Example failure redirect. The `error` parameter is machine-readable (`access_denied` or `setup_failed`) and should be used for branching; `message` is a URL-encoded, human-readable explanation that may change and must never be parsed or used for branching.

```text
https://yourapp.com/callback?error=setup_failed&message=We%20couldn%27t%20access%20any%20Instagram%20Business%20account...
Copy
```

--------------------------------

### GET /api/v1/channels

Source: https://fiwano.com/documentation/quickstart

Lists all channels associated with the authenticated account. Used to verify the API key and to check the status of connected channels.

```APIDOC
## GET /api/v1/channels

### Description
Lists all channels associated with the authenticated account. Used to verify the API key and to check the status of connected channels.

### Method
GET

### Endpoint
/api/v1/channels

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key, e.g., `mip_live_...`

### Response
#### Success Response (200)
- **channels** (array) - List of channel objects
- **total** (integer) - Total number of channels

#### Response Example
{
  "channels": [],
  "total": 0
}

#### Error Response (401)
Invalid or missing API key.

```

--------------------------------

### message.echo webhook payload for media message

Source: https://fiwano.com/documentation/webhooks

Example of a message.echo webhook payload for a media message. The media file is not delivered; data.media has null download_url and unavailable set to 'echo_media_not_supported'. Check media.download_url before fetching to handle this case.

```json
{
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient": "6543217890123456",
    "status": "sent",
    "type": "image",
    "caption": "Invoice photo",
    "media": {"media_id": null, "download_url": null, "unavailable": "echo_media_not_supported", "kind": "image"}
  }
}
```

--------------------------------

### GET /api/v1/subscriptions

Source: https://fiwano.com/documentation/subscriptions

Retrieves all subscriptions and aggregate slot availability for each channel type. Use this endpoint when an external service needs to decide whether it can start a new channel connection flow.

```APIDOC
## GET /api/v1/subscriptions

### Description
Retrieves all subscriptions and aggregate slot availability for each channel type. Use this endpoint when an external service needs to decide whether it can start a new channel connection flow.

### Method
GET

### Endpoint
/api/v1/subscriptions

### Parameters
#### Headers
- **X-API-Key** (string) - Required - API key for authentication.

### Request Example
```
curl -H "X-API-Key: $FIWANO_API_KEY" \
  https://fiwano.com/api/v1/subscriptions
```

### Response
#### Success Response (200)
- **available_slots** (object) - Aggregate slot availability per channel type. Each channel type has `total`, `starter`, and `pro` fields.
- **subscriptions** (array) - List of subscription objects. Each subscription has `id`, `status`, `source`, `tier`, `auto_renew`, and `assigned_channels`.

#### Response Example
```
{
  "available_slots": {
    "whatsapp": { "total": 0, "starter": 0, "pro": 0 },
    "instagram": { "total": 1, "starter": 0, "pro": 1 },
    "facebook": { "total": 1, "starter": 0, "pro": 1 }
  },
  "subscriptions": [
    {
      "id": "a1b2c3d4e5f67890",
      "status": "active",
      "source": "trial",
      "tier": "pro",
      "auto_renew": false,
      "assigned_channels": {
        "whatsapp": {
          "channel_id": "1111222233334444",
          "channel_type": "whatsapp",
          "name": "Acme Support",
          "is_active": false
        },
        "instagram": null,
        "facebook": null
      }
    }
  ]
}
```

### Notes
- Use `available_slots.<channel_type>.total > 0` as the signal that a new channel of that type can be connected.
- An inactive channel can still occupy a slot because Fiwano preserves the binding for reconnect.
- In `available_slots`, `total` is the sum of the currently free `starter` and `pro` slots for that channel type.
- In each subscription, `assigned_channels` shows which channel is assigned to the subscription for each type; `null` means no channel is assigned there.
- The reverse mapping is on the channel itself: `subscription.id` in `GET /api/v1/channels`.
- To move a channel to a different subscription, or to release a slot so another channel of the same type can take it, use `subscription_id` in `PATCH /api/v1/channels/{channel_id}` — see subscription slots.
```

--------------------------------

### WhatsApp message.received text example

Source: https://fiwano.com/documentation/webhooks

Example of a WhatsApp text message webhook. `data.from` is the sender's phone number without `+`; use it as `recipient` when replying.

```json
{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",
    "from_name": "John Doe",
    "type": "text",
    "text": "Hello!"
  }
}
```

--------------------------------

### Instagram message.received text example

Source: https://fiwano.com/documentation/webhooks

Example of an Instagram text message webhook. `data.from` is the IGSID; use it as `recipient` when replying. `from_name` is always `null` because Meta does not include sender name in IG webhooks.

```json
{
  "event": "message.received",
  "channel_id": "b2c3d4e5f6789012",
  "channel_type": "instagram",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "mid.xxx",
    "from": "6543217890123456",
    "from_name": null,
    "type": "text",
    "text": "Hi there!"
  }
}
```

--------------------------------

### List channels with curl using X-API-Key header

Source: https://fiwano.com/documentation/quickstart

Use this curl command to verify your API key works by listing your channels. A valid key on a fresh account returns 200 with an empty list; an invalid or missing key returns 401.

```bash
curl https://fiwano.com/api/v1/channels -H "X-API-Key: $FIWANO_API_KEY"
```

--------------------------------

### Facebook Messenger message.received text example

Source: https://fiwano.com/documentation/webhooks

Example of a Facebook Messenger text message webhook. `data.from` is the PSID; use it as `recipient` when replying. `from_name` is always `null` because Meta does not include sender name in FB webhooks.

```json
{
  "event": "message.received",
  "channel_id": "c3f8a1b2e4d56789",
  "channel_type": "facebook",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "mid.xxx",
    "from": "7890123456789012",
    "from_name": null,
    "type": "text",
    "text": "Hello from Messenger!"
  }
}
```

--------------------------------

### GET /api/v1/channels/{channel_id}/profile/{user_id}

Source: https://fiwano.com/documentation/webhooks

Retrieves profile information for a user on a specific channel. Use this endpoint to get the sender's name and avatar for Instagram and Facebook messages, as the sender's name is not included in webhooks for these channels.

```APIDOC
## GET /api/v1/channels/{channel_id}/profile/{user_id}

### Description
Retrieves the profile information for a user on a specific channel. Use this endpoint to get the sender's name and avatar for Instagram and Facebook messages, as the sender's name is not included in webhooks for these channels.

### Method
GET

### Endpoint
/api/v1/channels/{channel_id}/profile/{user_id}

### Parameters
#### Path Parameters
- **channel_id** (string) - Required - The ID of the channel (e.g., Instagram or Facebook channel).
- **user_id** (string) - Required - The user ID from the webhook's `data.from` value (IGSID for Instagram, PSID for Facebook).

### Response
#### Success Response (200)
- **username** (string) - Instagram username (Instagram only).
- **name** (string) - Display name (Instagram) or first name (Facebook).
- **profile_pic** (string) - URL to the profile picture (when available).
- **follower_count** (integer) - Number of followers (Instagram only).
- **is_verified_user** (boolean) - Whether the user is verified (Instagram only).
- **last_name** (string) - Last name (Facebook, when available).
- **cached** (boolean) - Indicates whether the response was served from cache.

#### Response Example
{
  "username": "john_doe",
  "name": "John",
  "profile_pic": "https://example.com/pic.jpg",
  "follower_count": 1234,
  "is_verified_user": false,
  "cached": false
}
```

--------------------------------

### GET /api/v1/media/{media_id}

Source: https://fiwano.com/documentation/quickstart

Downloads received media by its ID.

```APIDOC
## GET /api/v1/media/{media_id}

### Description
Downloads received media by its ID.

### Method
GET

### Endpoint
/api/v1/media/{media_id}

### Parameters
#### Path Parameters
- **media_id** (string) - Required - The unique identifier of the media.

### Response
#### Success Response (200)
Returns the media content.

```

--------------------------------

### Send a media message with curl

Source: https://fiwano.com/documentation/sending-messages

Use this curl command to send a media message via POST /api/v1/messages/send-media. Requires a Pro license. Meta fetches the file directly from media_url; Fiwano never downloads or stores it. Pass media_type (image, audio, video, document) and an HTTPS media_url. Use a signed URL for non-public content with expiry ≥ 20 min. Check success and status; permanent failures include Meta error_code (e.g., 131052). Recoverable failures return queued.

```bash
curl -X POST https://fiwano.com/api/v1/messages/send-media \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "recipient": "1234567890",
    "media_type": "image",
    "media_url": "https://my-bucket.s3.amazonaws.com/photo.jpg?X-Amz-Signature=...&X-Amz-Expires=1800",
    "caption": "Your order photo"
  }'

```

--------------------------------

### GET /api/v1/channels/{channel_id}

Source: https://fiwano.com/documentation/quickstart

Retrieves details of a specific channel by its ID.

```APIDOC
## GET /api/v1/channels/{channel_id}

### Description
Retrieves details of a specific channel by its ID.

### Method
GET

### Endpoint
/api/v1/channels/{channel_id}

### Parameters
#### Path Parameters
- **channel_id** (string) - Required - The unique identifier of the channel.

### Response
#### Success Response (200)
Returns the channel object with its details.

```

--------------------------------

### Template lifecycle diagram

Source: https://fiwano.com/documentation/templates

Shows the lifecycle of a WhatsApp template: Create leads to PENDING (Meta review, ~24h), then either APPROVED (sendable) or REJECTED (fix & resubmit).

```text
Create → PENDING (Meta review, ~24h) → APPROVED (sendable)
                                      → REJECTED (fix & resubmit)
```

--------------------------------

### GET /api/v1/subscriptions

Source: https://fiwano.com/documentation/api

Retrieves a list of all active subscriptions for the authenticated account.

```APIDOC
## GET /api/v1/subscriptions

### Description
List all subscriptions associated with the account.

### Method
GET

### Endpoint
https://fiwano.com/api/v1/subscriptions
```

--------------------------------

### message.received unsupported type (Starter license)

Source: https://fiwano.com/documentation/webhooks

Example webhook payload for a message.received event with type "unsupported" when the media file exists but the current license tier does not include it. The unsupported_type indicates the media type Pro would have delivered, and upgrade_required names the tier that unlocks it. Upgrade via the Billing page in the portal to receive full media content.

```json
{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",
    "from_name": "John Doe",
    "type": "unsupported",
    "unsupported_type": "image",
    "upgrade_required": "pro"
  }
}
```

--------------------------------

### GET /api/v1/redirects

Source: https://fiwano.com/documentation/quickstart

Lists whitelisted redirect URIs for the embedded OAuth flow.

```APIDOC
## GET /api/v1/redirects

### Description
Lists whitelisted redirect URIs for the embedded OAuth flow.

### Method
GET

### Endpoint
/api/v1/redirects

### Response
#### Success Response (200)
Returns a list of redirect URIs.

```

--------------------------------

### Replace a channel with a single subscription

Source: https://fiwano.com/documentation/channels

This workflow outlines the steps to replace an existing channel by deactivating it, freeing its subscription slot, and connecting a new Meta account.

```text
GET    /api/v1/subscriptions           → find the subscription and its occupied slot
DELETE /api/v1/channels/{old_id}       → deactivate the channel you are replacing
PATCH  /api/v1/channels/{old_id}       → {"subscription_id": ""} frees the slot
POST   /api/v1/channels/setup-url      → user connects the new Meta account
POST   /api/v1/channels/exchange-code  → new channel takes the free slot
```
Tokens:
Raw