Connect Your WhatsApp Number

This guide walks you through connecting your phone number to Sydx AI using the WhatsApp Cloud API. By the end, you'll be able to send and receive WhatsApp messages directly from your Sydx AI inbox.

Before You Start

Make sure you've completed the Meta WABA Setup guide first. You'll need your Meta App, WABA ID, and a permanent Access Token ready.

Overview

Here's what we'll do:

Step	What	Time
1	Add your phone number to Meta	2 min
2	Verify with OTP	1 min
3	Find your Phone Number ID	1 min
4	Register the number for Cloud API	1 min
5	Configure webhooks	3 min
6	Subscribe your WABA to webhooks	1 min
7	Enter credentials in Sydx AI	2 min
8	Test everything	2 min

Total time: ~15 minutes

Step 1: Add Your Phone Number

Go to developers.facebook.com → Open your Meta App
In the left sidebar, click WhatsApp → API Setup
Under "Step 1: Select phone numbers", click Add phone number
Enter:
- Display Name — Your business name as it will appear to customers
  (e.g., "My Store Support")
- Phone Number — The number you want to use, with country code
  (e.g., +91 98765 43210)
- Business Category — Select the appropriate category
Click Next

Phone Number Requirements

The number must not be registered on WhatsApp (personal or business)
If it is, you'll need to delete the WhatsApp account from that number first
The number must be able to receive SMS or Voice calls for OTP verification

Step 2: Verify with OTP

Choose your verification method: SMS or Voice Call
You'll receive a 6-digit OTP on your phone number
Enter the OTP code on the Meta verification screen
Once verified, your number will show status: Verified ✅

Step 3: Find Your Correct Phone Number ID

This is a critical step. The Phone Number ID is what Meta uses to identify your number in API calls.

Using Graph API Explorer

Open the Graph API Explorer
Select your Meta App from the dropdown (top right)
Set the API version to v21.0 (recommended for stability)
Make this API call:

Method: GET
URL:
```
{YOUR_WABA_ID}/phone_numbers
```
Click Submit
In the response, find your phone number and note the id field:

{
  "data": [
    {
      "verified_name": "My Store Support",
      "display_phone_number": "+91 98765 43210",
      "id": "123456789012345"    ← This is your Phone Number ID
    }
  ]
}

Use the ID from This API Call

The Phone Number ID shown elsewhere in the Meta dashboard may sometimes differ. Always use the ID returned from this API call to avoid errors.

Step 4: Register the Number for Cloud API

This tells Meta you want to use this number via the Cloud API.

Using Graph API Explorer

In the Graph API Explorer:
- Method: POST
- URL: {YOUR_PHONE_NUMBER_ID}/register
- API Version: v21.0
Switch to the JSON tab under the URL and enter:

{
  "messaging_product": "whatsapp",
  "pin": "123456"
}

Click Submit
You should receive:

{
  "success": true
}

About the PIN

The pin is your chosen 6-digit PIN for two-step verification. Remember this PIN — you'll need it if you ever re-register the number. You can choose any 6-digit number.

Step 5: Configure Webhooks

Webhooks allow Sydx AI to receive messages and delivery updates from WhatsApp in real-time.

5.1: Get Your Webhook Details from Sydx AI

Log in to your Sydx AI account
Go to Settings → Meta Cloud API (or check your Workspace Setup page)
Note down:
- Callback URL — looks like: https://sydxai.com/api/v1/webhook/{your-tenant-id}
- Verify Token — a unique token automatically generated for your workspace

5.2: Enter Webhook in Meta Dashboard

In your Meta App, go to WhatsApp → Configuration
Under Webhook, click Edit
Paste in:
- Callback URL — Your Sydx AI webhook URL from step 5.1
- Verify Token — Your verify token from step 5.1
Click Verify and Save

If successful, Meta will confirm the webhook is verified ✅

On the same Configuration page, you'll see a list of webhook fields. Subscribe to:

Field	Toggle	Why It's Needed
messages	✅ Subscribe	Receive incoming messages + delivery/read receipts

About Delivery Receipts

There is no separate "message_deliveries" field. All delivery status updates (sent, delivered, read) are included within the messages webhook field. Just subscribing to messages is sufficient.

You can optionally subscribe to these for additional features:

message_template_status_update — Know when templates are approved/rejected
phone_number_quality_update — Monitor your number's quality rating

Don't Skip This Step!

This is the most important step and the most commonly missed one. Without it, your webhooks are configured but Meta won't actually deliver any messages to your server!

This step links your WhatsApp Business Account to your app's webhooks, telling Meta: "Send this WABA's events to this app."

Using Graph API Explorer

In the Graph API Explorer:
- Method: POST
- URL: {YOUR_WABA_ID}/subscribed_apps
- API Version: v21.0
Click Submit
You should receive:

{
  "success": true
}

Verify It Worked

To confirm the subscription is active, make a GET request to the same URL:

GET {YOUR_WABA_ID}/subscribed_apps

Your app should appear in the response.

Why Is This Needed?

Think of it this way:

Step 5 tells Meta where to send webhooks (the URL)
Step 6 tells Meta which account's events to send there

