Threadline

Connecting WhatsApp Longest section

Threadline uses Meta's official WhatsApp Cloud API, not a third-party unofficial gateway. Most of the work is in Meta's dashboard, so follow the steps in order.

Keep Meta's dashboard and your Threadline panel open in two tabs. You will copy values back and forth.

In plain words

What this is. Connecting your WhatsApp Business number to Threadline, so messages sent to it arrive in your Inbox and the AI can answer them.

What you will end up with. Four values copied from Meta into Threadline (a phone number ID, a business account ID, an access token and an app secret), and two values copied from Threadline into Meta (a callback URL and a verify token).

How long it takes. About 20 minutes the first time, once the Meta app exists.

For what a channel is and how to manage one afterwards, see Channels.

1. Create your Meta app and add the WhatsApp use case

Everything below happens inside a Meta developer app, so this comes first.

  • No Meta app yet? Follow Create your Meta app and, on the use cases step, tick Connect with customers through WhatsApp. You can tick Messenger and Instagram on the same app, so you only do this once.
  • Already have an app (for example from Messenger or Instagram)? Open its Dashboard, click Add use cases, and add Connect with customers through WhatsApp.

When the app exists, its Dashboard lists "Customize the Connect with customers through WhatsApp use case". That is where the next step starts.

2. Collect the Phone number ID and Business Account ID

  1. In your Meta app, open Use cases in the left menu and click Customize next to Connect with customers through WhatsApp.
  2. In the left menu of that page, open Basic setup → Step 1. Try it out.
  3. Under Claim a WhatsApp test number you will see Meta's free test number (for example +1 555 …). Copy:
    • Phone Number ID: a long number shown next to the test number. It is not the phone number itself.
    • WhatsApp Business account ID: shown on the same line.

Use the small copy icon next to each value.

3. Get an access token

On the same screen, the Access token box says "Not generated yet". Click Generate token and copy the token.

This token expires after 24 hours. It is fine for a first test, but Threadline will seem to "break" the next day when it expires. For a real setup, make a permanent token. See Make the token permanent below.

4. Copy the App secret

  1. In the app's left menu, open App settings → Basic.
  2. Next to App secret, click Show and copy it.

Details are on Create your Meta app.

5. Create the channel in Threadline

  1. In Threadline, go to Channels and click Connect a channel.
  2. Fill in the dialog:
    • Channel type: WhatsApp
    • Name: anything you will recognise, for example "WhatsApp Support"
    • Assistant: pick one now, or choose it later from the channel's card (it decides which knowledge base the AI answers from)
    • Phone number ID and WhatsApp Business Account ID (step 2)
    • Access token (step 3)
    • App secret (step 4)
  3. Click Connect.

6. Copy the Callback URL and Verify token

Threadline opens the channel's page. A box called Finish setup in Meta's dashboard shows:

  • Callback URL
  • Verify token

Copy both with the copy buttons.

The Callback URL must be your real, public HTTPS address. If it starts with http://localhost, Meta cannot reach it. Install Threadline on your live domain first, then use the URL it shows there.

7. Register the webhook in Meta

  1. Back in Meta, open Use cases → Customize for WhatsApp, then Basic setup → Step 2. Production setup.
  2. Open Configure Webhooks.
  3. Paste the Callback URL and Verify token from Threadline.
  4. Click Verify and save. Meta calls your address once to check it. This only works over HTTPS with a matching verify token.
  5. Subscribe to the messages field, as Threadline's channel page says.

"Apps will only be able to receive test webhooks." Meta shows this warning on that screen. While your app is unpublished, real messages are not delivered, not even from admins, developers and testers. Only the test webhooks sent from Meta's dashboard arrive. To receive real messages, publish the app (App Dashboard → Publish).

Verification fails? The common causes are: the site is not on HTTPS yet, the Verify token was copied with extra spaces, or Site URL in Threadline does not match the domain you are using. See Troubleshooting.

8. Send a test message

