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

# Set Up WhatsApp

> Connect your Twilio account and a Meta-approved number so Marcus can send WhatsApp messages on your behalf — a hands-on guide from zero to first send.

## What you'll build

By the end of this guide, **Marcus** will be able to send WhatsApp messages on
behalf of your company, with:

* A Meta-approved number (not your personal one)
* Meta's 24-hour messaging window respected automatically
* Reply tracking arriving in the chat
* A complete audit trail for every message

Estimated time: **45 minutes to 7 days** — Meta's number approval is the
bottleneck. The other steps take about 10 minutes.

## Prerequisites

<CardGroup cols={2}>
  <Card title="Twilio account" icon="user">
    Pay-as-you-go is enough. [twilio.com](https://twilio.com)
  </Card>

  <Card title="A new phone number" icon="phone">
    Preferably NOT a personal or team number. Use a number dedicated to the
    company.
  </Card>

  <Card title="Company documents" icon="file-lines">
    Company registration (CNPJ), legal name, and address. Meta verifies these
    before approving.
  </Card>

  <Card title="Verified domain (recommended)" icon="globe">
    Speeds up Meta approval. Not required, but helps avoid rejection.
  </Card>
</CardGroup>

## Step 1: Create a Twilio account

Go to [twilio.com](https://twilio.com) and sign up. The standard process
includes email and phone verification — nothing unusual here.

<Info>
  **New account vs. sub-account.** If you're already running other things on
  Twilio (OTP SMS, voice flows), consider creating a dedicated **sub-account**
  for Apollo Space. Billing isolation and permissions stay cleaner that way.
</Info>

## Step 2: Get your WhatsApp number approved

In the Twilio dashboard: **Develop → Messaging → Senders → WhatsApp
senders → Get started**.

Twilio walks you through a wizard:

1. Confirm company details (CNPJ, legal name, address)
2. Register the number (ideally a **new, dedicated** number)
3. Submit for Meta approval
4. Wait

<Warning>
  **Meta approval takes 2–7 business days.** Don't start this step the day
  before a launch. If this is your company's first WhatsApp Business number,
  Meta may request additional domain and company verification — that can extend
  to 14 days in sensitive cases.
</Warning>

**Expected result:** a Twilio email confirming "Sender approved" and the number
showing as **active** in the **Senders → WhatsApp** panel.

## Step 3: Create a Messaging Service

Still in Twilio: **Develop → Messaging → Services → Create new**.

| Field               | Suggested value                                           |
| ------------------- | --------------------------------------------------------- |
| **Friendly name**   | "Apollo Space Outbound" (or something identifiable)       |
| **Use case**        | Notifications / Marketing / Mixed (whichever fits)        |
| **Sender pool**     | Add the approved number from Step 2                       |
| **Inbound webhook** | Leave blank — Apollo Space fills this in when you connect |
| **Status callback** | Same — Apollo Space fills it in                           |

Save and **copy the Messaging Service SID** (format `MGxxxx...`). You'll paste
it into Apollo Space in Step 5.

## Step 4: Get your Account SID and Auth Token

In the Twilio dashboard, go to **Account Dashboard → Account Info**:

```
Account SID:   AC........................
Auth Token:    ········  (click to reveal)
```

<Warning>
  **The Auth Token is equivalent to the master password for your Twilio account.**
  Anyone with the token can send messages (and generate charges) on your behalf.
  Treat it like a password: never commit it to a public repo, never paste it in
  chat, never share it in a screenshot.

  If you suspect it has leaked, rotate it **immediately** in the Twilio dashboard
  and update it in Apollo Space.
</Warning>

## Step 5: Connect to Apollo Space

In Apollo Space: **Settings → Integrations → WhatsApp → Connect Twilio**.

Paste the three values:

| Field                     | Where to find it          |
| ------------------------- | ------------------------- |
| **Account SID**           | Step 4 (starts with `AC`) |
| **Auth Token**            | Step 4 (click to reveal)  |
| **Messaging Service SID** | Step 3 (starts with `MG`) |

Click **Connect**. Apollo Space handles the following automatically:

1. Validates the credentials against the Twilio API
2. Updates the **inbound webhook** and **status callback** on the Messaging
   Service to point at Apollo Space (you don't need to do this manually)
3. Marks the integration as **active**

**Expected result:** a **Connected** badge on the WhatsApp row in
**Settings → Integrations**.

## Step 6: Send a test message

In **Settings → Integrations → WhatsApp → Send test message**:

* Enter your own WhatsApp number as the recipient
* Choose a Meta-approved template (or free-form text if you've recently
  exchanged messages with this number)
* Click **Send**

The message arrives on your WhatsApp within seconds. Apollo Space logs the test
in your org's usage history.

<Tip>
  **No open 24-hour window? Use a template.** Since you've never messaged with
  the Apollo Space number before, you're outside Meta's 24-hour window. Apollo
  Space shows you the pre-approved templates from your Messaging Service. Pick
  any one — it's just to verify the integration works.
</Tip>

## Troubleshooting — common errors

| Error                                   | Likely cause                                    | How to fix                                                                          |
| --------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| **"Number not approved"**               | Meta hasn't approved yet, or approval expired   | Go to Twilio → check sender status. Re-submit if needed                             |
| **"Authentication failed"**             | Wrong Auth Token or token was rotated           | Check the Twilio dashboard; paste it again in Apollo Space                          |
| **"Messaging Service not found"**       | Wrong SID or service was deleted                | Confirm the `MGxxx...` value in the Twilio dashboard                                |
| **"Out of window — template required"** | Tried free-form text outside the 24-hour window | Use an approved template, or wait for a reply from the recipient to open the window |
| **"Number not in sender pool"**         | The number isn't in the Messaging Service pool  | Add the number to the pool in the Twilio dashboard                                  |

Where to find logs:

| System            | Where to look                                                    |
| ----------------- | ---------------------------------------------------------------- |
| **Apollo Space**  | Settings → Integrations → WhatsApp → Send history                |
| **Twilio**        | Develop → Messaging → Logs (shows Meta's response line by line)  |
| **Meta Business** | business.facebook.com → Quality Rating (number health over time) |

## Production tips

Before operating at real scale, it's worth reviewing these:

<AccordionGroup>
  <Accordion title="Credential rotation" icon="rotate">
    Rotate the Twilio **Auth Token**:

    * **Always** when someone with access leaves the team
    * **Periodically** (every 6 months is a reasonable cadence) for hygiene
    * **Immediately** if there's any suspicion of a leak

    Updating in Twilio and Apollo Space takes about 2 minutes. Marcus will be
    unavailable during those 2 minutes — schedule this during a low-traffic period.
  </Accordion>

  <Accordion title="Quality Rating in Meta Business" icon="signal">
    Meta assigns a **Quality Rating** to your number (green / yellow / red). If
    it drops to red:

    * You lose the right to initiate marketing conversations
    * You may receive a temporary number suspension
    * In extreme cases, a permanent ban

    What affects the rating: negative responses from recipients, mass opt-outs,
    reports. **Do not blast cold lists without warming up first.** Marcus follows
    a conservative cadence by default — don't override it arbitrarily.
  </Accordion>

  <Accordion title="Multiple numbers (scaling)" icon="layer-group">
    As volume grows, consider adding **multiple numbers to the same Messaging
    Service**. Twilio automatically distributes load and isolates the impact if
    one number is penalized.

    Cost: each approved number carries a monthly Twilio hosting fee, regardless
    of volume.
  </Accordion>

  <Accordion title="Approved templates" icon="file-check">
    Create templates **in your Twilio account**, not in Apollo Space. Why:

    * Twilio submits them to Meta and manages the approval cycle
    * Templates are available to any tool using the same Messaging Service (not
      just Apollo Space)
    * Apollo Space reads your approved templates automatically

    Good templates: utility or service (more permissive). Marketing templates
    require extra care around tone and opt-out handling.
  </Accordion>
</AccordionGroup>

## Disconnect

In **Settings → Integrations → WhatsApp → Disconnect**:

* Apollo Space removes the credentials from storage
* Apollo Space reverts the webhooks in Twilio (you'll need to point them at
  another endpoint afterward — Twilio does not allow an empty webhook)
* Active campaigns using WhatsApp **pause** until you reconnect

Your Twilio account and approved number **remain intact** — disconnecting from
Apollo Space does not touch your Twilio infrastructure.

## Next steps

<CardGroup cols={2}>
  <Card title="Marcus in action" icon="paper-plane" href="/en/agents/marcus">
    How the outbound agent operates the channel you just connected.
  </Card>

  <Card title="Outbound — feature" icon="paper-plane" href="/en/features/outbound">
    Campaign types, cadence, and metrics.
  </Card>

  <Card title="Costs" icon="star" href="/en/billing/stars">
    How WhatsApp usage factors into your org's billing.
  </Card>
</CardGroup>