Connect your WhatsApp number
TL;DR
- Your own number, Meta's official API. Orkestia connects a WhatsApp Business number through Meta's WhatsApp Cloud API. It is not an unofficial WhatsApp Web gateway, so your number is not at risk of being banned for using one.
- One conversation, two places. A message sent to your number lands in the person's DM with the actor in your app's chat. The actor answers as it does in the web chat, and the answer goes back on WhatsApp. Your team sees the same thread in the chat.
- Only people who linked their phone reach the actor. An end user signs in to your app, taps Conectar WhatsApp and sends a one-time
LINK-code from their phone. Messages from numbers that are not linked never reach the actor. - You pay Meta for WhatsApp, directly. The number lives in your own Meta Business account. Orkestia does not charge separately for WhatsApp messages.
- Organization admins connect numbers. Nobody else in your organization sees the buttons.
WhatsApp is in beta.
Before you start
| You need | Why |
|---|---|
| To be an organization admin | Connecting and binding a number is admin-only for now |
| An identity app with its chat enabled and published, and an actor attached | The number is bound to your app's chat and to the actor that answers. See Enable and publish and Actors in chat |
| A phone number that is not in use on the WhatsApp app (WhatsApp or WhatsApp Business on a phone) | Meta moves the number to the Cloud API. A number still active in the phone app cannot be registered; remove it from the app first, or use a new number |
| A Meta Business account | You can create it during the connection flow if you do not have one |
| A payment method on your Meta account | Meta bills you for the conversations and templates it charges for |
Connect a number
Coming SoonConectar número (Meta), the guided connection through Meta's own sign-up popup, is being enabled. Until it is, the button does not appear in the console. If your team already runs its own Meta app with WhatsApp, see Bring your own Meta app.
Open the WhatsApp section
In the console, open your identity app and choose the Atendimento tab (the app's chat). Scroll to WhatsApp.
Start the Meta flow
Click Conectar número (Meta). If the number already has a two-step verification PIN, type it (6 digits); otherwise leave it empty. Click Continuar com a Meta.
Finish in Meta's popup
A Meta window opens. Sign in with Facebook, create or choose your Meta Business account and WhatsApp Business account, then add or choose the phone number and verify it with the code Meta sends. When the popup closes, Orkestia creates the WhatsApp connection for that number.
Bind the number to your chat
The Ligar número de WhatsApp dialog opens with the new number selected. Choose:
- Ator que responde: the actor that answers WhatsApp messages;
- Quem pode falar: Somente números vinculados pelo app (only phones your end users linked);
- Resposta a números desconhecidos (optional): a short reply sent at most once a day to numbers that are not linked, for example how to link from your app.
Click Ligar número. The number appears in the list as Ativo.
To stop, click Desligar on the number. Contacts and history are kept.
What your end users do
Link their phone
In your app's chat, the person taps Conectar WhatsApp. The chat shows a one-time code (LINK- followed by 8 characters) and a link that opens WhatsApp with the code ready to send.
Send the code
They send the code to your number from the phone they want to use, within 15 minutes. Sending it from that phone is the proof that the phone is theirs.
Talk to the actor
From then on, what they write on WhatsApp reaches the actor, and the actor's answer comes back on WhatsApp. Buttons and choices the actor offers show up as WhatsApp buttons or lists. Images and documents up to 1 MiB come through as chat attachments.
They can unlink at any time from the same Conectar WhatsApp dialog (Desconectar).
The 24-hour window and templates
Meta only lets a business send free text to a person within 24 hours of that person's last message. After that, the only messages allowed are templates approved by Meta, and Meta charges for them.
- Replies to someone who just wrote are always inside the window.
- A message you start (a reminder, an alert) outside the window needs an approved template.
buzz.channel.whatsapp.notifysends free text inside the window and a template outside it, and only to people who accepted messages from you. - If an answer would go out after the window closed and no fallback template is set, it is not sent to WhatsApp, and a notice appears in the web thread instead.
- Manage templates with
whatsapp.template.list,whatsapp.template.get,whatsapp.template.createandwhatsapp.template.delete. Meta reviews every new template.
Opting out and back in
| The person writes | Effect |
|---|---|
PARAR, STOP or SAIR | Opted out: nothing more is sent to them on WhatsApp |
VOLTAR or START | Opted back in |
People can also accept messages you start from the Conectar WhatsApp dialog in the chat.
A person on your team takes over
A WhatsApp conversation is a DM in your chat, so anyone on your team with access to the chat can read it. When someone from your organization writes in that DM, the message goes to WhatsApp with their name in front, and the actor stays quiet in that conversation for 30 minutes (by default) so the people can talk. The usual "talk to someone" handoff works on WhatsApp too.
Who pays Meta
- Meta bills your Meta Business account for WhatsApp, at Meta's prices (WhatsApp pricing). Templates are charged per message by category (marketing, utility, authentication).
- Orkestia does not charge per WhatsApp message. The work behind a WhatsApp conversation is ordinary platform usage (workflow runs and storage) on your plan.
Bring your own Meta app
Teams that already run a Meta Business app with the WhatsApp product can connect a number by hand:
- In the console, go to Connections and add WhatsApp Cloud API (Meta). Fill in the Phone number ID and WhatsApp Business Account ID (Meta App Dashboard → WhatsApp → API Setup), a permanent System user access token, the App secret, a random Webhook verify token you choose, and optionally the App ID, Graph API version and Display phone number.
- Bind the number with Ligar número in the WhatsApp section of the Atendimento tab, as above. The result shows the URL de callback para o app da Meta.
- In your Meta app, under WhatsApp → Configuration → Webhook, set that callback URL and the same verify token, click Verify and save, and subscribe the messages field.
Ask your AI assistant
List the WhatsApp numbers bound to my chat space with buzz.channel.whatsapp.list and show which actor answers each one.
Check the health of my WhatsApp number with whatsapp.phone-number.get: quality rating and messaging tier.
List the approved WhatsApp templates on my number with whatsapp.template.list.
For AI agents
| Need | Do this |
|---|---|
| Bound numbers | buzz.channel.whatsapp.list (with space_uuid) or buzz.channel.whatsapp.get. Never guess a binding_uuid |
| Number health | whatsapp.phone-number.get (read-only) |
| Confirm with the user first | buzz.channel.whatsapp.bind, buzz.channel.whatsapp.unbind, buzz.channel.whatsapp.notify, every whatsapp.message.send-*, whatsapp.template.create / delete |
| Callers | Bind and unbind are for organization admins; end users only link, unlink and opt in through the chat |
| Outside the 24-hour window | Only a Meta-approved template can be sent |
Living Surfaces
A page of live cards that DGI grows, keeps current and retires by itself. Create, tick, signal, read, list, archive and crystallize a surface with dgi.surface.*, set its policy, run its heartbeat, and follow its patch stream over a WebSocket
What is DGI
Orkestia is Orkestia.dev. DGI is Orkestia's decision layer. It turns what a person asks into your organization's own workflows, and answers with live cards (forms, confirms, tables, charts) instead of prose. Where you can use it, what it does, and what it never does