Meta's free test number can only talk to phone numbers you have added as recipients, so add yours first.

  1. In Meta, open Use cases → Customize for WhatsApp, then Basic setup → Step 1. Try it out.
  2. Under Send a message from your test number, open Recipient and select a recipient number. Add your own WhatsApp number there. Meta may ask you to confirm it with a code.
  3. Choose a Message (for example Order Confirmation) and click Send message. It arrives on your phone from the test number.
  4. Reply from your phone to the test number.
  5. Open Threadline's Inbox. Your reply should appear within seconds, and, if the channel has an assistant with a knowledge base, get an AI answer.

Nothing shows in the Inbox? The most common reasons are an unpublished app (see the note in step 7), a stale cron (check the dashboard for a warning) or a webhook that was never verified. See Troubleshooting & FAQ.

Make the token permanent

The 24-hour token from step 3 is only for testing. A System User token does not expire.

  1. Go to business.facebook.com/settings for the business portfolio your app belongs to.
  2. Under Users → System Users, click Add, name it (for example "Threadline") and give it the Admin role.
  3. Click Add Assets, choose your app, and grant Full control.
  4. Click Generate New Token, choose your app, tick whatsapp_business_messaging and whatsapp_business_management, and generate.
  5. Copy it immediately. Meta shows it only once.
  6. In Threadline, open the channel, click Credentials, paste it into Access token and save. Leave the other fields empty to keep them.

Click-to-WhatsApp ads

When a customer taps your ad and writes to you, Meta tells us which ad it was. The conversation then shows a From an ad card with the ad's picture and headline, you can start automations for it (the trigger Someone starts a conversation from one of your ads, or the Only when the conversation came from an ad option of the message trigger), find those people in Contacts and segments, and see the results per ad in Reports → Ads.

Good to know

  • Nothing needs setting up for this beyond a connected WhatsApp number. The ad information arrives with the customer's first message.
  • Ads shown in WhatsApp Status do not carry a click id, so they appear in the report but cannot be reported back to Meta.

Tell Meta what the ad achieved (optional)

Under Settings → Conversions you can report sales and leads back to Meta, so it can show your ads to similar people. You need your Meta dataset ID and a token with the whatsapp_business_management and whatsapp_business_manage_events permissions. Turn it on and choose what to send: a purchase when a deal is won or a store order arrives, and a lead when a lead form is completed. Only people with a click id from the ad are reported, each result once. The page lists what was sent and any answer Meta refused.

Keep using the WhatsApp Business app (Coexistence)

If you already chat with customers in the WhatsApp Business app on your phone, you can connect that same number and keep the app. This is called Coexistence.

What you need

  • The number is registered in the WhatsApp Business app (version 2.24.17 or newer), and the app is on your phone.
  • Your platform owner has turned Coexistence on. If you do not see the button, ask them.
  • The number's country supports Coexistence. Meta decides this and can change it.

Connect it

  1. Open Channels and press Connect the number I use in the WhatsApp Business app.
  2. Sign in with Facebook and follow Meta's steps. You scan a QR code with your WhatsApp Business app.
  3. Choose whether to share your past chats. Sharing is optional.

What happens next

  • The channel shows Phone app linked. Messages you type on the phone appear in the Inbox as From the phone app.
  • When you answer a customer from the phone, the AI stays quiet on that conversation for 12 hours.
  • Past chats (up to six months) and your phone contacts are copied in the background. Old chats are stored in closed conversations and never trigger the AI, an automation or a notification. You can follow progress on the channel page.
  • Meta only allows the contact and history copy in the first 24 hours after you link. If it fails after that, disconnect the channel and connect the number again.

Limits to know

  • Sending is limited to about 20 messages a second.
  • Open the WhatsApp Business app at least every 14 days, or Meta unlinks the number.
  • Some app features stop working on a linked number, such as broadcast lists, view-once media and live location.
  • Group chats are not copied.

Going live with a real business number

Everything above also works with your real WhatsApp Business number. Add it in Meta under WhatsApp → API Setup → Add phone number, then use that number's Phone Number ID in Threadline. Meta requires business verification before a real number can message customers who have not written to you in the last 24 hours. That process is entirely on Meta's side. To let your clients connect with one click, see the Owner guide.