Build notes · Platform
What survives when you move to the official WhatsApp API
Everyone leaving an unofficial WhatsApp library asks the same question first, and it is not about price or rate limits. It is: do I lose my history? The honest answer is yes, and most of the answers you will find are wrong in the flattering direction.
We shipped one of those wrong answers ourselves. Until this week two of our own pages said that moving between our desktop and cloud surfaces "does not mean losing your contacts or your history". Half of that was true. We found it by reading what Brazilian competitors say about migration, checked our own code, and corrected the claim in both languages. This note is the version we should have written first.
TL;DR
Contacts, groups and memberships transfer. In our implementation, in batches of 500, with an idempotency key, so a sync that dies halfway can be re-run without duplicating anything.
Conversation history does not transfer at all. Not slowly, not partially. Meta does not permit importing prior conversations into the Cloud API, so this is not a feature any vendor has failed to build.
The cost lands on your agents, not your customers. A returning customer does not know their thread is empty. The person answering them does.
The ledger
| What | Carries | Detail |
|---|---|---|
| Contacts | Yes | Batched 500 at a time. Phone number and phone hash written atomically rather than backfilled, so a half-finished sync leaves no rows that look complete and are not. |
| Groups | Yes | Same path, same batching. |
| Group memberships | Yes | Separate endpoint, so membership can be reconciled without re-sending every contact. |
| Conversation history | No | There is no message sync, in our software or anyone else's, because there is nothing on Meta's side to sync into. |
| Media in old threads | No | Follows the messages. Whatever holds them today is where they stay. |
| Your number's reputation | No | A new number on the Cloud API starts at the lowest messaging tier regardless of how long the old one ran. |
The idempotency detail is worth dwelling on if you are writing the migration yourself rather than buying it. A contact sync that fails at row 3,000 of 8,000 is the normal case, not the exception, and the difference between a migration you can retry and one you cannot is whether the request carried a key the server remembers.
The shape that makes a re-run safe
const requestId = sanitizeRequestId(body?.requestId || c.req.header('x-idempotency-key'));
const deduped = await loadDedupedSyncResponse(db, creatorId, 'contacts', requestId);Why the history limit is structural
It is tempting to read "you cannot bring your history" as a gap somebody will eventually close. It is not. The Cloud API has no endpoint that accepts historical messages, and there is no reason to expect one: a platform that let businesses write arbitrary past conversations into a customer's thread would be handing every bad actor a forgery tool.
So the limit sits on Meta's side of the boundary, which means it applies identically to us, to every BSP, and to whatever you would build yourself. A vendor claiming to migrate your history is describing its own database, not WhatsApp. That may still be useful, because being able to read the old conversations somewhere is worth something, but it is a different promise from the one it sounds like.
What the empty thread actually costs
The customer does not experience the gap. They message the same business at the same number and get an answer. Nothing on their screen says anything changed.
Your agent experiences all of it. A returning customer arrives with no visible context, and the agent asks a question the business already knew the answer to two weeks ago. That is a small indignity repeated across every thread for as long as it takes new history to accumulate, and it lands during the fortnight when everything else about the switch is also new.
There is no technical fix, so treat it as a staffing fact rather than a migration bug. Tell the team the first two weeks of threads will be thin, and keep the old surface readable while that passes rather than switching it off the same day. The migration itself is reversible in a way the team's confidence is not.
Running both is the safer shape
The unofficial library and the Cloud API are different numbers, so they can run side by side, and the parallel period is what removes most of the risk. The official number takes new conversations while the old number finishes the ones already open. Nobody messages a line that nothing is watching.
What you cannot do is point both at the same phone number. That is not a policy preference, it is the same conflict that produces the QR loop we wrote about after eleven of our own browser processes fought over one auth directory until WhatsApp logged the device out.
The one thing to do beforehand
Export your contacts, and verify the export somewhere other than the tool that produced it. Open the file. Count the rows. Check that the ones you would notice missing are present.
That list is the only asset in this whole exercise that both carries across and is genuinely yours, and it is also the thing people discover was incomplete at the least convenient moment. Everything else about a migration is recoverable. A contact list you cannot reconstruct is not.
Weighing the move?
Klaros runs both sides: whatsapp-web.js sessions on the desktop for personal numbers, and Meta's Cloud API for business numbers, on your own WhatsApp Business Account billed by Meta directly. That is why this note can be specific about what transfers. It is also why it can be specific about what does not.
+91 97893 77634 · you message first, so nothing reaches you without your say-so.
Questions about migrating to the official WhatsApp API
Can I keep my WhatsApp conversation history when I move to the Cloud API?
No. Meta does not permit importing prior conversations into the WhatsApp Cloud API, so no vendor can migrate them for you regardless of what its marketing says. Threads start empty on the official API and accumulate from your first message onward. Anyone promising to carry your history across is either describing their own database rather than WhatsApp, or is wrong.
What actually transfers when you migrate off an unofficial library?
Contacts, groups and group memberships. In our implementation those move in batches of 500 with an idempotency key, so a sync that fails partway can be re-run without creating duplicates, and phone number and phone hash are written atomically rather than backfilled afterwards. What does not move is the message history itself.
Does an empty thread matter on day one?
It matters most for the agent, not the customer. Someone answering a returning customer sees no prior context and has to ask questions the business already knew the answer to. The practical mitigation is not technical: brief the team that the first fortnight of threads will be thin, and keep the old surface readable while that passes.
Is it safe to run the unofficial library and the Cloud API at the same time?
They are different numbers, so yes, and running both in parallel is the lower-risk migration. The official number can take new conversations while the old number finishes the ones already open, which avoids the situation where a customer messages a line nobody is watching. What you cannot do is point both at the same phone number.
What should I do in the weeks before switching?
Export your contacts and verify the export outside the tool that produced it. That is the one asset that both carries across and is genuinely yours, and it is also the thing people discover is incomplete at the worst moment. Everything else about the switch is recoverable; a contact list you cannot reconstruct is not.
Written 3 September 2026, the same day we corrected the claim that prompted it. We append when the facts change. Related: the session that logged itself out 377 times, the broadcast that lost its tail, all build notes.