> ## Documentation Index
> Fetch the complete documentation index at: https://docs.msgflash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fundamentals

> Core concepts to understand MsgFlash before integrating the API.

## Why this page exists

Most integration issues are not coding issues.

They usually come from unclear terms:

* what is an instance?
* what is the difference between `instanceId`, `name`, and `waNumber`?
* what is an API key?
* what is a webhook?
* what is a payload?

This page is a compact glossary you can keep open while integrating.

***

## System overview

MsgFlash connects three layers:

* your MsgFlash account
* one or more connected WhatsApp numbers
* your technical integrations (backend, WordPress, Zapier, etc.)

Typical flow:

1. Create a WhatsApp instance
2. Connect a real WhatsApp number to it
3. Generate an API key
4. Call MsgFlash API from your backend
5. MsgFlash sends through the selected instance

***

## WhatsApp instance

A **WhatsApp instance** is a WhatsApp number connected to MsgFlash.

It is **not**:

* a user
* an API key
* a template
* a campaign

Think of it as an independent sending channel.

***

## `instanceId` vs `name` vs `waNumber`

| Field        | Meaning                                |
| ------------ | -------------------------------------- |
| `instanceId` | technical identifier used in API calls |
| `name`       | human-readable label in the dashboard  |
| `waNumber`   | connected WhatsApp number              |

Example from `GET /api/v1/instances`:

```json theme={null}
{
  "data": [
    {
      "id": "d6f66e76-9e59-41a5-bba8-a45c7fb72bfc",
      "name": "Main Store",
      "waNumber": "2250715516311",
      "status": "connected"
    }
  ]
}
```

When sending a message, always use `id` as `instanceId`.

***

## API key

An **API key** is the secret used to authenticate your requests.

Example:

```txt theme={null}
msgf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Use it in request headers:

```txt theme={null}
x-api-key: msgf_live_...
```

Never expose it in public browser JavaScript or commit it to git.

***

## Webhook

A **webhook** is an endpoint in your system that MsgFlash calls automatically when events happen.

Example endpoint:

```txt theme={null}
https://my-app.com/webhooks/msgflash
```

This replaces polling loops for delivery/read/status events.

***

## Campaign vs scheduled message

* **Scheduled message**: one recipient, sent later
* **Campaign**: same message pattern to many recipients

Campaigns include an instance, audience, content, and timing rules.

***

## QR code

The QR code is used only to connect WhatsApp (like WhatsApp Web).

Flow:

1. Create instance
2. Scan QR code from phone
3. Instance becomes connected

It is not a sending method by itself.

***

## Quotas

A **quota** is a limit from your plan.

Examples:

* monthly messages
* monthly API requests
* max instances
* max API keys

Two quota families:

| Type            | Example                          |
| --------------- | -------------------------------- |
| monthly quotas  | messages, statuses, API requests |
| capacity limits | instances, API keys, webhooks    |

***

## Payload

A **payload** is the JSON body sent to or returned by the API.

Example send payload:

```json theme={null}
{
  "instanceId": "d6f66e76-9e59-41a5-bba8-a45c7fb72bfc",
  "to": "+2250715516311",
  "type": "text",
  "text": "Hello"
}
```

Example webhook payload:

```json theme={null}
{
  "event": "message.delivered",
  "data": {
    "messageId": "msg_uuid",
    "status": "delivered"
  }
}
```

***

## Quick glossary

* **Instance**: connected WhatsApp number
* **instanceId**: technical ID to send in API calls
* **API key**: secret used for auth
* **Webhook**: URL called by MsgFlash on events
* **Campaign**: one operation targeting many contacts
* **Scheduled message**: delayed single-recipient message
* **Quota**: allowed usage limits
* **Payload**: JSON body in requests/responses

***

## Go further

* [Quickstart](/quickstart)
* [Guide: Instances](/guides/instances)
* [Guide: Send message](/guides/send-message)
* [Guide: Webhooks](/guides/webhooks)