Without Step 6, Meta has the address but doesn't know what mail to deliver!

Step 7: Enter Credentials in Sydx AI

Now connect everything in your Sydx AI workspace.

Log in to Sydx AI
Go to Settings → Meta Cloud API (or complete the Workspace Setup wizard)
Enter the following:

Field	Value	Where You Got It
App ID	Your Meta App ID	App Dashboard → App Settings → Basic
App Secret	Your Meta App Secret	App Settings → Basic → Show
Access Token	System User permanent token	Created in WABA Setup
WABA ID	WhatsApp Business Account ID	Business Settings → WhatsApp Accounts
Phone Number ID	From Step 3 of this guide	Graph API: `GET /WABA_ID/phone_numbers`

Click Save & Verify

Sydx AI will validate your credentials and confirm the connection ✅

Step 8: Test Your Connection

Send a Test Message (Incoming)

From your personal WhatsApp, send a message (e.g., "Hello!") to your business number
Open the Sydx AI Inbox
The message should appear within a few seconds 🎉

Send a Reply (Outgoing)

In the Sydx AI Inbox, click on the received message
Type a reply and click Send
The reply should be delivered to the personal WhatsApp number

Check Delivery Status

After sending from Sydx AI:

✓ Single tick = Sent
✓✓ Double tick = Delivered
✓✓ Blue ticks = Read

These statuses update in real-time within the Sydx AI inbox.

Quick Reference: All Your IDs

Keep these handy for your records:

Item	Your Value
Meta App Name	_______________
App ID	_______________
WABA ID	_______________
Phone Number	_______________
Phone Number ID	_______________
Webhook Verify Token	(auto-generated by Sydx AI)

Troubleshooting

Messages Not Appearing in Inbox

I completed all steps but messages aren't showing up

Most likely cause: Step 6 (subscribed_apps) was missed.

Fix: Go to Graph API Explorer and run:

POST /{YOUR_WABA_ID}/subscribed_apps

This links your WABA to your app's webhook configuration.

Webhook verification fails

Possible causes:

The Verify Token you entered in Meta doesn't match the one in Sydx AI
Your Sydx AI server might be temporarily unreachable

Fix: Go to Sydx AI → Settings → Meta Cloud API, copy the Verify Token, and re-enter it in Meta → WhatsApp → Configuration → Webhook → Edit.

I get "Object does not exist" errors in Graph API

Cause: You're using the wrong Phone Number ID.

Fix: Run this API call to get the correct ID:

GET /{YOUR_WABA_ID}/phone_numbers

Use the id from the response — don't rely on IDs shown elsewhere in the dashboard.

I can receive messages but can't send replies

Possible causes:

Your Access Token may have expired (if using a temporary token)
The phone number isn't registered for Cloud API

Fix:

Generate a permanent System User token (see Meta WABA Setup)
Update the token in Sydx AI → Settings → Meta Cloud API
If needed, re-run the register step (Step 4 above)

Messages sent but not delivered (stuck on single tick)

Possible causes:

The recipient's number is incorrect
The 24-hour messaging window has expired (you can only send template messages outside the window)

Fix: If more than 24 hours have passed since the customer's last message, use an approved Message Template instead of a freeform text message.

Need Help?

If you're stuck at any step, reach out to us:

📧 Email: support@sydxai.com
💬 WhatsApp: Contact your account manager

This guide covers the WhatsApp Cloud API setup. For information about other Sydx AI features, check the Features Guide.

Overview​

Step 1: Add Your Phone Number​

Step 2: Verify with OTP​

Step 3: Find Your Correct Phone Number ID​

Using Graph API Explorer​

Step 4: Register the Number for Cloud API​

Using Graph API Explorer​

Step 5: Configure Webhooks​

5.1: Get Your Webhook Details from Sydx AI​

5.2: Enter Webhook in Meta Dashboard​

5.3: Subscribe to Webhook Events​

Step 6: Subscribe WABA to App Webhooks​

Using Graph API Explorer​

Verify It Worked​

Step 7: Enter Credentials in Sydx AI​

Step 8: Test Your Connection​

Send a Test Message (Incoming)​

Send a Reply (Outgoing)​

Check Delivery Status​

Quick Reference: All Your IDs​

Troubleshooting​

Messages Not Appearing in Inbox​

Need Help?​

Overview

Step 1: Add Your Phone Number

Step 2: Verify with OTP

Step 3: Find Your Correct Phone Number ID

Using Graph API Explorer

Step 4: Register the Number for Cloud API

Using Graph API Explorer

Step 5: Configure Webhooks

5.1: Get Your Webhook Details from Sydx AI

5.2: Enter Webhook in Meta Dashboard

5.3: Subscribe to Webhook Events

Step 6: Subscribe WABA to App Webhooks

Using Graph API Explorer

Verify It Worked

Step 7: Enter Credentials in Sydx AI

Step 8: Test Your Connection

Send a Test Message (Incoming)

Send a Reply (Outgoing)

Check Delivery Status

Quick Reference: All Your IDs

Troubleshooting

Messages Not Appearing in Inbox

Need Help?