WhatsApp connections

Overview

A connection is a WhatsApp number linked to ChatISP. Everything that arrives at that number becomes a conversation in the support panel, and everything the team, the AI or the flows reply goes out through it. The screen is in the Connections menu, with the subtitle WhatsApp numbers connected to the system, via QR or the official API.

There are two transports, which can be used separately or together on the same number:

When the same number is connected through both transports, ChatISP treats the pair as a single channel: one conversation per customer, no duplicate messages, and the outbound channel chosen by the policy the administrator defines. Details in QR and official API on the same number.

Who can use it

The screen requires the WhatsApp connections permission (description on the profiles screen: Connects and manages the system WhatsApp numbers.). Users without this permission do not see the menu. To define which numbers each agent works on, see Connections per agent.

Number limit per plan Plan limit

The contracted plan defines how many WhatsApp numbers the installation can have. The count is per number: a number connected through QR and the official API at the same time takes up only one slot. The screen header shows the meter in the format 2 of 4 WhatsApp numbers in your plan; when the cap is reached, it changes to Plan limit reached and the New connection button no longer appears.

How the screen is organized

Each number appears in a block. A number with a single transport appears in the Individual connection block (One support channel for this number.). A number with QR and the official API appears in the Linked connections block (QR code and Official API, one number and the same conversation.), with the phone number highlighted and the two cards side by side, the QR card first.

Each card shows the name you gave the connection, the status label, the type (App (QR code) or Official API), the phone number, the WhatsApp account name (or Unnamed) and the action buttons. The screen refreshes on its own every 10 seconds, so a disconnection made from the phone shows up without reloading.

Choosing the connection type

Click New connection. The window asks Choose how you want to connect WhatsApp: and offers four paths:

QR code or official API?

Connect with a QR code

ChatISP becomes a linked device of the number's WhatsApp, like WhatsApp Web. This works for both regular WhatsApp and WhatsApp Business.

1. In Connections, click New connection and choose App (QR code). The connection is created with the name WhatsApp (you can rename it later with Edit) and the Connect WhatsApp window opens on its own.
2. Wait for the code to appear. The window shows Waiting for the code to be scanned...
3. On the number's phone, open WhatsApp, tap Linked devices (under Settings or in the three-dot menu, depending on the device), then link a device, and point the camera at the code on the screen.
4. Once the scan is accepted, WhatsApp connected successfully. appears, the window closes and the card changes to Connected, already showing the phone number and the account name.

The WhatsApp code expires quickly. If nobody scans it in time, the window shows The code expired. Generate a new one to continue. and the Generate new code button. There is no need to close the window: click the button and scan the new code.

An existing QR connection that is disconnected has the Connect button on its card, which opens the same scanning window.

What happens when you connect

• Messages arriving at the number start coming into ChatISP and follow the support rules (flows, AI, queue and departments).
• The system checks whether there is already an official API connection with the same phone number. If there is, the two automatically become Linked connections.
• If the number has served customers before through another connection that was deleted, that number's old conversations, open and closed, are linked to it again. See Disconnect, delete and reconnect.
• If the account name did not come from WhatsApp on the first scan, the panel queries again on its own and fills in the card.

Server without access to WhatsApp

