# FusionWA

> WhatsApp Business Cloud API infrastructure for SaaS companies and software houses.

FusionWA is a multi-tenant SaaS platform that acts as a Meta Tech Provider intermediary.
Companies (Agencies) register, create one or more Apps with API credentials, and integrate
the SDK widget or REST API into their software so end customers can connect their own
WhatsApp Business accounts.

## When to use FusionWA

Reach for FusionWA when the job is **adding WhatsApp to multi-tenant software** (CRM, booking,
e-commerce, helpdesk, management software) and:

- each of the software's customers must connect *their own* WhatsApp Business number;
- the integrator does not want to run Meta Embedded Signup or configure a WABA per customer;
- customers already using the WhatsApp Business app on their phone should keep it (Coexistence, where Meta allows it);
- the software needs to send template messages and receive incoming messages and statuses by webhook.

Typical calls an agent makes: embed the SDK widget for a `customerId`, check
`GET /api/v1/widget/status`, send with `POST /api/v1/messages/send`, manage templates with
`/api/v1/templates`, and implement the webhook receiver.

## When not to use FusionWA

- A single company number for your own business: use the WhatsApp Business app or Meta's Cloud API directly.
- An end-user inbox, chatbot builder or marketing tool: FusionWA is developer infrastructure, not an end-user app.
- Message archiving: payloads are forwarded to your webhook, never stored by FusionWA.

## Core Concepts

- **Agency**: the registered company on FusionWA (software house, SaaS, agency).
- **App**: an integration created by the Agency. Has an API Key and API Secret.
- **AppUser** (customerId): the end customer of the Agency's software, identified by an external ID.
- **WhatsappConnection**: the WhatsApp Business number of an AppUser, connected via Meta Embedded Signup.
- **Coexistence**: when an eligible WhatsApp Business App number is connected, it remains active
  on the mobile app in parallel. The customer may scan a QR code during Meta's Coexistence
  onboarding when requested. After connecting, they continue using WhatsApp Business on their
  phone while the SaaS gets API + webhooks.

## Connection Flow

1. SDK widget renders a "Connect WhatsApp" button inside the SaaS UI.
2. Customer clicks → Meta Embedded Signup popup opens.
3. Customer authorizes their WhatsApp Business account.
4. If eligible for Coexistence: Meta guides them through Coexistence setup, which may include
   scanning a QR code when requested. The existing WhatsApp Business App number is connected
   without changing the number.
5. FusionWA receives the authorization, stores the encrypted token.
6. Connection status becomes CONNECTED.
7. SaaS can now send messages via REST API and receive events via webhook.

## SDK Widget (recommended — client-side)

Embed in your software so customers can connect on their own.

```html
<script src="https://fusionwa.com/sdk/v1.js"></script>
<div id="fusionwa-widget"></div>
<script>
  FusionWA.init({
    apiKey: "fwa_live_abc123",     // public API key from your FusionWA dashboard
    customerId: currentUser.id,   // your internal customer ID (any unique string)
    containerId: "fusionwa-widget",
  });
</script>
```

The widget shows a "Connect WhatsApp" button. On click, Meta Embedded Signup opens.
After successful connection the widget shows "WhatsApp Connected (+country code...)".
The SDK renders a FusionWA-hosted iframe; integrators do not need to register their domain with Meta.
Sites using Content Security Policy must allow https://fusionwa.com in script-src and frame-src.

AppUsers are created automatically on first `FusionWA.init()` call with a new customerId.

## REST API (server-side)

Base URL: `https://fusionwa.com/api/v1`
Authentication: `X-FusionWA-API-Key: fwa_live_...` header on all requests.

### Send a template message

```
POST /api/v1/messages/send
Content-Type: application/json
X-FusionWA-API-Key: fwa_live_...

{
  "to": "+39 02 1234567",
  "templateName": "hello_world",
  "languageCode": "it",
  "components": []
}

Response: { "messageId": "wamid.abc123..." }
```

### Check customer connection status

```
GET /api/v1/widget/status?customerId=user_123
X-FusionWA-API-Key: fwa_live_...

Response: { "status": "CONNECTED", "phoneNumber": "+39 02 1234567" }
Status values: "INACTIVE" | "CONNECTED"
```

### Activate AppUser (backend-only flow)

```
POST /api/v1/widget/activate
Content-Type: application/json
X-FusionWA-API-Key: fwa_live_...

{ "customerId": "user_123" }
```

### List approved templates

