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

# Whatsapp

By the end of this, messages people send to your WhatsApp number will land in Olanna. Your agent will answer them.

WhatsApp is owned by Meta, the company behind Facebook. So most of this happens on Meta's website, not in Olanna. Here is the whole job:

1. Set up an account with Meta.
2. Copy five things from Meta into a note.
3. Paste those five things into Olanna.
4. Tell Meta to start sending your messages to Olanna.

Set aside 20 to 30 minutes. Use a computer, not your phone.

<Note>
  Meta changes these pages now and then. A button might not be exactly where this guide says. Look for the words, not the place, and you will find it.
</Note>

### **Before you start**

You need a phone number that can receive WhatsApp messages. It must not be in use on the normal WhatsApp app or the WhatsApp Business app. A number can only be on one of them at a time. If yours is in use, take it off there first, or use a different number.

You also need an email address, if you do not have a Facebook or Meta account yet.

<Warning>
  Was this number connected to another company's WhatsApp service before? Turn off its two-step PIN first, or moving it here will fail.
</Warning>

### **Part 1: Open a blank note**

You are about to collect five things from Meta. Keep them in one place so you do not lose any.

Open a blank note on your computer. Leave it open in its own window.

Type these five lines into it. Fill each one in as you reach it.

```text theme={null}
Phone number ID:
WhatsApp Business Account ID:
Access token:
App secret:
Verify token:
```

### **Part 2: Set up your Meta business account**

Skip to Part 3 if you already have one. Meta calls it Meta Business Suite, or Business Manager. It is the same thing.

<Steps>
  <Step title="Open Meta's business site">
    Go to business.facebook.com.
  </Step>

  <Step title="Choose Create Account">
    The button is near the top of the page.
  </Step>

  <Step title="Type your name and email">
    Your business name, your own name, and your work email. Then choose **Submit**.
  </Step>

  <Step title="Add your business details">
    Address, phone number, and your website if you have one.
  </Step>

  <Step title="Confirm your email">
    Open the email Meta sends you and click the link in it.
  </Step>
</Steps>

This account sits above everything else you are about to do.

### **Part 3: Create a Meta app**

Meta will ask you to make something called an app. It is not an app anyone downloads. It is a box that holds your connection. Meta will not let Olanna handle your messages without one. You make it once, then leave it alone.

<Steps>
  <Step title="Go to Meta's developer site">
    Open developers.facebook.com.
  </Step>

  <Step title="Log in with the same account">
    Choose **Log In** at the top right. Use the same account as Part 2.
  </Step>

  <Step title="Start a new app">
    Choose **My Apps**, then **Create App**.
  </Step>

  <Step title="Pick Business as the type">
    Meta asks what type of app this is. Choose **Business**.
  </Step>

  <Step title="Name it after your business">
    Something you will recognise in a year, like "Ridgeway Plumbing Olanna".
  </Step>

  <Step title="Link your business account">
    Choose the one you made in Part 2.
  </Step>

  <Step title="Finish creating it">
    Choose **Create App**. Meta might ask for your password again. You will land on your app's dashboard.
  </Step>
</Steps>

### **Part 4: Add WhatsApp to your app**

<Steps>
  <Step title="Find the product list">
    On the dashboard, look for a list of products you can add. It is usually on the main screen, or under **Add Product** in the left menu.
  </Step>

  <Step title="Set up WhatsApp">
    Find **WhatsApp** in that list and choose **Set up**.

    <Frame caption="The product list. WhatsApp is one tile among many.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/01-add-product.png" alt="Meta's add products screen with WhatsApp in the list" />
    </Frame>
  </Step>

  <Step title="Keep the API Setup page open">
    You will land on a page called **API Setup**. Three of your five things come from here, so leave this tab where it is.
  </Step>

  <Step title="Add your phone number">
    Look for the words "Send and receive messages". Meta shows you a free test number of its own, and a button to add your own number. Add your own. Meta will text or call it with a code to check it is yours.

    <Frame caption="The API Setup page. Your own number goes in the From section.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/02-api-setup-number.png" alt="The API Setup page showing the From phone number section" />
    </Frame>
  </Step>
</Steps>

### **Part 5: Copy two ID numbers into your note**

An ID is a number Meta uses to tell one thing from another. Both of these are on the API Setup page you are already looking at.

**Phone number ID.** This sits just under your phone number. It is a long number and it is not your phone number. There is a copy button beside it.

<Frame caption="The phone number ID sits under your number and looks nothing like it.">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/03-phone-number-id.png" alt="The phone number ID field with its copy icon" />
</Frame>

