HopeChat Docs
All guides

Connect WhatsApp

Connect your official WhatsApp Business number to HopeChat so customers can reach you and automations can reply instantly.

What you need

HopeChat uses the official Meta WhatsApp Business API (Cloud API), which lives in your Meta business ecosystem. To connect it you need three values from Meta plus your webhook URL:

Phone Number ID

A numeric ID for your WhatsApp number

WhatsApp Business Account ID

A numeric ID for your business account

Permanent Access Token

A long-lived system-user token

Webhook Callback URL

Auto-shown in Settings → WhatsApp Config

Step 1 — Have the Meta prerequisites ready

These one-time setup steps happen in Meta, not in HopeChat. If you already have a Meta business app with the WhatsApp product added, skip to step 2.

  • Go to developers.facebook.com, open My Apps, and click Create App. Choose Business as the app type.
  • In your app dashboard, click Add Product, find WhatsApp, and click Set Up. Follow the wizard to connect your WhatsApp Business number.
  • Under WhatsApp → API Setup you'll find your Phone Number ID and WhatsApp Business Account ID.
  • Generate a Permanent Access Token from Business Settings → System Users.

Step 2 — Enter credentials in HopeChat

  1. 1

    Open WhatsApp Config

    From your dashboard go to Settings → WhatsApp Config. The screen shows your connection status at the top — "Not Connected" until setup completes.

  2. 2

    Paste your API credentials

    In the API Credentials card, enter your Phone Number ID, WhatsApp Business Account ID, and Permanent Access Token. The token is encrypted at rest — it's never stored in plain text.

  3. 3

    Save configuration

    Click Save Configuration. HopeChat verifies the credentials by pinging Meta and, on success, confirms which verified business the number belongs to (e.g. "Connected to Acme Corp").

  4. 4

    Configure the webhook

    Copy the Webhook Callback URL shown on this screen — it follows the form https://your-domain/api/whatsapp/webhook. In your Meta app, under WhatsApp → Configuration → Webhook, click Edit, paste the URL, enter the Verify Token provided by your system admin, and subscribe to the messages webhook field. If you had to change anything, click Verify and Save.

  5. 5

    Test the connection

    Back in HopeChat, click Test API Connection. The status card should flip to Connected, and your number can now send and receive messages.

Using your existing number

You can connect the same WhatsApp number you already use for your business — there's no new SIM and no lost history. HopeChat runs alongside the WhatsApp Business app on your phone through Meta's official coexistence model.

Troubleshooting

  • Stored token can't be decrypted— an amber banner appears when the saved token can't be read back. Use Reset Configuration and re-enter your credentials.
  • "Not Connected" after saving — the token may be invalid, expired, or lack the whatsapp_business_messaging and whatsapp_business_management permissions. Regenerate it in Meta. Fixes here: FAQ.
  • Messages not arriving — verify the webhook is set to the exact callback URL shown and subscribed to messages.
Keep your Permanent Access Token secret. HopeChat shields it after save — if you ever need to update your configuration, re-enter the token rather than relying on a masked value.

Next guide

Team & permissions

Invite your team and set what each role can do in the inbox.