If, when requesting the code, the message The server could not reach WhatsApp. Check the server's internet access and try again. appears, the problem is in the network, not in the panel: the server cannot reach WhatsApp's servers over the internet (firewall, route or the ISP's DNS). Allow the server's outbound access and use Generate new code.

Meta official API

The Official WhatsApp API option connects a dedicated number to Meta's official platform through an assistant with Facebook login. There is no need to copy IDs or tokens: the assistant fetches the accounts, you pick the number and ChatISP configures the rest, including message receiving.

Number requirements

Before opening the assistant, the screen shows Official API requirements with the notice You need a dedicated number that is not in use in the phone WhatsApp app.

The Continue with Facebook button is only enabled after you check I have a dedicated number not in use in the phone WhatsApp app. If the number is already in the WhatsApp Business app and you want to keep it there, use coexistence.

Assistant step by step

The Connect WhatsApp Business assistant has four steps, shown at the top: Sign in, Authorize, Pick number and Done.

1. Click Continue with Facebook. A new tab opens with the Ravi Systems secure connection page. The panel says: We opened a secure Ravi Systems tab for you to sign in with Facebook. Finish the authorization there: as soon as you are done, this assistant continues on its own. If the browser blocks the tab, use the Open the connection page button.
2. In the new tab, sign in with the Facebook account of the person who administers the company in Meta Business Manager and follow Meta's screens: choose or create the business portfolio, the WhatsApp Business account and the number, and confirm the number.
3. When you finish in the tab, go back to ChatISP. The assistant detects the authorization on its own, shows Fetching your WhatsApp Business accounts... and lists the accounts and numbers found, each number with Meta's quality badge.
4. Click the desired number and then Connect selected number. The panel shows Setting up the connection..., creates the connection, turns on message receiving for the business account and finishes with WhatsApp connected!.

The authorization must be completed within 5 minutes after the tab is opened. After that, the assistant shows The authorization was not completed in time. Please try again. and the Try again button.

Assistant error messages

Receiving messages (webhook)

With the official API, customer messages arrive because Meta calls an address on your ChatISP (the Webhook address, visible in the Configure API window). The assistant subscribes this address on the business account automatically. For this to work, Meta must be able to reach the address over the internet, with HTTPS and a valid certificate.

• Self-hosted installation Configure a domain with a certificate for the server (see the Server page) before connecting the official API. A server reachable only on the internal network can send messages but cannot receive them.
• On ChatISP Cloud, the public address is already provided by Ravi Systems; there is nothing to configure.

If the receiving subscription fails at the end of the assistant, the assistant shows the reason returned by Meta and the connection card stays in Setup pending. Fix the cause (usually the server's public address) and use Configure API and Save to try the subscription again.

Existing Business number (coexistence)

Coexistence is the Meta feature that puts on the official API a number that is already in the WhatsApp Business app, without removing the number from the phone. The app keeps working and ChatISP starts talking through the official channel of the same number.

1. In New connection, choose Existing Business number.
2. Check I have the number in the WhatsApp Business app and the phone at hand and click Continue with Facebook.
3. In the Ravi Systems tab, sign in with Facebook and follow Meta's screens. In one of the steps Meta shows a QR code: scan that code in the WhatsApp Business app on the phone itself, as Meta's screen instructs.
4. Once the authorization is complete, ChatISP usually already receives the chosen number and finishes on its own. If it does not, it shows the list of accounts so you can pick the number, as in the regular flow.

On a coexistence number, voice calls over the official channel are not available: Meta only enables calls over the official channel on a dedicated number, without the app. The card shows Calls unavailable with the explanation. For calls on this number, use the QR side (see Voice and video calls).

Manual setup of the official API

For those who already have an app and Meta credentials (for example, a number already operated by another system), the Manual setup option creates an official API connection named WhatsApp Business and opens the Configure API window. The same window opens from the Configure API button on the card of any official API connection.

When you click Save, ChatISP tests the credentials right away and, if the token works, subscribes receiving on the business account. Possible notices:

Test connection

The Test connection button (official API cards with a configured number) repeats the check at any time: it validates the credentials, updates the phone number and account name, checks with Meta the call status and whether the number is in coexistence, and redoes the link with the QR connection of the same number, if any. It also measures the account health at Meta (block, limit by verification) and checks the receiving subscription, redoing it when needed (see Account health at Meta).

QR and official API on the same number

When a QR connection and an official API connection have the same phone number, ChatISP links them on its own (with or without the ninth digit) and starts treating them as a single support channel. This is the coexistence scenario: the number is in the WhatsApp Business app, connected to ChatISP through QR and also through the official API.

How the pair behaves

• One conversation per customer. The customer's message arrives through both channels, but enters the panel only once. Delivery and read receipts, quotes and reactions match the right message, whichever channel they come from.
• One channel on every screen. In filters, selectors, the agent profile and other lists, the number appears once. Only the Connections screen shows both cards, inside the Linked connections block, because that is where each transport is managed.
• The pair survives a QR outage. If the phone disconnects, the official API keeps serving the number's conversations. Only a different number scanning the QR breaks the link.
• A single plan slot. The pair counts as one number toward the plan limit.
• App features preserved. New conversations are tied to the QR side, which brings the contact photo and name and the edit, delete for everyone and react features.

Which channel each message goes out on

The channel choice follows the policy in the Channels and allowance tab under Settings. With the factory configuration (Use both connections with Prefer the QR and menus While there is free allowance):

The Official API only and QR only modes are strict: the system uses only the chosen channel, without falling back to the other. All options are explained in Settings, Channels and allowance tab.

24-hour window and approved templates

On the official API, Meta's rule applies: the business can send free-form messages (text, media, menu) only within 24 hours counted from the customer's last message. Each new message from the customer reopens the window for another 24 hours. Outside it, only message templates approved by Meta reach the customer.

What the agent sees

In a conversation on a number that has only the official API, with the window closed, the message box is locked with the text Outside the 24-hour window: send a template and the bar The official API 24-hour window has closed: until the customer replies, only an approved template reaches them. The Send template button opens the list of approved templates, with fields for the variables. Internal notes remain available. If Meta rejects a message because the window is closed, the panel warns Outside the official API 24-hour window. Send an approved template.

On a number with QR (on its own or linked to the API), none of this locks: free text goes out through QR.

Account templates

Templates are created and approved in the Meta WhatsApp Manager; ChatISP keeps a copy of the account's templates to use in the panel, in the billing schedule and in campaigns. On the official API card (with the business account ID filled in), the Templates button opens the list:

• Each template shows the name, language, status at Meta (for example APPROVED for approved), category and the text with the variables {{1}}, {{2}}...
• Sync with Meta fetches the updated list (the message confirms how many templates were synced). Templates deleted at Meta disappear from the list.
• Manage on Meta opens the template manager of your business account, where you create a template and submit it for approval.

Conversation starter templates

Not every template has the same purpose: some are made for bulk sending, others to bring the customer into a conversation. On the Meta Templates page, every card has the Conversation starter switch, saved on click. On, the template is offered when starting a conversation from the panel and in the Send template button once the 24-hour window closes. Off, it stays with the campaigns and billing reminders and the promotions. While no template of the connection is on, all of them appear everywhere. The Conversation starters filter shows only the marked ones, and the mark follows the copy when a template is duplicated.

When the local list is empty, the panel fetches the templates from Meta on its own the first time someone tries to send one. For sending from the panel, the approved templates without a media header (image, video or document in the header) apply, because the panel fills in only the text variables.

Official API allowance and costs

Meta charges per message sent through the official API, including within the 24-hour window, and grants 1,000 free service messages per month on each number. Templates are always paid. Messages sent through QR have no cost. ChatISP tracks this usage and lets the administrator decide how to spend the allowance.

Usage manager on the card

Each official API card with a configured number shows the Meta allowance panel:

• The bar and the caption {usado} of {limite} free messages used this month, with the total in numbers (for example, 640 / 1,000). From 80% of the limit onward, the panel changes color as a warning.
• When the allowance is exceeded, the bar gains a paid segment and N messages beyond the allowance · estimated amount to pay Meta: R$ X appears. The estimate uses the configured price per message and the most recent dollar exchange rate known to the system (without an exchange rate, it is shown in dollars).
• Templates sent (always paid): N shows how many templates went out in the month.
• The Set up link goes straight to the Channels and allowance tab under Settings.

Usage policy (summary)

In the Channels and allowance tab under Settings, the administrator chooses from clickable cards that save on click:

An In practice strip sums up in one sentence the effect of the chosen combination. The full explanation of each option is in Settings.

Channel policies affect linked numbers (QR and API on the same number). On a number that has only the official API, all messages go out through it and consume the allowance.

Connection card features

Besides the status and the main actions, the card holds settings that apply number by number.

Customer typing live (QR)

Available on QR cards, with the label Enabled or Disabled and the button to toggle it. The change takes effect immediately, without reconnecting (Done, the change is already live for this number.). It comes enabled.

With voice calls active on the number, the phone still does not ring for messages even with the feature disabled, because the calls line must stay available to receive calls.

Voice calls Plan feature

When the calls service is available in the installation and in the plan, each card gains the Voice calls panel, with the status and the Turn calls on or Turn calls off button:

• On the QR side, calls use a second linked device of the same number: when turning them on, you scan another QR code on the same phone. A code scanned on the phone of a different number is rejected and undone immediately. The messaging connection must be connected first.
• On the official API, there is no device: the feature is turned on for the number itself, at Meta, and only exists on a dedicated number (without coexistence).

Turning calls off does not affect messages. The full step by step is in Voice and video calls.

Knowledge base

Every card has the Knowledge base block with the label of the base the assistant uses on this number and the Change button, which opens Knowledge base of this number: tapping a base saves immediately and also applies to the twin channel of the same number. With no base, the label turns into an alert (None) and the button becomes Choose base; in that state the assistant serves without registered plans, terms and answers. With a single base in the installation, a new connection is served by it from the start. See Several bases: one per company.

Card buttons

Account health at Meta

Besides the state, the card of each official API connection shows what Meta itself says about the account. The panel checks Meta every hour (every 5 minutes when there is a problem) and whenever you click Test connection.

The Payment method button is always in the footer of the official API card, even without a notice, to add or replace the card at Meta at any time.

Connection statuses

The label at the top of the card shows the current status. For QR connections, the status is checked against the WhatsApp service on every screen refresh, so it reflects what is actually happening.

The calls panel has its own statuses (Calls off, Waiting for the scan, Calls on, Calls offline, Calls unavailable), independent of the messaging status.

Connections per agent

At ISPs with more than one number (for example, one for support and another for sales, or one per city), the manager can define which numbers each agent works on.

1. Open the Agents screen and edit the agent.
2. In the Connections field, check the numbers they work on. The on-screen hint sums up the rule: The agent only sees and receives the conversations and calls of the checked connections. None checked: they work on all of them.
3. Save. The Connections column in the agents list shows the choice (All when none is checked).

What the restriction covers

• Conversation list, opening a conversation and starting a new conversation from the panel: only on the checked numbers.
• Automatic distribution (round robin) and queue and transfer notices: the agent is only chosen or notified for conversations on their numbers.
• Voice calls: only those on their numbers.
• Sending automation: billing schedules and campaigns can only be created on the agent's numbers.
• Transferring or sharing a conversation with someone who does not work on that number is refused with This agent does not work on this conversation's connection.; the destination list already shows only those who can receive it.

The restriction applies to any access profile, including those with permission to see all conversations: whoever checked the boxes decided where the agent works. Linked numbers (QR and API) appear as a single entry, and checking the number covers both transports. Old conversations without a connection (from a deleted number) are not restricted. Contacts and reports follow only the profile permissions.

More about the agent profile in Users and profiles.

Disconnect, delete and reconnect the same number

The support history belongs to the number, not to the connection. Changing the phone, swapping QR for the official API or recreating the connection does not delete anything.

Disconnect (QR)

Disconnect removes ChatISP from WhatsApp's linked devices and deletes the stored session, so it does not come back on its own. If voice calls were active on the number, the calls device is removed as well. The card stays on the screen with the registered phone number, ready to Connect again. On a linked number, the official API keeps serving while the QR is offline.

Delete

Delete asks for the confirmation Delete this connection? Recorded conversations will be kept and linked automatically when the same number connects again, through QR Code or the official API. Upon confirming:

• If it is a connected QR, the device is first unlinked from WhatsApp; if calls were active, the calls device is too.
• Tickets, messages, events, internal notes, assignees, contacts and past calls are preserved.
• Campaigns that were sending through this connection are paused.
• The knowledge base is not deleted: it stays on the Knowledge base screen, on hold. ChatISP remembers, by number, which base and which flows served this connection.
• If the twin connection (the other transport of the same number) is still connected, it takes over the conversations immediately.
• With no transport for the number, the conversations remain available for viewing and internal notes, but the message box is locked with Waiting for the same number to connect.

Reconnect the same number

When the same number is connected again, through QR or the official API, the knowledge base and the flows that served the number come back on their own (as long as the base is still active and the new connection has no base chosen yet), and ChatISP automatically relinks all of that number's conversations, open and closed, and the message box unlocks on its own in open conversations, without reloading the page. This happens even if the first message arrives before anyone opens the Connections screen.

Taking the number to another system

The account connected through the official API belongs to your company, not to Ravi Systems. The number, the WhatsApp Business account and the message templates live in your Meta business portfolio and can be used in any system approved by Meta. ChatISP puts no barrier in the way out: we want customers for the quality of the service, never through technical lock-in.

API data

On the card of an official API connection, the discreet API data button opens a window with everything the new provider may ask for, each item with a Copy button:

• WhatsApp number and Verified name;
• Phone number ID;
• WhatsApp Business account and Business account ID;
• Business portfolio and Portfolio ID.

The window opens at once with what the panel already knows and then checks the data with Meta (Checking with Meta...). The access token is left out on purpose: it is tied to this installation and does not work in another system. The new provider generates its own when connecting the same account.

Migration step by step

1. If you want to keep the conversation history, take a ChatISP backup in Settings. The history stays with you; no system imports it through Meta.
2. In the new system, connect the number through Meta's signup (the same Facebook login used here). Sign in with the account that manages your portfolio and pick the same WhatsApp Business account and the same number. Approved templates follow the account.
3. Back in ChatISP, open API data and click Unlink from Ravi Systems. ChatISP cancels message delivery at Meta, erases the stored credential and removes the connection. The service history is kept, as in Delete.
4. If you prefer to do it at Meta, go to Business settings, Integrations, Connected apps and remove the ChatISP app. Then use Unlink from Ravi Systems or Delete in the panel.

Best practices

• Use clear names. Use Edit to name each connection by its role (for example, "Support" and "Sales"). That name is what the team sees in filters, conversations and sending automation.
• Keep the QR phone on and online. WhatsApp may disconnect linked devices when the main phone goes unused for a long time, so use WhatsApp on the phone from time to time.
• Keep the WhatsApp app updated on the number's phone, especially with coexistence, which requires an updated WhatsApp Business.
• Prefer the QR plus official API combination on the same number when you want menus with buttons and the billing card without spending the allowance on regular support.
• Keep an eye on the usage manager on the official API card and, if you want a margin, lower the monthly allowance in Settings so the system spares the API before the real limit.
• Create templates in advance in the Meta WhatsApp Manager, because approval is not immediate, and sync them under Templates.
• Prepare the public address before the official API on a self-hosted installation: domain and certificate configured in Server.
• Delete without fear when you need to switch transports. The history is kept and comes back on its own when the same number is connected.

Common problems