**WhatsApp Business Account ID.** Usually near the top of the same page, or in your business settings. You do not have to have this one. But it lets Olanna show you clearer information later, so copy it if you can find it.

### **Part 6: Make your access token**

An access token is a long password. It is what lets Olanna into your WhatsApp.

Meta offers you one on the API Setup page already. Do not use that one. It stops working after a day and your WhatsApp would go quiet. Make one that lasts instead.

This part has the most steps of anything here. Go slowly.

<Steps>
  <Step title="Open System Users">
    Go to business.facebook.com. Choose **Settings**, then **Users**, then **System Users**.

    <Frame caption="System Users is buried under Settings, then Users.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/04-system-users.png" alt="The System Users page inside Meta business settings" />
    </Frame>
  </Step>

  <Step title="Add a system user">
    Choose **Add**. Name it "Olanna Integration". Set the role to **Admin**. Choose **Create System User**.
  </Step>

  <Step title="Give it your app">
    Choose **Add Assets**. Pick the app you made in Part 3. Give it **Full Control**.
  </Step>

  <Step title="Start a new token">
    Choose **Generate New Token**. Pick that same app.
  </Step>

  <Step title="Tick two permissions">
    You will see a list of permissions with tick boxes. Tick **whatsapp\_business\_messaging** and **whatsapp\_business\_management**. Leave the rest alone.
  </Step>

  <Step title="Generate it">
    Choose **Generate Token**. A long line of letters and numbers appears.

    <Frame caption="Two permissions ticked, the rest left alone.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/05-generate-token.png" alt="The generate token dialog with the two WhatsApp permissions ticked" />
    </Frame>
  </Step>

  <Step title="Copy it into your note">
    Do this before you close anything.

    <Warning>
      Meta shows this token once and never again. If you close the window without copying it, you will have to come back and make a new one. That is annoying, not serious.
    </Warning>
  </Step>
</Steps>

### **Part 7: Copy your app secret, then make up a verify token**

**App secret.** This is another password. It proves the app belongs to you.

<Steps>
  <Step title="Open your app">
    Go to developers.facebook.com and open the app you made.
  </Step>

  <Step title="Go to Settings, then Basic">
    Both are in the left menu.
  </Step>

  <Step title="Reveal the app secret">
    Find **App Secret** and choose **Show**. Meta might ask for your password.

    <Frame caption="App Secret stays hidden until you choose Show.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/06-app-secret.png" alt="The Settings Basic page with the App Secret field and Show button" />
    </Frame>
  </Step>

  <Step title="Copy it into your note">
    That is four of your five lines done.
  </Step>
</Steps>

**Verify token.** You make this one up yourself. It is not copied from anywhere. Any word or phrase will do, like `ridgeway-2026`.

Write it into your note exactly as you typed it. You will type the same thing in two places later, and they have to match.

Your note should now have all five lines filled in.

### **Part 8: Paste it all into Olanna**

<Steps>
  <Step title="Open Channels">
    In Olanna, choose **Channels** in the left menu.
  </Step>

  <Step title="Choose Connect on the WhatsApp row">
    A form opens with a box for each of your five things.
  </Step>

  <Step title="Copy your note into the boxes">
    Each line of your note goes in the box with the same name.

    <Frame caption="All five values from your note, in Olanna.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/07-olanna-connect-form.png" alt="Olanna's WhatsApp connect form with all five boxes filled in" />
    </Frame>
  </Step>

  <Step title="Choose Install">
    Olanna takes a few seconds to check with Meta that your access token really works with your phone number ID, and that your app secret belongs to the same app.
  </Step>
</Steps>

If it works, WhatsApp moves into your connected apps. It will say **Active**, or **Pending Setup**. Pending Setup is normal here, because there is one part left.

If it does not work, the message tells you which one did not match. It is nearly always the access token. Troubleshooting is at the bottom of this page.

### **Part 9: Tell Meta where to send your messages**

Meta now trusts Olanna. But it still does not know where to send your messages. This part gives it the address.

That address is called a webhook URL. It is a long web address. You copy it out of Olanna and paste it into Meta. Nothing will arrive until you do.

