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

# Quick Start

> Set up your account and send your first WhatsApp message in under 5 minutes ⏲️

## Before you begin

You'll need three things in place before making your first API call:

<AccordionGroup>
  <Accordion title="Connectly account & API key">
    You need a Connectly business account and a **business ID** to scope your API requests. Your **API key** authenticates every request — contact your Account Manager if you don't have one yet, or generate one from the Connectly Dashboard at any time.

    <Warning>
      Keep your API key secret. Never commit it to source control or expose it in client-side code. If a key is compromised, regenerate it immediately from the Dashboard.
    </Warning>
  </Accordion>

  <Accordion title="Facebook Business Manager">
    You need a **verified Facebook Business Manager account** with admin access. Meta uses this to own and manage your WhatsApp Business Account, and to review and approve your message templates.
  </Accordion>

  <Accordion title="WhatsApp Business Account (WABA)">
    A WABA is required to send and receive WhatsApp messages as a business. Connectly is a WhatsApp BSP (Business Service Provider) and can onboard you directly from the Connectly inbox. To register a WABA you'll need:

    | Resource                           | Purpose                                                        |
    | ---------------------------------- | -------------------------------------------------------------- |
    | Facebook Page                      | Required by Meta to link your business presence to your WABA.  |
    | Facebook Business Manager          | Where your WABA lives and your templates are managed.          |
    | Phone number (SMS or call capable) | Used for one-time verification of your WhatsApp sender number. |

    Your Account Manager will walk you through the registration once these are in place.
  </Accordion>
</AccordionGroup>

***

## Step 1: Authenticate your requests

Every Connectly API request must include your API key as an `X-API-Key` header. There are no session tokens or OAuth flows — just a single header on every call.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages \
    --header 'Content-Type: application/json' \
    --header 'X-API-Key: <YOUR_KEY_HERE>' \
    --data '{}'
  ```

  ```python Python theme={null}
  import requests
   
  headers = {
      "Content-Type": "application/json",
      "X-API-Key": "<YOUR_KEY_HERE>"
  }
   
  response = requests.post(
      "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
      headers=headers,
      json={}
  )
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
   
  const headers = {
      "Content-Type": "application/json",
      "X-API-Key": "<YOUR_KEY_HERE>"
  };
   
  axios.post(
      "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
      {},
      { headers }
  );
  ```
</CodeGroup>

Any request missing a valid `X-API-Key` header returns an `ERROR_TYPE_AUTHENTICATION` error.

***

## Step 2: Send a template message

Template messages are pre-approved message formats managed in your Facebook Business Manager. They are not subject to the 24-hour reply window — you can send them to any customer at any time, even if they have never messaged you before.

<Info>
  Your template must be created and approved in [Facebook Business Manager](https://business.facebook.com) before you can use it in an API call. Contact the Connectly team if you need help getting a template approved.
</Info>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages \
    --header 'Content-Type: application/json' \
    --header 'X-API-Key: <YOUR_KEY_HERE>' \
    --data '{
      "number": "+1XXXXXXXXXX",
      "templateName": "your_template_name",
      "language": "en_US",
      "parameters": [
        { "name": "body_1", "value": "John" },
        { "name": "body_2", "value": "your order" }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests
   
  payload = {
      "number": "+1XXXXXXXXXX",
      "templateName": "your_template_name",
      "language": "en_US",
      "parameters": [
          { "name": "body_1", "value": "John" },
          { "name": "body_2", "value": "your order" }
      ]
  }
   
  response = requests.post(
      "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
      headers={ "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" },
      json=payload
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
   
  const payload = {
    number: "+1XXXXXXXXXX",
    templateName: "your_template_name",
    language: "en_US",
    parameters: [
      { name: "body_1", value: "John" },
      { name: "body_2", value: "your order" }
    ]
  };
   
  axios.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/whatsapp_templated_messages",
    payload,
    { headers: { "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" } }
  ).then(r => console.log(r.data));
  ```
</CodeGroup>

**Request fields**

| Field          | Type   | Description                                                                          |
| -------------- | ------ | ------------------------------------------------------------------------------------ |
| `number`       | string | Recipient's WhatsApp number in E.164 format (e.g. `+1XXXXXXXXXX`).                   |
| `templateName` | string | Exact name of the approved template in your WhatsApp Manager.                        |
| `language`     | string | Language code for the template translation (e.g. `en_US`, `pt_BR`, `es`).            |
| `parameters`   | array  | Name/value pairs that substitute variables in the template body, header, or buttons. |

**Response**

```json theme={null}
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
```

The `id` is your message ID. Use it to correlate delivery status events if you're subscribed to [webhooks](/message-api/webhook-api).

***

## Step 3: Reply with a session message

Once a customer messages you, a **24-hour session window** opens. During that window you can send free-form session messages — no template or pre-approval needed.

<Warning>
  If the customer hasn't messaged you in the last 24 hours — or has never messaged you at all — you must use a template message instead. The session endpoint will return an error outside this window.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.connectly.ai/v1/businesses/<business_id>/send/messages \
    --header 'Content-Type: application/json' \
    --header 'X-API-Key: <YOUR_KEY_HERE>' \
    --data '{
      "recipient": {
        "id": "+1XXXXXXXXXX",
        "channelType": "whatsapp"
      },
      "message": {
        "text": "Hello! How can we help you today?"
      }
    }'
  ```

  ```python Python theme={null}
  import requests
   
  payload = {
      "recipient": {
          "id": "+1XXXXXXXXXX",
          "channelType": "whatsapp"
      },
      "message": {
          "text": "Hello! How can we help you today?"
      }
  }
   
  response = requests.post(
      "https://api.connectly.ai/v1/businesses/<business_id>/send/messages",
      headers={ "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" },
      json=payload
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');
   
  const payload = {
    recipient: { id: "+1XXXXXXXXXX", channelType: "whatsapp" },
    message: { text: "Hello! How can we help you today?" }
  };
   
  axios.post(
    "https://api.connectly.ai/v1/businesses/<business_id>/send/messages",
    payload,
    { headers: { "Content-Type": "application/json", "X-API-Key": "<YOUR_KEY_HERE>" } }
  ).then(r => console.log(r.data));
  ```
</CodeGroup>

**Response**

```json theme={null}
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
```

<Info>
  Add an optional `sender` object (`{ "id": "+14151111234", "channelType": "whatsapp" }`) to choose which of your WhatsApp numbers sends the message. If omitted, Connectly uses your default number.
</Info>

***

## Which message type should I use?

| Situation                                     | Use              |
| --------------------------------------------- | ---------------- |
| First message to a customer                   | Template message |
| Customer hasn't replied in over 24 hours      | Template message |
| Replying within the 24-hour window            | Session message  |
| Proactive notifications, campaigns, reminders | Template message |
| Bulk send to many recipients at once          | Campaigns API    |