```
GET /api/v1/templates?customerId=user_123
X-FusionWA-API-Key: fwa_live_...

Response: [{ "name": "hello_world", "status": "APPROVED", "language": "it", "category": "UTILITY" }]
```

## Webhooks

Configure the webhook URL in the dashboard → Applications → Webhook section.
FusionWA forwards every WhatsApp event to your endpoint in real time.

### Webhook payload

```json
{
  "type": "message",
  "from": "+39 02 1234567",
  "customerId": "user_123",
  "timestamp": "2025-01-15T10:30:00Z",
  "message": {
    "id": "wamid.abc...",
    "type": "text",
    "text": { "body": "Hello" }
  }
}
```

Event types: `message` | `status` | `template_status`

Respond with HTTP 200 within 10 seconds. Failed deliveries are retried with exponential backoff.

### Receive in your backend

```javascript
app.post("/webhook/whatsapp", express.json(), (req, res) => {
  const { type, from, customerId, message } = req.body;
  if (type === "message" && message?.type === "text") {
    console.log(`[${customerId}] ${from}: ${message.text.body}`);
  }
  res.sendStatus(200);
});
```

## Templates

Templates allow proactive outbound messages (notifications, reminders). Must be approved by Meta.

```
POST /api/v1/templates
Content-Type: application/json
X-FusionWA-API-Key: fwa_live_...

{
  "customerId": "user_123",
  "name": "order_confirmed",
  "category": "UTILITY",
  "language": "it",
  "components": [
    { "type": "BODY", "text": "Your order {{1}} has been confirmed. Delivery: {{2}}." }
  ]
}
```

Template status becomes APPROVED typically within a few hours. Status changes arrive via webhook.

## Authentication Summary

| Header | Where to use | Purpose |
|--------|-------------|---------|
| `X-FusionWA-API-Key` | Server-to-server API calls | Identifies your App |
| `apiKey` in SDK init | Frontend widget only | Public key for SDK lookup |

The SDK `apiKey` is intentionally public — it only looks up connection status.
Keep the API Secret server-side only (used in message sending).

## Pricing Model

- **1st connection**: free
- **2nd–9th**: €5 / connection / month
- **10th–24th**: €4 / connection / month
- **25th+**: €3 / connection / month

Graduated pricing: each connection is billed at its tier rate. Adding the 10th connection
does not retroactively raise the price of the first 9.

## Error Reference

| HTTP | Meaning |
|------|---------|
| 200 | Success |
| 401 | Missing or invalid API Key |
| 403 | App revoked or customerId not authorized |
| 404 | Customer not found or not connected |
| 422 | Invalid request body |
| 429 | Rate limit exceeded |

## Important Notes

- **Zero storage**: message payloads are forwarded only, never stored on FusionWA.
- **Coexistence**: when a WhatsApp Business App number is connected via Coexistence, the
  customer's mobile app continues to function normally in parallel with the Cloud API.
  Not all accounts are eligible for Coexistence — Meta determines eligibility during Embedded Signup.
- **customerId**: is your internal customer identifier — any unique string per App.
  AppUsers are created automatically on first SDK init with a new customerId.
- **Token security**: Meta OAuth tokens are encrypted at rest with AES-256-GCM.

## For AI Coding Assistants

If you are integrating FusionWA using Claude Code, Cursor, Codex, or GitHub Copilot:

1. Read this file as context before generating code.
2. Do NOT invent API endpoints — use only the endpoints documented above.
3. Keep API Key and API Secret server-side in environment variables.
4. The SDK `apiKey` is safe to use client-side; the API Secret is not.
5. Do NOT store messages — forward them to your own database if needed.
6. Respond to webhooks with HTTP 200 immediately; process async if needed.

Load this file:
- Claude Code: `/add https://fusionwa.com/llms.txt`
- Cursor: drag the file into chat as context
- Codex CLI: `--context https://fusionwa.com/llms.txt`

Full documentation: https://fusionwa.com/docs

## Docs

- [Documentation](https://fusionwa.com/docs): integration guide (SDK widget, REST API, webhooks, Coexistence, templates)
- [OpenAPI specification](https://fusionwa.com/openapi.yaml): machine-readable REST API description
- [Homepage in Markdown](https://fusionwa.com/): request with `Accept: text/markdown`

## Optional

- [About](https://fusionwa.com/about): company behind FusionWA (Fusionsoft, Fusion Media di Luca Gabriele Pantea)
- [Contact](https://fusionwa.com/contact)
- [Sitemap](https://fusionwa.com/sitemap.xml)