<Steps>
  <Step title="Copy your webhook URL from Olanna">
    On the Channels page, open your WhatsApp row and copy the **Webhook URL**.
  </Step>

  <Step title="Open Configuration in Meta">
    Go to developers.facebook.com, open your app, then **WhatsApp**, then **Configuration**.
  </Step>

  <Step title="Edit the webhook section">
    Find the **Webhook** section and choose **Edit**.
  </Step>

  <Step title="Paste in the address">
    Put the Webhook URL into the **Callback URL** box.
  </Step>

  <Step title="Type your verify token">
    In the **Verify Token** box, type the phrase you made up in Part 7. It has to match what is in Olanna exactly. Same capital letters. No spaces at either end.

    <Frame caption="Callback URL from Olanna, verify token from your note.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/08-webhook-config.png" alt="The WhatsApp Configuration page with Callback URL and Verify Token boxes" />
    </Frame>
  </Step>

  <Step title="Verify and save">
    Choose **Verify and Save**. If the two match, it confirms straight away. If not, go back and check the value saved in Olanna.
  </Step>

  <Step title="Switch on messages">
    Still on that page, find **Webhook fields** and choose **Manage**. Switch on **messages**.

    <Frame caption="Only messages needs to be on.">
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/olanna/images/whatsapp/09-webhook-fields.png" alt="The webhook fields list with messages switched on" />
    </Frame>
  </Step>
</Steps>

### **Part 10: Test it**

<Steps>
  <Step title="Use a different phone">
    Not the number you just connected. Open WhatsApp on it.
  </Step>

  <Step title="Send yourself a message">
    A short text message to your WhatsApp Business number.
  </Step>

  <Step title="Check your Olanna inbox">
    It should be there within a few seconds. If nothing arrives after a minute, see Troubleshooting.
  </Step>
</Steps>

<Note>
  Only text messages come through at the moment. If someone sends a photo or a voice note to your WhatsApp number, it will not appear in your Olanna inbox. That is expected, not a fault.
</Note>

You can close your note now. Or keep it somewhere safe, in case you ever need to connect again.

### **Questions**

<AccordionGroup>
  <Accordion title="Do I pay Meta anything for this?">
    WhatsApp gives you a number of free messages each month. After that, Meta charges you directly, based on how much you use. Their WhatsApp Business Platform pricing page has the current rates. Meta bills you for this, not Olanna.
  </Accordion>

  <Accordion title="How long does display name approval take?">
    It varies. Sometimes minutes, sometimes a day or two. You can usually send and receive before it finishes. Your business name may look different to customers until it is approved.
  </Accordion>

  <Accordion title="Can I use my personal WhatsApp number?">
    You can. But it has to come off the normal WhatsApp and WhatsApp Business apps first. A number cannot be on both at once.
  </Accordion>

  <Accordion title="Can I connect more than one WhatsApp number?">
    One number per business through this screen. Contact support if you need more.
  </Accordion>

  <Accordion title="I have no Meta or Facebook account at all. Where do I start?">
    Go to business.facebook.com and choose Create Account. It walks you through making a login as part of the process. That is Part 2 above.
  </Accordion>

  <Accordion title="Do I need to keep the Meta app after this?">
    Yes. It is what keeps the connection alive. You do not have to open it again, but do not delete it.
  </Accordion>
</AccordionGroup>

### **Troubleshooting**

<AccordionGroup>
  <Accordion title="Access token is not valid on either graph.facebook.com or graph.instagram.com">
    Your access token does not go with your phone number ID. Or it has expired or been deleted. Go back to Part 6 and make a new one. Then open the connection in Olanna, choose Edit, paste the new token, and save.
  </Accordion>

  <Accordion title="App Secret is incorrect for this app">
    The app secret came from a different Meta app than the one holding your phone number and token. Check you copied it from Settings, then Basic, on the same app you set WhatsApp up in.
  </Accordion>

  <Accordion title="Meta shows an error when I choose Verify and Save">
    The verify token you typed into Meta does not match the one saved in Olanna. A space on the end is the usual cause. Open your WhatsApp connection in Olanna, look at the exact value saved there, and type it into Meta again.
  </Accordion>

  <Accordion title="Everything says connected, but test messages never arrive">
    This is almost always Part 9. Either it was not finished, or messages was left switched off. Go to WhatsApp, then Configuration, then Webhook fields in Meta, and check that messages is on.
  </Accordion>

  <Accordion title="I sent a photo or a voice note and it did not show up">
    That is expected. Only text messages come into the inbox at the moment.
  </Accordion>

  <Accordion title="My number is stuck on Pending Setup">
    Olanna has your five values but Meta has not registered the address yet. Go and finish Part 9.
  </Accordion>

  <Accordion title="I lost my access token or app secret">
    Neither can be looked up once hidden. But you can make a new one from Part 6 or Part 7 and update it in Olanna. You will not lose your number or your messages.
  </Accordion>

  <Accordion title="Still stuck">
    Contact support. Tell us which part you are on, and the exact words of the error. A screenshot is best. Say whether this is a new WhatsApp number or one moved from another company.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.