WhatsApp integration
Connect a WhatsApp Business number with Meta Embedded Signup. Messages to that number are routed to the connected bot, and the bot replies on WhatsApp as text, image attachments, or document attachments, depending on the tool output.
- Embedded Signup to link a WhatsApp Business number to a bot.
- Capture phone_number_id, WABA ID, display phone, access token, and two-step verification PIN.
- Auto-subscribe the webhook, register the phone, and store the PIN for future deregistration.
- Incoming WhatsApp messages reach the bot; audio and image messages are stored in Google Cloud Storage, transcribed, and used as the bot's incoming text.
- If Enable file uploads in chat is on for the bot, inbound WhatsApp images and PDF documents are also forwarded as file input in the bot prompt.
- If the bot runs the PDF generation tool successfully, WhatsApp replies with a document attachment plus a short confirmation message.
- If the bot runs the image generation tool successfully, WhatsApp replies with an image attachment.
- Workflows can also subscribe to inbound WhatsApp messages, including audio and image media metadata for downstream transcription.
- Image and audio payloads are stored in Google Cloud Storage and exposed under audio/image objects (url, mimeType, bytes).
- Recent conversations (last 30 minutes) with the same sender reuse the same thread for context.
- All conversations stay in the free support window and no templates are used, so the channel is fully free.
Bring these to the signup flow (no billing setup required):
- A Facebook account.
- A Facebook Business Account (you can create one during the Embedded Signup flow).
- A WhatsApp phone number to connect.
- Open the bot dashboard and go to the WhatsApp tab.
- Click Launch Embedded Signup to open Meta's popup.
- Select a Business Account and choose an existing number or create a new one.
- Finish Meta's setup guide so it returns the verification code and phone_number_id.
- Raian exchanges the code for a business token, subscribes the webhook to your WABA, registers the phone, and stores the PIN for later deregistration.
- The status card shows phone_number_id, WABA ID, display number, webhook subscription time, registration time, and connection time.
- Webhook: Meta posts to our webhook; we verify with a verify token and the app secret signature when present.
- Routing: Your phone number ID maps to the bot that connected it. If the sender has an active conversation in the last 30 minutes, that thread is reused for context.
- Workflows: If the number is attached to workflows, inbound messages trigger runs with payload fields like from, to, text, messageType, and audio/image metadata (url, mimeType, bytes) pointing to the stored file.
- Bot call: the incoming text is sent to the bot via the non-stream endpoint.
- Delivery: normal responses are sent as WhatsApp text messages (up to 4096 characters, with link previews off).
- PDF delivery: when the bot generates a PDF, Raian first sends the PDF as a WhatsApp document attachment, then sends a short confirmation text. If document delivery fails, a fallback text with the public file link is sent and logged.
- Image delivery: when the bot generates an image, Raian sends it as a WhatsApp image message. If image delivery fails, a fallback text with the public image link is sent and logged.
- Inbound file input: when file uploads are enabled on the bot, WhatsApp images and PDF documents are passed as file input (alongside text/transcription when present).
- Voice notes are transcribed and handled as incoming text, so the bot can reply normally and workflows can still run.
- From a personal WhatsApp account, send a message to the connected number.
- Confirm you receive a bot reply on WhatsApp; recent conversations reuse context within 30 minutes.
- Send a PDF file with a short prompt and confirm the bot uses that PDF as input when file uploads are enabled for the bot.
- Ask the bot to generate an image and confirm you receive it as a native WhatsApp image attachment.
- Ask the bot to generate a PDF and confirm you receive it as a WhatsApp document attachment (not only as a URL).
- Send a voice note and confirm it is transcribed and used as bot input text.
- Check Dashboard → Logs for the inbound message and reply details.
- If no reply arrives, confirm the WhatsApp tab shows the number registered and the token not expired; retry registration if Meta was rate limited.
- Use Disconnect WhatsApp to deregister the phone and unsubscribe the webhook; the stored PIN is sent to Meta.
- If Meta cannot deregister automatically, finish removal in WhatsApp Manager with the same PIN.
- To refresh an expired token, rerun Embedded Signup; the existing number is reused.
- You can also remove the app from Meta directly at connected apps.
- Popup blocked: allow popups for the dashboard domain and retry.
- Token expired or revoked: reconnect through Embedded Signup to issue a fresh access token.
- No replies: verify webhook token and ensure the phone shows as registered; retries may be needed if Meta rate limited registration.
- If the number already had a PIN, disable two-step authentication at WhatsApp Manager → Phone numbers, then reconnect.
- Need a full reset: disconnect in Raian, then remove the app or unshare the WABA in WhatsApp Manager, or remove it from connected apps.
Next up
Monitor logs and jobs to debug messages and imports.